ChatKit : présentation et installation

Vous avez construit un agent puissant avec le SDK. Il tourne parfaitement dans votre terminal — et personne d’autre que vous ne peut s’en servir. Maintenant, il faut le mettre entre les mains de vos utilisateurs. ChatKit est le SDK d’OpenAI pour déployer des agents dans votre produit : une interface de chat prête à l’emploi, personnalisable, avec des widgets interactifs et des actions utilisateur.

Qu’est-ce que ChatKit ?

ChatKit fournit des composants React (et vanilla JS) pour intégrer un agent dans n’importe quelle application web. Au lieu de construire une interface de chat depuis zéro, vous utilisez des composants pré-construits et les personnalisez. Le socle est une interface de chat complète avec historique, saisie et affichage des réponses, à laquelle s’ajoute un theming aux couleurs de votre charte graphique. Au-delà de la conversation textuelle, des widgets affichent des données riches — tableaux, graphiques, cartes — et des actions permettent à l’utilisateur d’interagir avec l’agent autrement qu’en tapant du texte. Le streaming est natif, ce qui donne l’expérience temps réel à laquelle vos utilisateurs sont désormais habitués.

Autrement dit, ChatKit vous fait économiser les semaines de travail front-end que représentent la gestion du défilement, des états de chargement, des messages partiels et des reconnexions.

Installation

ChatKit s’installe via npm :

npm install @openai/chatkit

Pour un projet React :

npm install @openai/chatkit react react-dom

Configuration de base

Créez un fichier de configuration pour connecter ChatKit à votre agent. Deux valeurs suffisent : votre clé API et l’identifiant de l’agent créé dans Agent Builder.

// chatkit.config.ts
import { ChatKit } from "@openai/chatkit";

const chatkit = new ChatKit({
  apiKey: process.env.OPENAI_API_KEY,
  agentId: "agent_votre_id",  // ID de l'agent créé dans Agent Builder
});

export default chatkit;

Intégration React basique

Voici le code minimal pour afficher un chat dans votre application React. Le ChatProvider porte la connexion à l’agent, ChatWindow affiche la conversation et MessageInput gère la saisie ; le conteneur en flex colonne avec une hauteur fixe suffit à obtenir une mise en page correcte.

import React from "react";
import { ChatProvider, ChatWindow, MessageInput } from "@openai/chatkit/react";

function App() {
  return (
    <ChatProvider agentId="agent_votre_id" apiKey={process.env.OPENAI_API_KEY}>
      <div style={{ height: "600px", display: "flex", flexDirection: "column" }}>
        <ChatWindow />
        <MessageInput placeholder="Posez votre question..." />
      </div>
    </ChatProvider>
  );
}

export default App;

Ces quelques lignes suffisent à obtenir une interface complète : l’historique des messages, la saisie de texte, le streaming des réponses et l’affichage des appels de tools. Ce dernier point mérite d’être souligné — l’utilisateur voit que l’agent consulte votre catalogue ou votre CRM, ce qui rend l’attente compréhensible au lieu d’être subie.

Architecture backend recommandée

Le code précédent est parfait pour un prototype et dangereux en production : la clé API y est exposée dans le bundle JavaScript, donc lisible par n’importe quel visiteur. En production, ne passez jamais votre clé API côté client. Créez un backend proxy qui héberge l’agent, reçoit les messages et relaie la réponse en flux d’événements.

# backend/main.py (FastAPI)
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from agents import Agent, Runner

app = FastAPI()

agent = Agent(
    name="Agent produit",
    instructions="Vous assistez les utilisateurs du produit.",
    model="gpt-5.6-terra",
)

@app.post("/api/chat")
async def chat(request: Request):
    body = await request.json()
    message = body["message"]
    historique = body.get("history", [])

    async def stream_response():
        result = Runner.run_streamed(agent, historique + [{"role": "user", "content": message}])
        async for event in result.stream_events():
            if event.type == "raw_response_event" and hasattr(event.data, "delta"):
                if event.data.delta:
                    yield f"data: {event.data.delta}\n\n"
        yield "data: [DONE]\n\n"

    return StreamingResponse(stream_response(), media_type="text/event-stream")

Côté frontend, la modification est minime : vous remplacez la clé et l’identifiant d’agent par l’adresse de votre endpoint. Cette bascule vous donne au passage un point de contrôle unique où appliquer authentification, quotas et journalisation.

<ChatProvider
  endpoint="/api/chat"
  // Pas de apiKey côté client !
>
  <ChatWindow />
  <MessageInput />
</ChatProvider>

Vanilla JavaScript

Tous les produits ne sont pas des applications React. Un site WordPress, une application Rails ou une page statique peuvent intégrer le même agent : ChatKit fonctionne aussi sans React, en chargeant le script et la feuille de style depuis le CDN puis en désignant le conteneur à remplir.

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.openai.com/chatkit/latest/chatkit.min.js"></script>
  <link rel="stylesheet" href="https://cdn.openai.com/chatkit/latest/chatkit.min.css" />
</head>
<body>
  <div id="chat-container" style="height: 600px;"></div>
  <script>
    const chat = OpenAI.ChatKit.create({
      container: document.getElementById("chat-container"),
      endpoint: "/api/chat",
    });
  </script>
</body>
</html>

Le meilleur premier exercice consiste à reprendre un agent des leçons précédentes, à l’exposer derrière l’endpoint /api/chat et à le brancher sur cette page HTML : vous aurez, en moins d’une heure, un agent réellement utilisable par quelqu’un d’autre que vous.

Points clés à retenir

ChatKit fournit des composants prêts à l’emploi pour intégrer un agent dans votre produit
Installez avec npm install @openai/chatkit
Le ChatProvider encapsule toute la logique de communication avec l’agent
En production, utilisez un backend proxy pour protéger votre clé API
Le streaming est natif : les réponses s’affichent en temps réel
ChatKit fonctionne avec React et en vanilla JavaScript