Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Intégration avancée dans ton application

Oppitunti 21 / 25 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Ce qu’il reste à faire après la démo
  2. Authentifier chaque requête
  3. Chaque utilisateur obtient ses propres conversations
  4. Donner ton contexte applicatif au modèle
  5. Outils côté client
  6. Piloter ChatKit depuis ton application
  7. Observer ce qui se passe
  8. Avant de passer en production
  9. Keskeiset asiat

Leçon réécrite le 3 novembre 2026. La version précédente reposait sur des propriétés et événements inventés (ChatProvider, mode « sidebar », persistance basée sur l’interface). Elle suit désormais les guides du SDK Python openai-chatkit 1.6.5 (Préparer ton application pour la production, Transmettre un contexte applicatif supplémentaire, Mettre à jour le client pendant une réponse) et les types @openai/chatkit-react 1.6.1 : le code serveur a été exécuté localement et le code React vérifié par compilation. Sources : Préparer ton application pour la production · Transmettre un contexte applicatif supplémentaire à ton modèle · Mettre à jour le client pendant une réponse · Intégrations avancées avec ChatKit.

Ce qu’il reste à faire après la démo

Les quatre dernières leçons t’ont fourni un assistant fonctionnel. Pour le rendre opérationnel dans un produit réel, il lui faut ce qui sépare une démo d’un service : savoir qui parle, n’afficher que les conversations de chaque utilisateur, interagir avec le reste de l’application et être observable. Cette leçon couvre ces points un par un.

Authentifier chaque requête

Le SDK ne fait aucune hypothèse sur ton authentification : il te laisse vérifier l’utilisateur, puis transmettre son identité à server.process dans un contexte de requête. Ce contexte suit chaque appel : tu le retrouves dans respond, dans action, dans le store et dans les outils de l’agent.

Côté interface, l’option api.fetch remplace la fonction fetch utilisée par ChatKit. C’est ici que tu ajoutes le jeton de session de ton application :

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

