ChatKit: Overzicht en installatie
Op deze pagina
Les herschreven op 3 november 2026. De vorige versie beschreef een API die niet meer bestaat: een
new ChatKit({ apiKey, agentId })-object,ChatProvider,ChatWindow- enMessageInput-componenten, een@openai/chatkit/react-module en eencdn.openai.com/chatkit/…-script. Deze les volgt nu de officiële OpenAI ChatKit-gidsen, Python SDKopenai-chatkit1.6.5 en@openai/chatkit-react1.6.1. We hebben de voorbeeldserver lokaal uitgevoerd om elke stap te verifiëren. Opmerking: Agent Builder wordt op 30 november 2026 stopgezet; ChatKit blijft beschikbaar. Bronnen: ChatKit · Geavanceerde integraties met ChatKit · Python SDK quickstart · Officiële starter-app.
Waarom ChatKit
U heeft een agent gebouwd met de Agents SDK. Deze draait in uw terminal en niemand anders kan hem gebruiken. Om de agent onder uw gebruikers te brengen, heeft u een conversatie-interface nodig. Het vanaf nul bouwen van een goede chat-UI is echter kostbaar. U moet namelijk omgaan met scrollen, streamende berichten, het hervatten van conversaties, bijlagen, de weergave van tool-aanroepen en het afhandelen van netwerkfouten.
ChatKit is het antwoord van OpenAI: een conversatiecomponent die u in uw product insluit en die de volledige gebruikerservaring voor zijn rekening neemt. De documentatie benadrukt de interactieve widgets, startsuggesties, weergave van tool-aanroepen, bijlagen en visualisatie van de redenering van de agent. U houdt de controle over wat er toe doet: de agent, uw gegevens en uw regels.
Twee manieren om het aan te sturen
ChatKit is slechts een interface. Er is een server nodig die berichten ontvangt, de agent uitvoert en het antwoord terugstreamt. OpenAI beschrijft twee benaderingen:
| Pad | Hoe het werkt | Voor wie |
|---|---|---|
| Uw eigen ChatKit-server (geavanceerde integratie) | Uw Python-server, gebruikmakend van de openai-chatkit SDK, ontvangt verzoeken van de UI en voert de agent van uw keuze uit, zoals een Agents SDK-agent | Elk nieuw project: dit is het pad dat OpenAI aanbeveelt |
| Gehoste Agent Builder-workflow | OpenAI voert een workflow uit die is ontworpen in Agent Builder; uw server maakt alleen sessies aan | Bestaande integraties tijdens de overgangsperiode: Agent Builder wordt op 30 november 2026 stopgezet |
Deze cursus volgt het eerste pad, het enige met toekomst. We vatten het tweede pad aan het einde van de les samen voor degenen die een bestaande integratie tot aan de stopzetting moeten onderhouden.
De architectuur uit drie onderdelen
Een ChatKit-integratie komt neer op drie elementen. Het onderscheid hiervan voorkomt de meeste beginnersfouten:
- ChatKit.js, de component zelf: een webcomponent
<openai-chatkit>die het gesprek in een iframe weergeeft. Deze wordt geladen vanaf OpenAI’s CDN (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), niet vanaf npm: het npm-pakket@openai/chatkitbevat alleen de type-definities. - React-bindings,
@openai/chatkit-react, die deChatKit-component en deuseChatKit-hook beschikbaar stellen. Deze zijn optioneel: zonder React bestuurt u de webcomponent direct. - Uw ChatKit-server, een enkel HTTP-eindpunt, conventioneel
/chatkit, dat alle verzoeken van de interface ontvangt. EenChatKitServer-instantie routeert deze, maakt gebruik van een store om conversatiethreads te persistenteren en voert uw agent uit.
De OpenAI API-sleutel verlaat de server nooit: de interface communiceert alleen met uw /chatkit-eindpunt.
Installeren
Installeer aan de kant van de interface de React-bindings en laad het ChatKit-script in uw pagina:
npm install @openai/chatkit-react
<!-- In de <head> van uw pagina -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Installeer aan de serverzijde de ChatKit Python SDK (Python 3.10 of later), die de Agents SDK meebrengt, plus een webserver:
pip install openai-chatkit fastapi uvicorn
De minimale server
De onderstaande server volgt de officiële quickstart. ChatKitServer vereist slechts één methode, respond, die voor elk gebruikersbericht wordt aangeroepen. Deze laadt de laatste thread-items, converteert ze naar agent-invoer met simple_to_agent_input, voert de agent uit in streaming-modus en vertaalt die stream naar ChatKit-gebeurtenissen met 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 # in-memory store uit de starter-app
assistant = Agent[AgentContext[dict[str, Any]]](
name="Product Assistant",
instructions="You help product users. Respond in English, briefly.",
model="gpt-6.1-sol",
)
class MyChatKitServer(ChatKitServer[dict[str, Any]]):
async def respond(
self,
thread: ThreadMetadata,
input_user_message: UserMessageItem | None,
context: dict[str, Any],
) -> AsyncIterator[ThreadStreamEvent]:
# De laatste 30 thread-items, hersteld in chronologische volgorde
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 = MyChatKitServer(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")
Voer dit uit met OPENAI_API_KEY in uw omgeving: uvicorn main:app --port 8000.
De store verdient twee woorden. ChatKit slaat niets zelf op: threads, berichten, widgets en tool-aanroepen worden gepersisteerd door een klasse die overerft van chatkit.store.Store en ongeveer een dozijn methoden implementeert (load_thread, save_thread, load_thread_items, add_thread_item…). Gebruik om mee te beginnen het bestand memory_store.py uit de officiële starter-app opnieuw: dit houdt alles in het geheugen zolang het proces draait. Vervang dit in productie door een database. De documentatie raadt aan objecten als JSON op te slaan, zodat SDK-updates u niet dwingen tot schemamigraties.
De React-interface
Aan de kant van de interface ontvangt useChatKit de configuratie en geeft een control-object terug, dat u doorgeeft aan de ChatKit-component:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// In ontwikkeling is een placeholder-waarde voldoende; gebruik in productie
// uw domeinsleutel (zie hieronder)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Serveer de interface en /chatkit vanaf dezelfde origin: in ontwikkeling regelt de proxy van uw build-tool dit (de starter-app configureert Vite’s proxy om /chatkit door te sturen naar poort 8000). Als de server op een andere origin staat, staat u deze dan expliciet toe, bijvoorbeeld met FastAPI’s CORSMiddleware.
Zonder React
Een WordPress-site, een Rails-applicatie of een statische pagina kan dezelfde assistant integreren: de webcomponent werkt direct zodra het CDN-script is geladen.
<!doctype html>
<html lang="en">
<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>
Elke optie die u in de volgende lessen zult zien, heeft in beide gevallen dezelfde vorm: een object dat wordt doorgegeven aan useChatKit in React, of aan setOptions op de webcomponent.
Beveiliging vanaf dag één
Drie regels, ontleend aan de ChatKit-productiegids, gelden vanaf het prototype-stadium:
- De API-sleutel blijft op de server. Deze mag niet voorkomen in interface-code of in uw repository: lees deze uit een omgevingsvariabele of een secrets manager.
- Authenticeer elk verzoek aan
/chatkit. De SDK regelt dit niet: uw applicatie moet de sessie of het token van de gebruiker verifiëren en vervolgens hun identiteit doorgeven aanserver.processin de context (les 21). Zonder dit kan iedereen uw agent op uw kosten uitvoeren. - Registreer uw domeinen. Declareer voordat u live gaat elke hostnaam die ChatKit zal weergeven op de pagina Domain allowlist van het OpenAI-platform en kopieer de gegenereerde sleutel naar
domainKey. Bij het laden verifieert het ChatKit-iframe deze sleutel bij OpenAI en weigert het weer te geven als deze ontbreekt of niet overeenkomt.
Als u al een Agent Builder-workflow heeft
Bestaande integraties die gekoppeld zijn aan een gehoste workflow werken tot Agent Builder wordt stopgezet. Hun principe verschilt: uw server maakt een ChatKit-sessie aan door POST https://api.openai.com/v1/chatkit/sessions aan te roepen, met de header OpenAI-Beta: chatkit_beta=v1, de workflow-ID en een user-identifier die uniek is voor elke geauthenticeerde gebruiker. Vervolgens geeft het de verkregen client_secret terug aan de interface. Aan de kant van de interface neemt de api-optie dan een getClientSecret-functie in plaats van een URL.
Start geen nieuw project op basis van dit model. Exporteer voor een bestaande integratie de workflow naar Agents SDK-code en schakel over naar uw eigen ChatKit-server vóór 30 november 2026, volgens de gids Migrate from Agent Builder.
Belangrijkste punten
- ChatKit is een kant-en-klare conversatie-interface; uw server voert de agent uit
- Voor elk nieuw project: uw eigen ChatKit-server (
pip install openai-chatkit), met eenrespond-methode en een/chatkit-eindpunt; de gehoste Agent Builder wordt op 30 november 2026 stopgezet - De interface wordt geladen vanaf OpenAI’s CDN; gebruik in React
useChatKiten<ChatKit control={control} />van@openai/chatkit-react - De store persisteert conversatiethreads: in het geheugen voor testen, in een database voor productie
- API-sleutel alleen server-side, geauthenticeerde
/chatkit, geregistreerde domeinen om dedomainKeyte verkrijgen