Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Geavanceerde integratie in uw app

Les 21 van 25 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Wat resteert er na de demo
  2. Authenticeer elk verzoek
  3. Elke gebruiker krijgt zijn eigen conversaties
  4. Geef het model uw app-context
  5. Client-side tools
  6. Stuur ChatKit aan vanuit uw applicatie
  7. Observeer wat er gebeurt
  8. Voordat u naar productie gaat
  9. Belangrijkste punten

Les herschreven op 3 november 2026. De vorige versie vertrouwde op verzonnen eigenschappen en gebeurtenissen (ChatProvider, “sidebar”-modus, UI-gebaseerde persistentie). Deze versie volgt de Python SDK openai-chatkit 1.6.5-gidsen (Prepare your app for production, Pass extra app context, Update the client during a response) en @openai/chatkit-react 1.6.1-types: de servercode is lokaal uitgevoerd en de React-code is geverifieerd door compilatie. Bronnen: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.

Wat resteert er na de demo

De vorige vier lessen leveren u een werkende assistent op. Om deze live te laten gaan in een echt product, heeft u nodig wat een demo onderscheidt van een dienst: weten wie er spreekt, elke gebruiker alleen zijn eigen conversaties tonen, interactie met de rest van de applicatie, en observeerbaarheid. Deze les behandelt deze punten één voor één.

Authenticeer elk verzoek

De SDK maakt geen aannames over uw authenticatie: u verifieert de gebruiker en geeft vervolgens diens identiteit door aan server.process binnen een request context. Deze context volgt elke aanroep: u vindt deze terug in respond, in action, in de store, en in de tools van de agent.

Aan de interfacekant vervangt de optie api.fetch de fetch-functie die door ChatKit wordt gebruikt. Hier voegt u uw sessietoken toe:

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) => {
        // Keep headers set by ChatKit, then add ours
        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]" />;
}

Aan de serverkant verifieert een FastAPI-dependency het token en bouwt de context. De interface-taal komt binnen via de Accept-Language-header, die ChatKit bij elk verzoek meestuurt:

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)  # your authentication: 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")

Elke gebruiker krijgt zijn eigen conversaties

Authenticatie alleen is niet genoeg: u heeft ook autorisatie nodig. Zonder controle zou een gebruiker die een thread-ID raadt, de conversatie van iemand anders kunnen lezen. De juiste plek voor deze controle is de store, waar alle leesbewerkingen langs komen. In dit voorbeeld bewaart elke thread de naam van de eigenaar in zijn metadata, die de SDK nooit naar de interface verzendt:

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")  # do not reveal that it exists
        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

Het try-blok in het endpoint is hier zinvol: zonder dit zou het direct lezen van de thread van een andere gebruiker eindigen in een 500-fout in plaats van een 404; bij een gestreamd verzoek, zoals het toevoegen van een bericht, onderbreekt de SDK de stream zonder iets te verzenden. In productie gebeurt deze filtering in de SQL-query zelf (een WHERE owner = … behandelt ook paginatie correct). Pas dezelfde regel toe op bijlagen. De documentatie herinnert u er ook aan om te beslissen wat u bewaart en hoe lang: threads bevatten tekst, bestanden en tool-resultaten, dus vaak persoonsgegevens.

Geef het model uw app-context

Het model weet niets over de pagina die de gebruiker bekijkt, zijn abonnement, of het geopende document. De documentatie stelt drie manieren voor om het dit te leren:

  • Bij elk verzoek, via headers toegevoegd in api.fetch (X-Page, X-Plan…), die de server in de context opslaat;
  • Op aanvraag, via een server-tool die ctx.context.request_context leest en de informatie ophaalt;
  • In de browser, via een client-side tool, wanneer de informatie alleen daar bestaat (zie de volgende sectie).

Eén voorzorgsmaatregel, ontleend aan de productiegids: bouw nooit de systeeminstructies van het model op basis van waarden die van de gebruiker komen, zelfs niet indirect (thread-titel, ticketonderwerp). Houd deze vast en geef de variabele context door als data.

Client-side tools

Sommige informatie leeft alleen in de browser: selectie in een editor, canvas-status, een niet-opgeslagen concept. Een client-side tool laat het model deze halverwege een beurt opvragen: uw server pauzeert de agent, ChatKit voert uw functie uit in de browser, en stuurt het resultaat terug naar de server, die vervolgens hervat.

Aan de serverkant doet de tool alleen het verzoek, en de agent stopt daarop:

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


