Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

ChatKit: Overzicht en installatie

Les 17 van 25 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Waarom ChatKit
  2. Twee manieren om het aan te sturen
  3. De architectuur uit drie onderdelen
  4. Installeren
  5. De minimale server
  6. De React-interface
  7. Zonder React
  8. Beveiliging vanaf dag één
  9. Als u al een Agent Builder-workflow heeft
  10. Belangrijkste punten

Les herschreven op 3 november 2026. De vorige versie beschreef een API die niet meer bestaat: een new ChatKit({ apiKey, agentId })-object, ChatProvider, ChatWindow- en MessageInput-componenten, een @openai/chatkit/react-module en een cdn.openai.com/chatkit/…-script. Deze les volgt nu de officiële OpenAI ChatKit-gidsen, Python SDK openai-chatkit 1.6.5 en @openai/chatkit-react 1.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:

PadHoe het werktVoor 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-agentElk nieuw project: dit is het pad dat OpenAI aanbeveelt
Gehoste Agent Builder-workflowOpenAI voert een workflow uit die is ontworpen in Agent Builder; uw server maakt alleen sessies aanBestaande 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:

  1. 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/chatkit bevat alleen de type-definities.
  2. React-bindings, @openai/chatkit-react, die de ChatKit-component en de useChatKit-hook beschikbaar stellen. Deze zijn optioneel: zonder React bestuurt u de webcomponent direct.
  3. Uw ChatKit-server, een enkel HTTP-eindpunt, conventioneel /chatkit, dat alle verzoeken van de interface ontvangt. Een ChatKitServer-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 aan server.process in 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 een respond-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 useChatKit en <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 de domainKey te verkrijgen