Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

ChatKit: Überblick und Installation

Lektion 17 von 25 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Warum ChatKit
  2. Zwei Wege zur Bereitstellung
  3. Die dreiteilige Architektur
  4. Installation
  5. Der minimale Server
  6. Die React-Oberfläche
  7. Ohne React
  8. Sicherheit von Anfang an
  9. Wenn Sie bereits einen Agent Builder-Arbeitsablauf haben
  10. Kernaussagen

Lektion neu geschrieben am 3. November 2026. Die vorherige Version beschrieb eine API, die nicht mehr existiert: ein new ChatKit({ apiKey, agentId })-Objekt, ChatProvider, ChatWindow und MessageInput-Komponenten, ein @openai/chatkit/react-Modul und ein cdn.openai.com/chatkit/…-Skript. Diese Lektion folgt nun den offiziellen OpenAI ChatKit-Anleitungen, dem Python-SDK openai-chatkit 1.6.5 und @openai/chatkit-react 1.6.1. Wir haben den Beispielserver lokal ausgeführt, um jeden Schritt zu verifizieren. Hinweis: Der Agent Builder schaltet am 30. November 2026 ab; ChatKit bleibt verfügbar. Quellen: ChatKit · Erweiterte Integrationen mit ChatKit · Python-SDK Schnellstart · Offizielles Starter-App.

Warum ChatKit

Sie haben einen Agenten mit dem Agents SDK erstellt. Er läuft in Ihrem Terminal, und niemand anderes kann ihn nutzen. Um ihn in die Hände Ihrer Nutzer zu geben, benötigen Sie eine Gesprächsoberfläche – und der Aufbau einer guten Chat-Benutzeroberfläche von Grund auf ist teuer. Sie müssen Scrollen, das Streamen von Nachrichten, die Fortsetzung von Gesprächen, Anhänge, die Anzeige von Tool-Aufrufen und die Behandlung von Netzwerkfehlern verwalten.

ChatKit ist die Antwort von OpenAI: eine Gesprächskomponente, die Sie in Ihr Produkt einbinden und die das gesamte Benutzererlebnis verwaltet. Die Dokumentation hebt ihre interaktiven Widgets, Vorschläge für den Start, die Anzeige von Tool-Aufrufen, Anhänge und die Visualisierung der Agenten-Überlegungen hervor. Sie behalten die Kontrolle über das Wesentliche: den Agenten, Ihre Daten und Ihre Regeln.

Zwei Wege zur Bereitstellung

ChatKit ist lediglich eine Schnittstelle. Es benötigt einen Server, der Nachrichten empfängt, den Agenten ausführt und die Antwort zurückstreamt. OpenAI beschreibt zwei Ansätze:

WegFunktionsweiseZielgruppe
Eigener ChatKit-Server (erweiterte Integration)Ihr Python-Server, der das openai-chatkit-SDK verwendet, empfängt Anfragen von der Oberfläche und führt den Agenten Ihrer Wahl aus, z. B. einen Agents SDK-AgentenJedes neue Projekt: dies ist der von OpenAI empfohlene Weg
Gehosteter Agent Builder-ArbeitsablaufOpenAI führt einen in Agent Builder konzipierten Arbeitsablauf aus; Ihr Server erstellt lediglich SitzungenBestehende Integrationen während des Übergangszeitraums: Agent Builder schaltet am 30. November 2026 ab

Dieser Kurs folgt dem ersten Weg – dem einzigen mit Zukunft. Wir fassen den zweiten Weg am Ende der Lektion zusammen, für diejenigen, die eine bestehende Integration bis zum Abschalten aufrechterhalten müssen.

Die dreiteilige Architektur

Eine ChatKit-Integration reduziert sich auf drei Elemente. Die Unterscheidung vermeidet die meisten Anfängerfehler:

  1. ChatKit.js, die Komponente selbst: eine Web-Komponente <openai-chatkit>, die das Gespräch in einem iframe anzeigt. Sie wird von OpenAIs CDN (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js) geladen, nicht von npm: das npm-Paket @openai/chatkit enthält lediglich seine Typdefinitionen.
  2. React-Bindungen, @openai/chatkit-react, die die ChatKit-Komponente und den useChatKit-Hook bereitstellen. Diese sind optional: ohne React steuern Sie die Web-Komponente direkt.
  3. Ihr ChatKit-Server, ein einzelner HTTP-Endpunkt, konventionell /chatkit, der alle Anfragen von der Oberfläche empfängt. Eine ChatKitServer-Instanz leitet sie weiter, stützt sich auf eine Speicherstelle (Store), um Gesprächsthreads zu persistieren, und führt Ihren Agenten aus.

Der OpenAI API-Schlüssel verlässt den Server niemals: die Oberfläche spricht nur mit Ihrem /chatkit-Endpunkt.

Installation

Auf der Schnittstellenseite installieren Sie die React-Bindungen und laden das ChatKit-Skript in Ihre Seite:

npm install @openai/chatkit-react
<!-- Im <head> Ihrer Seite -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>

Auf der Serverseite installieren Sie das ChatKit Python-SDK (Python 3.10 oder neuer), das das Agents SDK mitbringt, sowie einen Web-Server:

pip install openai-chatkit fastapi uvicorn

Der minimale Server

Der folgende Server folgt dem offiziellen Schnellstart. ChatKitServer erfordert nur eine Methode, respond, die für jede Benutzernachricht aufgerufen wird. Sie lädt die neuesten Thread-Elemente neu, wandelt sie mit simple_to_agent_input in Agenteneingabe um, führt den Agenten im Stream-Modus aus und übersetzt diesen Stream in ChatKit-Ereignisse mit 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-Speicher-Speicher aus der 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]:
        # Die letzten 30 Thread-Elemente, chronologisch neuhergestellt
        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")

