Geavanceerde integratie in uw app
Op deze pagina
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 SDKopenai-chatkit1.6.5-gidsen (Prepare your app for production, Pass extra app context, Update the client during a response) en@openai/chatkit-react1.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_contextleest 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:
| Methode | Effect |
|---|---|
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
/chatkitis 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.fetchaan de interfacekant, vervolgens via de context vanserver.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