@function_tool(description_override="Reads the text the user has selected on the 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="Help the user improve the text they select.",
    model="gpt-6.1-sol",
    tools=[read_selection],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)

Aan de interfacekant ontvangt onClientTool het verzoek; de naam moet overeenkomen en het teruggegeven object gaat naar de server:

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

Er kan slechts één client-side tool per beurt worden uitgevoerd. En wanneer u geen respons verwacht, geef de voorkeur aan een effect: de server zendt een ClientEffectEvent(name="refresh_cart", data={...}) uit, vanuit respond, action, of een tool via ctx.context.stream(...), en de interface ontvangt dit in onEffect zonder de respons te onderbreken. Effecten worden niet vastgelegd in de thread.

Stuur ChatKit aan vanuit uw applicatie

useChatKit retourneert, naast control, methoden om de interface aan te sturen vanuit de rest van uw code:

MethodeEffect
sendUserMessage({ text })Verstuurt een bericht alsof de gebruiker het heeft getypt
setComposerValue({ text })Vult het invoerveld vooraf zonder te verzenden
setThreadId(id)Opent een bestaande thread, of een nieuwe thread met null
focusComposer()Plaatst de cursor in het invoerveld
showHistory(), hideHistory()Opent of sluit de conversatiegeschiedenis
sendCustomAction(action)Verstuurt een actie naar de server (Les 20)
fetchUpdates()Herlaadt de thread vanaf de server

Een knop “Vraag het de assistent” op een productfiche wordt één regel 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: `Is the ${product} product compatible with my equipment?` })}>
        Ask the assistant
      </button>
      <ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
    </>
  );
}

De optie initialThread opent bij het laden een specifieke thread, bijvoorbeeld degene die de gebruiker open had laten staan; met null (de standaardwaarde) toont ChatKit het startscherm.

Observeer wat er gebeurt

ChatKit zendt gebeurtenissen uit: gereed (onReady), start en einde van respons (onResponseStart, onResponseEnd), thread-wijziging (onThreadChange), logs (onLog), en fouten (onError). In React zijn dit opties voor 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 }),
});

De productiegids benadrukt één punt: deze gebeurtenissen kunnen persoonsgegevens en berichttekst bevatten. Stuur niet alle inhoud naar uw trackingtool: extraheer nuttige velden (gebeurtenisnaam, thread-ID, foutcode). Log aan de serverkant elk verzoek naar /chatkit, aanroepen naar de store en het model, en tool-fouten, met de gebruiker- en thread-ID, zodat u beide kanten kunt correleren.

Houd bij trage tools de gebruiker op de hoogte: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) toont directe voortgang, vervangen door de rest van de respons en nooit vastgelegd in de thread.

Voordat u naar productie gaat

De checklist, overgenomen uit de officiële gids:

  • Domeinen: elke productie-hostnaam staat vermeld op de pagina Domain allowlist van het OpenAI-platform, en de sleutel staat in domainKey;
  • Authenticatie en autorisatie: elk verzoek naar /chatkit is geauthenticeerd, threads en bijlagen zijn gefilterd per gebruiker;
  • Secrets: de API-sleutel en interne referenties staan in omgevingsvariabelen of een secrets manager, nooit in de repository;
  • Inputs: berichten, bestanden, action payloads en tool-resultaten worden behandeld als niet-vertrouwd en gevalideerd voordat ze uw systemen bereiken;
  • Persoonsgegevens: bewaartermijn besloten en toegepast in de store, encryptie in rust, geen onnodige data in metadata;
  • Taal: de Accept-Language-taal stuurt de responsen van de agent en uw tool-berichten aan;
  • Tracking: interface-gebeurtenissen en server-logs verzameld, zonder gevoelige inhoud.

Belangrijkste punten

  • De identiteit van de gebruiker passeert via api.fetch aan de interfacekant, vervolgens via de context van server.process, die deze overal propageert
  • Autorisatie gebeurt in de store: elke thread behoort toe aan een gebruiker, en de thread van een andere gebruiker is “niet gevonden”
  • App-context komt binnen via headers, server-tools, of client-side tools (onClientTool + StopAtTools); effecten (onEffect) dienen wanneer geen respons wordt verwacht
  • Methoden van useChatKit (sendUserMessage, setThreadId, setComposerValue…) sturen ChatKit aan vanuit de rest van de applicatie
  • Gebeurtenissen (onError, onLog…) voeden uw tracking, zonder persoonsgegevens erin te kopiëren; de productiechecklist dekt domeinen, rechten, secrets, inputs en data