export function ConnectedAssistant({ obtainToken }: { obtainToken: () => Promise<string> }) {
  const { control } = useChatKit({
    api: {
      url: '/chatkit',
      domainKey: 'local-dev',
      fetch: async (input, init) => {
        // Conserve les en-têtes définis par ChatKit, puis ajoute les nôtres
        const headers = new Headers(init?.headers);
        headers.set('Authorization', `Bearer ${await obtainToken()}`);
        return fetch(input, { ...init, headers });
      },
    },
  });

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

Côté serveur, une dépendance FastAPI vérifie le jeton et construit le contexte. La langue de l’interface arrive dans l’en-tête Accept-Language, que ChatKit envoie avec chaque requête :

from dataclasses import dataclass

from chatkit.server import StreamingResult
from chatkit.store import NotFoundError
from fastapi import Depends, FastAPI, HTTPException, Request
from fastapi.responses import Response, StreamingResponse


@dataclass
class RequestContext:
    user_id: str
    locale: str


async def current_user(request: Request) -> str:
    token = request.headers.get("authorization", "").removeprefix("Bearer ")
    user_id = await verify_token(token)  # ton authentification : session, JWT...
    if not user_id:
        raise HTTPException(status_code=401, detail="Unauthenticated")
    return user_id


app = FastAPI()


@app.post("/chatkit")
async def chatkit_endpoint(request: Request, user_id: str = Depends(current_user)) -> Response:
    context = RequestContext(user_id=user_id, locale=request.headers.get("accept-language", "fr"))
    try:
        result = await server.process(await request.body(), context)
    except NotFoundError:
        raise HTTPException(status_code=404, detail="Not found")
    if isinstance(result, StreamingResult):
        return StreamingResponse(result, media_type="text/event-stream")
    return Response(content=result.json, media_type="application/json")

Chaque utilisateur obtient ses propres conversations

L’authentification ne suffit pas : il te faut aussi une autorisation. Sans contrôle, un utilisateur qui devinerait un ID de fil pourrait lire la conversation de quelqu’un d’autre. Le bon endroit pour ce contrôle est le store, par lequel transitent toutes les lectures. Dans cet exemple, chaque fil conserve le nom de son propriétaire dans ses métadonnées, ce que le SDK ne transmet jamais à l’interface :

from chatkit.store import NotFoundError
from chatkit.types import Page, ThreadMetadata

from memory_store import MemoryStore


class UserStore(MemoryStore):
    async def save_thread(self, thread: ThreadMetadata, context: RequestContext) -> None:
        thread.metadata.setdefault("owner", context.user_id)
        await super().save_thread(thread, context)

    async def load_thread(self, thread_id: str, context: RequestContext) -> ThreadMetadata:
        thread = await super().load_thread(thread_id, context)
        if thread.metadata.get("owner") != context.user_id:
            raise NotFoundError(f"Thread {thread_id} not found")  # ne révèle pas qu'il existe
        return thread

    async def load_threads(self, limit, after, order, context: RequestContext) -> Page[ThreadMetadata]:
        page = await super().load_threads(limit, after, order, context)
        page.data = [t for t in page.data if t.metadata.get("owner") == context.user_id]
        return page

Le bloc try dans le point de terminaison prend tout son sens ici : sans lui, la lecture directe du fil d’un autre utilisateur se solderait par une erreur 500 au lieu d’une 404 ; pour une requête diffusée en flux, comme l’ajout d’un message, le SDK interrompt le flux sans rien envoyer. En production, ce filtrage se fait directement dans la requête SQL (un WHERE owner = … gère aussi correctement la pagination). Applique la même règle aux pièces jointes. La documentation te rappelle aussi de décider ce que tu conserves et pendant combien de temps : les fils contiennent du texte, des fichiers et des résultats d’outils, donc souvent des données personnelles.

Donner ton contexte applicatif au modèle

Le modèle ne sait rien de la page que l’utilisateur consulte, de son abonnement ou du document ouvert. La documentation propose trois façons de le lui apprendre :

  • À chaque requête, via des en-têtes ajoutés dans api.fetch (X-Page, X-Plan…), que le serveur stocke dans le contexte ;
  • À la demande, via un outil serveur qui lit ctx.context.request_context et récupère l’information ;
  • Dans le navigateur, via un outil côté client, quand l’information n’existe que là (voir la section suivante).

Une précaution, tirée du guide de production : ne construis jamais les instructions système du modèle à partir de valeurs venant de l’utilisateur, même indirectement (titre du fil, objet du ticket). Garde-les fixes, et passe le contexte variable sous forme de données.

Outils côté client

Certaines informations ne vivent que dans le navigateur : sélection dans un éditeur, état d’un canevas, brouillon non enregistré. Un outil côté client permet au modèle de les demander en cours de tour : ton serveur met l’agent en pause, ChatKit exécute ta fonction dans le navigateur, puis renvoie le résultat au serveur, qui reprend.

Côté serveur, l’outil se contente de faire la demande, et l’agent s’arrête dessus :

from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall


@function_tool(description_override="Lit le texte que l'utilisateur a sélectionné sur la page.")
async def read_selection(ctx: RunContextWrapper[AgentContext]) -> None:
    ctx.context.client_tool_call = ClientToolCall(name="read_selection", arguments={})


assistant = Agent[AgentContext](
    name="Writing Assistant",
    instructions="Aide l'utilisateur à améliorer le texte qu'il sélectionne.",
    model="gpt-6.1-sol",
    tools=[read_selection],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)

Côté interface, onClientTool reçoit la demande ; le nom doit correspondre, et l’objet retourné va au serveur :

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onClientTool: async ({ name }) => {
    if (name === 'read_selection') {
      return { text: window.getSelection()?.toString() ?? '' };
    }
    return {};
  },
});

Un seul outil côté client peut s’exécuter par tour. Et quand tu n’attends pas de réponse, préfère un effet : le serveur émet un ClientEffectEvent(name="refresh_cart", data={...}), depuis respond, action ou un outil via ctx.context.stream(...), et l’interface le reçoit dans onEffect sans interrompre la réponse. Les effets ne sont pas enregistrés dans le fil.

Piloter ChatKit depuis ton application

useChatKit renvoie, en plus de control, des méthodes pour commander l’interface depuis le reste de ton code :

