ChatKit : présentation et installation

Leçon réécrite le 3 novembre 2026. La version précédente décrivait une API qui n’existe pas : un objet new ChatKit({ apiKey, agentId }), des composants ChatProvider, ChatWindow et MessageInput, un module @openai/chatkit/react et un script cdn.openai.com/chatkit/…. Elle suit désormais les guides ChatKit d’OpenAI, le SDK Python openai-chatkit 1.6.5 et @openai/chatkit-react 1.6.1. Le serveur d’exemple a été exécuté en local pour vérification. Rappel : l’Agent Builder ferme le 30 novembre 2026, ChatKit reste disponible. Sources : ChatKit · Advanced integrations with ChatKit · démarrage rapide du SDK Python · application de démarrage officielle.

Pourquoi ChatKit

Vous avez construit un agent avec l’Agents SDK. Il tourne dans votre terminal, et personne d’autre que vous ne peut s’en servir. Pour le mettre entre les mains de vos utilisateurs, il lui faut une interface de conversation, et une bonne interface de chat coûte cher à construire : défilement, messages qui arrivent en flux, reprise d’une conversation, pièces jointes, affichage des appels d’outils, gestion des erreurs réseau.

ChatKit est la réponse d’OpenAI à ce problème : un composant de conversation à intégrer dans votre produit, qui prend en charge toute l’expérience utilisateur. La documentation met en avant ses widgets interactifs, les suggestions de démarrage, l’affichage des appels d’outils, les pièces jointes et la visualisation du raisonnement de l’agent. Vous gardez la main sur ce qui compte : l’agent, vos données et vos règles.

Deux façons de l’alimenter

ChatKit n’est qu’une interface. Il lui faut un serveur qui reçoit les messages, fait travailler l’agent et renvoie la réponse en flux. OpenAI en décrit deux :

Ce cours suit le premier parcours, le seul qui ait un avenir. Le second est résumé en fin de leçon pour ceux qui doivent maintenir une intégration existante d’ici sa fermeture.

L’architecture en trois pièces

Une intégration ChatKit tient en trois éléments, et les distinguer évite la plupart des erreurs de départ :

1. ChatKit.js, le composant lui-même : un élément web <openai-chatkit> qui affiche la conversation dans une iframe. Il se charge depuis le CDN d’OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), pas depuis npm : le paquet npm @openai/chatkit ne contient que ses définitions de types.
2. Les liaisons React, @openai/chatkit-react, qui exposent le composant ChatKit et le hook useChatKit. Elles sont facultatives : sans React, vous pilotez l’élément web directement.
3. Votre serveur ChatKit, un unique point d’accès HTTP, par convention /chatkit, qui reçoit toutes les requêtes de l’interface. Une instance de ChatKitServer les aiguille, s’appuie sur un store pour conserver les fils de discussion et fait répondre votre agent.

La clé d’API OpenAI ne quitte jamais le serveur : l’interface ne parle qu’à votre point d’accès /chatkit.

Installer

Côté interface, installez les liaisons React et chargez le script de ChatKit dans votre page :

npm install @openai/chatkit-react

<!-- Dans le <head> de votre page -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>

Côté serveur, installez le SDK Python de ChatKit (Python 3.10 ou plus récent), qui apporte avec lui l’Agents SDK, puis un serveur web :

pip install openai-chatkit fastapi uvicorn

Le serveur minimal

Le serveur ci-dessous suit le démarrage rapide officiel. ChatKitServer ne demande qu’une méthode, respond, appelée à chaque message de l’utilisateur. Elle relit les derniers éléments du fil de discussion, les convertit en entrée pour l’agent avec simple_to_agent_input, lance l’agent en flux et traduit ce flux en événements ChatKit avec stream_agent_response :

# main.py
from typing import Any, AsyncIterator

from agents import Agent, Runner
from chatkit.agents import AgentContext, simple_to_agent_input, stream_agent_response
from chatkit.server import ChatKitServer, StreamingResult
from chatkit.types import ThreadMetadata, ThreadStreamEvent, UserMessageItem
from fastapi import FastAPI, Request
from fastapi.responses import Response, StreamingResponse

from memory_store import MemoryStore  # store en mémoire de l'application de démarrage

assistant = Agent[AgentContext[dict[str, Any]]](
    name="Assistant produit",
    instructions="Vous aidez les utilisateurs du produit. Répondez en français, brièvement.",
    model="gpt-6.1-sol",
)


class MonServeurChatKit(ChatKitServer[dict[str, Any]]):
    async def respond(
        self,
        thread: ThreadMetadata,
        input_user_message: UserMessageItem | None,
        context: dict[str, Any],
    ) -> AsyncIterator[ThreadStreamEvent]:
        # Les 30 derniers éléments du fil, remis dans l'ordre chronologique
        page = await self.store.load_thread_items(
            thread.id, after=None, limit=30, order="desc", context=context
        )
        agent_input = await simple_to_agent_input(list(reversed(page.data)))
        agent_context = AgentContext(thread=thread, store=self.store, request_context=context)
        result = Runner.run_streamed(assistant, agent_input, context=agent_context)
        async for event in stream_agent_response(agent_context, result):
            yield event