Starten Sie es mit OPENAI_API_KEY in Ihrer Umgebung: uvicorn main:app --port 8000.

Die Speicherstelle (Store) verdient zwei Worte. ChatKit speichert nichts von selbst: Threads, Nachrichten, Widgets und Tool-Aufrufe werden von einer Klasse persistiert, die von chatkit.store.Store erbt und etwa ein Dutzend Methoden implementiert (load_thread, save_thread, load_thread_items, add_thread_item…). Um zu beginnen, verwenden Sie die memory_store.py-Datei aus der offiziellen Starter-App: sie hält alles im Speicher, solange der Prozess läuft. In der Produktion ersetzen Sie sie durch eine Datenbank. Die Dokumentation empfiehlt, Objekte als JSON zu speichern, damit SDK-Updates Sie nicht zu Schema-Migrationen zwingen.

Die React-Oberfläche

Auf der Schnittstellenseite empfängt useChatKit die Konfiguration und gibt ein control-Objekt zurück, das Sie an die ChatKit-Komponente übergeben:

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

export function Assistant() {
  const { control } = useChatKit({
    api: {
      url: '/chatkit',
      // In der Entwicklung reicht ein Platzhalterwert; in der Produktion
      // verwenden Sie Ihren Domain-Schlüssel (siehe unten)
      domainKey: 'local-dev',
    },
  });

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

Bereitstellen Sie die Oberfläche und /chatkit vom selben Ursprung aus: in der Entwicklung übernimmt der Proxy Ihres Build-Tools dies (die Starter-App konfiguriert den Vite-Proxy, um /chatkit auf Port 8000 umzuleiten). Wenn der Server an einem anderen Ursprung lebt, erlauben Sie dies explizit, z. B. mit CORSMiddleware von FastAPI.

Ohne React

Eine WordPress-Website, eine Rails-Anwendung oder eine statische Seite können denselben Assistenten integrieren: die Web-Komponente funktioniert direkt, sobald das CDN-Skript geladen ist.

<!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>

Jede Option, die Sie in den folgenden Lektionen sehen werden, hat in beiden Fällen dieselbe Form: ein Objekt, das an useChatKit in React oder an setOptions auf der Web-Komponente übergeben wird.

Sicherheit von Anfang an

Drei Regeln, die aus dem ChatKit-Produktionsleitfaden stammen, gelten bereits ab dem Prototyp-Stadium:

  • Der API-Schlüssel bleibt auf dem Server. Er darf nicht im Schnittstellen-Code oder in Ihrem Repository erscheinen: lesen Sie ihn aus einer Umgebungsvariablen oder einem Secrets Manager.
  • Authentifizieren Sie jede Anfrage an /chatkit. Das SDK übernimmt dies nicht: Ihre Anwendung muss die Sitzung oder das Token des Benutzers verifizieren und dann dessen Identität an server.process im Kontext übergeben (Lektion 21). Ohne dies kann jeder Ihren Agenten auf Ihre Kosten ausführen.
  • Registrieren Sie Ihre Domains. Bevor Sie live gehen, deklarieren Sie jeden Hostnamen, der ChatKit auf der OpenAI-Plattform anzeigt, auf der Domain Allowlist-Seite, und kopieren Sie den generierten Schlüssel in domainKey. Beim Laden überprüft das ChatKit-iframe diesen Schlüssel bei OpenAI und verweigert die Anzeige, wenn er fehlt oder nicht übereinstimmt.

Wenn Sie bereits einen Agent Builder-Arbeitsablauf haben

Bestehende Integrationen, die an einen gehosteten Arbeitsablauf gekoppelt sind, funktionieren, bis Agent Builder abschaltet. Ihr Prinzip unterscheidet sich: Ihr Server erstellt eine ChatKit-Sitzung, indem er POST https://api.openai.com/v1/chatkit/sessions, aufruft, mit dem Header OpenAI-Beta: chatkit_beta=v1, der Workflow-ID und einer user-Kennung, die für jeden authentifizierten Benutzer eindeutig ist. Er gibt dann das erhaltene client_secret an die Oberfläche zurück. Auf der Schnittstellenseite nimmt die api-Option dann eine getClientSecret-Funktion anstelle einer URL entgegen.

Starten Sie kein neues Projekt auf diesem Modell. Für eine bestehende Integration exportieren Sie den Arbeitsablauf in Agents SDK-Code und wechseln Sie vor dem 30. November 2026 zu Ihrem eigenen ChatKit-Server, indem Sie dem Migrate from Agent Builder-Leitfaden folgen.

Kernaussagen

  • ChatKit ist eine sofort integrierbare Gesprächsoberfläche; Ihr Server führt den Agenten aus
  • Für jedes neue Projekt: Ihr eigener ChatKit-Server (pip install openai-chatkit) mit einer respond-Methode und einem /chatkit-Endpunkt; der gehostete Agent Builder schaltet am 30. November 2026 ab
  • Die Oberfläche wird von OpenAIs CDN geladen; in React verwenden Sie useChatKit und <ChatKit control={control} /> aus @openai/chatkit-react
  • Die Speicherstelle (Store) persistiert Gesprächsthreads: im Speicher für Tests, in einer Datenbank für die Produktion
  • API-Schlüssel nur serverseitig, authentifizierter /chatkit, registrierte Domains zur Erlangung des domainKey