MéthodeEffet
sendUserMessage({ text })Envoie un message comme si l’utilisateur l’avait tapé
setComposerValue({ text })Pré-remplit la zone de saisie sans envoyer
setThreadId(id)Ouvre un fil existant, ou un nouveau fil avec null
focusComposer()Place le curseur dans la zone de saisie
showHistory(), hideHistory()Ouvre ou ferme l’historique des conversations
sendCustomAction(action)Envoie une action au serveur (Leçon 20)
fetchUpdates()Recharge le fil depuis le serveur

Un bouton « Demander à l’assistant » sur une fiche produit tient en une ligne de code :

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

export function ProductSheet({ product }: { product: string }) {
  const chatkit = useChatKit({ api: { url: '/chatkit', domainKey: 'local-dev' } });

  return (
    <>
      <button onClick={() => chatkit.sendUserMessage({ text: `Le produit ${product} est-il compatible avec mon équipement ?` })}>
        Demander à l'assistant
      </button>
      <ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
    </>
  );
}

L’option initialThread ouvre un fil spécifique au montage, par exemple celui que l’utilisateur a laissé ouvert ; avec null (la valeur par défaut), ChatKit affiche l’écran d’accueil.

Observer ce qui se passe

ChatKit émet des événements : prêt (onReady), début et fin de réponse (onResponseStart, onResponseEnd), changement de fil (onThreadChange), journaux (onLog) et erreurs (onError). Dans React, ce sont des options pour useChatKit :

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onThreadChange: ({ threadId }) => rememberLastThread(threadId),
  onError: ({ error }) => sendTelemetry({ name: 'chatkit.error', message: error.message }),
  onLog: ({ name }) => sendTelemetry({ name: name }),
});

Le guide de production insiste sur un point : ces événements peuvent contenir des données personnelles et du texte de message. N’envoie pas tout le contenu à ton outil de suivi : extrais les champs utiles (nom de l’événement, ID du fil, code d’erreur). Côté serveur, journalise chaque requête vers /chatkit, les appels au store et au modèle, ainsi que les erreurs d’outils, avec l’ID utilisateur et l’ID du fil, pour pouvoir corréler les deux côtés.

Pour les outils lents, tiens l’utilisateur informé : await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Recherche de tes commandes…")) affiche une progression immédiate, remplacée par le reste de la réponse et jamais enregistrée dans le fil.

Avant de passer en production

La liste de contrôle, tirée du guide officiel :

  • Domaines : chaque nom d’hôte de production est listé sur la page Domain allowlist de la plateforme OpenAI, et sa clé est dans domainKey ;
  • Authentification et autorisation : chaque requête vers /chatkit est authentifiée, les fils et pièces jointes sont filtrés par utilisateur ;
  • Secrets : la clé API et les identifiants internes sont dans des variables d’environnement ou un gestionnaire de secrets, jamais dans le dépôt ;
  • Entrées : les messages, fichiers, charges utiles d’action et résultats d’outils sont traités comme non fiables et validés avant d’atteindre tes systèmes ;
  • Données personnelles : durée de conservation décidée et appliquée dans le store, chiffrement au repos, aucune donnée inutile dans les métadonnées ;
  • Langue : la langue de l’en-tête Accept-Language pilote les réponses de l’agent et tes messages d’outils ;
  • Suivi : événements d’interface et journaux serveur collectés, sans contenu sensible.

Keskeiset asiat

  • L’identité de l’utilisateur passe via api.fetch côté interface, puis via le contexte de server.process, qui la propage partout
  • L’autorisation se fait dans le store : chaque fil appartient à un utilisateur, et le fil d’un autre utilisateur est « introuvable »
  • Le contexte applicatif arrive via des en-têtes, des outils serveur ou des outils côté client (onClientTool + StopAtTools) ; les effets (onEffect) servent quand aucune réponse n’est attendue
  • Les méthodes de useChatKit (sendUserMessage, setThreadId, setComposerValue…) commandent ChatKit depuis le reste de l’application
  • Les événements (onError, onLog…) alimentent ton suivi, sans y copier de données personnelles ; la liste de contrôle de production couvre les domaines, les droits, les secrets, les entrées et les données