app = FastAPI()
server = MonServeurChatKit(MemoryStore())


@app.post("/chatkit")
async def chatkit_endpoint(request: Request) -> Response:
    result = await server.process(await request.body(), {})
    if isinstance(result, StreamingResult):
        return StreamingResponse(result, media_type="text/event-stream")
    return Response(content=result.json, media_type="application/json")

Lancez-le avec OPENAI_API_KEY dans l’environnement : uvicorn main:app --port 8000.

Le store mérite deux mots. ChatKit ne garde rien de lui-même : fils, messages, widgets et appels d’outils sont enregistrés par une classe qui hérite de chatkit.store.Store et implémente une douzaine de méthodes (load_thread, save_thread, load_thread_items, add_thread_item…). Pour démarrer, reprenez le fichier memory_store.py de l’application de démarrage officielle : il garde tout en mémoire tant que le processus tourne. En production, remplacez-le par une base de données. La documentation conseille de stocker les objets en JSON, pour que les mises à jour du SDK ne vous imposent pas de migration de schéma.

L’interface React

Côté interface, useChatKit reçoit la configuration et renvoie un objet control, que vous passez au composant ChatKit :

import { ChatKit, useChatKit } from '@openai/chatkit-react';

export function Assistant() {
  const { control } = useChatKit({
    api: {
      url: '/chatkit',
      // En développement, une valeur de substitution suffit ; en production,
      // la clé de votre domaine (voir plus bas)
      domainKey: 'local-dev',
    },
  });

  return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}

Servez l’interface et /chatkit depuis la même origine : en développement, le proxy de votre outil de build s’en charge (l’application de démarrage configure celui de Vite pour rediriger /chatkit vers le port 8000). Si le serveur vit sur une autre origine, autorisez-la explicitement, par exemple avec le CORSMiddleware de FastAPI.

Sans React

Un site WordPress, une application Rails ou une page statique peuvent intégrer le même assistant : l’élément web s’utilise directement, une fois le script du CDN chargé.

<!doctype html>
<html lang="fr">
  <head>
    <meta charset="UTF-8" />
    <script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
  </head>
  <body>
    <div id="chat-root" style="height: 600px"></div>
    <script>
      const chatkit = document.createElement('openai-chatkit');
      chatkit.setOptions({
        api: { url: '/chatkit', domainKey: 'local-dev' },
      });
      document.getElementById('chat-root').append(chatkit);
    </script>
  </body>
</html>

Toutes les options que vous verrez dans les leçons suivantes ont la même forme dans les deux cas : un objet passé à useChatKit en React, ou à setOptions sur l’élément web.

La sécurité dès le premier jour

Trois règles, tirées du guide de mise en production de ChatKit, s’appliquent dès le prototype :

• La clé d’API reste sur le serveur. Elle ne doit apparaître ni dans le code de l’interface, ni dans le dépôt : elle se lit dans une variable d’environnement ou un gestionnaire de secrets.
• Authentifiez chaque requête à /chatkit. Le SDK ne s’en charge pas : c’est à votre application de vérifier la session ou le jeton de l’utilisateur, puis de transmettre son identité à server.process dans le contexte (leçon 21). Sans cela, n’importe qui peut faire travailler votre agent à vos frais.
• Enregistrez vos domaines. Avant la mise en ligne, déclarez chaque nom d’hôte qui affichera ChatKit sur la page Domain allowlist de la plateforme OpenAI, et copiez la clé générée dans domainKey. Au chargement, l’iframe de ChatKit vérifie cette clé auprès d’OpenAI et refuse de s’afficher si elle manque ou ne correspond pas.

Si vous avez déjà un workflow de l’Agent Builder

Les intégrations existantes branchées sur un workflow hébergé fonctionnent jusqu’à la fermeture de l’Agent Builder. Leur principe est différent : votre serveur crée une session ChatKit en appelant POST https://api.openai.com/v1/chatkit/sessions, avec l’en-tête OpenAI-Beta: chatkit_beta=v1, l’identifiant du workflow et un identifiant user propre à chaque utilisateur authentifié. Il renvoie ensuite à l’interface le client_secret obtenu. Côté interface, l’option api prend alors une fonction getClientSecret au lieu d’une URL.

Ne commencez pas de projet sur ce modèle. Pour une intégration existante, exportez le workflow en code Agents SDK et passez sur votre propre serveur ChatKit avant le 30 novembre 2026, en suivant le guide Migrate from Agent Builder.

Points clés à retenir

• ChatKit est une interface de conversation prête à intégrer ; c’est votre serveur qui fait répondre l’agent
• Pour tout nouveau projet : un serveur ChatKit à vous (pip install openai-chatkit), avec une méthode respond et un point d’accès /chatkit ; l’Agent Builder hébergé ferme le 30 novembre 2026
• L’interface se charge depuis le CDN d’OpenAI ; en React, useChatKit et <ChatKit control={control} /> de @openai/chatkit-react
• Le store conserve les fils de discussion : en mémoire pour essayer, en base de données en production
• Clé d’API côté serveur seulement, /chatkit authentifié, domaines enregistrés pour obtenir la domainKey