Wenn du volle Kontrolle brauchst, kannst du ChatKit auf deiner eigenen Infrastruktur betreiben. Das bietet sich etwa an, wenn du eine eigene Authentifizierung verwendest, Vorgaben zur Datenresidenz erfüllen musst, ChatKit vor Ort bereitstellen möchtest oder die Orchestrierung deiner Agenten selbst gestalten willst. Mit der erweiterten Self-Hosting-Option von OpenAI kannst du ChatKit anpassen und auf deinem eigenen Server betreiben.
Für ChatKit-Workflows, die Agent Builder hostet, läuft derzeit eine Übergangsphase. Setze bei neuen ChatKit-Apps auf eine eigene serverseitige Agentenimplementierung mit den ChatKit-SDKs und dem Agents SDK. Siehe Hinweise zur Umstellung von ChatKit →
ChatKit auf deiner eigenen Infrastruktur betreiben
Für eine erweiterte ChatKit-Integration entwickelst du einen eigenen ChatKit-Server und gestaltest die Chatoberfläche mit Widgets. Mit den APIs von OpenAI und deinem ChatKit-Server erstellst du einen Chat, der auf OpenAI-Modellen basiert und auf dein Produkt zugeschnitten ist.

Deinen ChatKit-Server einrichten
Die Server-Anleitung auf GitHub zeigt dir, wie du eingehende Anfragen verarbeitest, Tools ausführst und Ergebnisse an den Client streamst. Die folgenden Codebeispiele zeigen die wichtigsten Komponenten.
1. Serverpaket installieren
pip install openai-chatkit
2. Serverklasse implementieren
ChatKitServer steuert den Gesprächsverlauf. Überschreibe respond, um Ereignisse zu streamen, sobald eine Nutzernachricht oder die Ausgabe eines Client-Tools eingeht. Hilfsfunktionen wie stream_agent_response verbinden den Server mit dem Agents SDK.
class MyChatKitServer(ChatKitServer[RequestContext]):
async def respond(
self,
thread: ThreadMetadata,
input: UserMessageItem | ClientToolCallOutputItem | None,
context: RequestContext,
) -> AsyncIterator[Event]:
items_page = await self.store.load_thread_items(
thread.id,
after=None,
limit=20,
order="desc",
context=context,
)
input_items = await simple_to_agent_input(list(reversed(items_page.data)))
agent_context = AgentContext(
thread=thread,
store=self.store,
request_context=context,
)
result = Runner.run_streamed(
assistant_agent,
input_items,
context=agent_context,
)
async for event in stream_agent_response(agent_context, result):
yield event3. Endpunkt bereitstellen
Leite HTTP-Anfragen mit einem Framework deiner Wahl an die Serverinstanz weiter. Das folgende Beispiel verwendet FastAPI.
from fastapi import FastAPI, Request, Response
from fastapi.responses import StreamingResponse
app = FastAPI()
data_store = MemoryStore()
server = MyChatKitServer(data_store)
@app.post("/chatkit")
async def chatkit_endpoint(request: Request):
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")4. Schnittstelle für den Datenspeicher implementieren
Implementiere chatkit.store.Store, um Threads, Nachrichten und Dateien in der Datenbank deiner Wahl zu speichern. Für die lokale Entwicklung kannst du eine Store-Implementierung verwenden, die Daten im Arbeitsspeicher hält. Verwende im Produktivbetrieb einen persistenten Speicher. Erwäge, die Modelle als JSON-Blobs zu speichern, damit bei Bibliotheksupdates Änderungen am Schema ohne Datenmigration möglich sind.
5. Schnittstelle für den Dateispeicher bereitstellen
Wenn du Uploads unterstützt, stelle eine FileStore-Implementierung bereit. ChatKit unterstützt direkte Uploads, bei denen der Client die Datei per POST an deinen Endpunkt sendet, und zweistufige Uploads, bei denen der Client eine signierte URL anfordert und die Datei anschließend in den Cloud-Speicher hochlädt. Stelle Vorschaubilder bereit, damit der Chat Miniaturansichten direkt anzeigen kann. Implementiere auch das Löschen von Dateien, wenn ein Thread entfernt wird.
6. Client-Tools vom Server aus aufrufen
Registriere Client-Tools sowohl in den Client-Optionen als auch bei deinem Agenten. Mit ctx.context.client_tool_call kannst du aus einem Tool des Agents SDK heraus einen Aufruf in die Warteschlange stellen.
@function_tool(description_override="Add an item to the user's todo list.")
async def add_to_todo_list(ctx: RunContextWrapper[AgentContext], item: str) -> None:
ctx.context.client_tool_call = ClientToolCall(
name="add_to_todo_list",
arguments={"item": item},
)
assistant_agent = Agent[AgentContext](
model="gpt-6-astra",
name="Assistant",
instructions="You are a helpful assistant",
tools=[add_to_todo_list],
tool_use_behavior=StopAtTools(stop_at_tool_names=[add_to_todo_list.name]),
)7. Thread-Metadaten und Zustand verwenden
Speichere mit thread.metadata den serverseitigen Zustand, etwa die ID des vorherigen Laufs der Responses API oder eigene Labels. Der Client hat keinen Zugriff auf die Metadaten. Auf dem Server stehen sie bei jedem Aufruf von respond zur Verfügung.
8. Statusmeldungen von Tools empfangen
Tools mit längerer Laufzeit können ihren Fortschritt mit ProgressUpdateEvent an die Benutzeroberfläche streamen. ChatKit ersetzt das Fortschrittsereignis durch die nächste Nachricht des Assistenten oder die nächste Widget-Ausgabe.
9. Serverkontext verwenden
Übergib ein eigenes Kontextobjekt an server.process(body, context), um Berechtigungen durchzusetzen oder die Nutzeridentität in deinen Implementierungen für Daten- und Dateispeicher weiterzugeben.
Interaktive Widgets direkt im Chat einbetten
Mit Widgets können Agenten interaktive Elemente direkt im Chat anzeigen. Verwende Widgets für Karten, Formulare, Textblöcke, Listen und andere Layouts. Die Hilfsfunktion stream_widget kann ein Widget sofort rendern oder Aktualisierungen streamen, sobald sie eintreffen.
async def respond(
self,
thread: ThreadMetadata,
input: UserMessageItem | ClientToolCallOutputItem | None,
context: RequestContext,
) -> AsyncIterator[Event]:
widget = Card(
children=[
Text(
id="description",
value="Generated summary",
)
]
)
async for event in stream_widget(
thread,
widget,
generate_id=lambda item_type: self.store.generate_item_id(
item_type, thread, context
),
):
yield eventChatKit enthält zahlreiche Widget-Nodes, darunter Karten, Listen, Formulare, Text und Schaltflächen. In der Widget-Anleitung auf GitHub findest du alle Komponenten und Props sowie Hinweise zum Streaming.
Im Widget Builder kannst du Widgets in einer interaktiven Oberfläche erkunden und erstellen.
Aktionen verwenden
Mit Aktionen kann die ChatKit-Oberfläche Vorgänge auslösen, ohne eine Nutzernachricht zu senden. Weise jedem Widget-Node, der Aktionen unterstützt, bei Bedarf eine ActionConfig zu. Schaltflächen, Auswahlfelder und andere Bedienelemente können neue Thread-Einträge streamen oder vorhandene Widgets direkt aktualisieren. Befindet sich ein Widget in einem Form-Element, übermittelt ChatKit die erfassten Formularwerte in der Payload der Aktion.
Implementiere auf dem Server die Methode action von ChatKitServer, um die Payload zu verarbeiten und bei Bedarf weitere Ereignisse zu streamen. Du kannst Aktionen auch auf dem Client verarbeiten. Setze dazu handler="client" und reagiere in JavaScript auf die Aktion, bevor du weitere Aufgaben an den Server weiterleitest.
Die Anleitung zu Aktionen auf GitHub zeigt dir, wie du Aktionen verkettest, streng typisierte Payloads erstellst und die Handler auf Client und Server aufeinander abstimmst.
Ressourcen
Die folgenden Ressourcen und Referenzen helfen dir, deine Integration fertigzustellen.
Designressourcen
- Lade OpenAI Sans Variable herunter.
- Dupliziere die Datei und passe die Komponenten an dein Produkt an.
Ereignisreferenz
Die Webkomponente von ChatKit sendet Instanzen von CustomEvent. Registriere Listener für Lebenszyklusereignisse und lies die Payload aus event.detail aus.
chatkit.addEventListener("chatkit.error", (event) => {
console.error(event.detail.error);
});
chatkit.addEventListener("chatkit.response.start", () => {
console.log("Response started");
});
chatkit.addEventListener("chatkit.response.end", () => {
console.log("Response ended");
});
chatkit.addEventListener("chatkit.thread.change", (event) => {
console.log("Active thread:", event.detail.threadId);
});
chatkit.addEventListener("chatkit.log", (event) => {
console.log(event.detail.name, event.detail.data);
});Optionsreferenz
| Option | Typ | Beschreibung | Standardwert |
|---|---|---|---|
apiURL |
string |
Endpunkt, der das ChatKit-Serverprotokoll implementiert. | erforderlich |
fetch |
typeof fetch |
Überschreibt fetch-Aufrufe, etwa für eigene HTTP-Header oder die Authentifizierung. | window.fetch |
theme |
"light" | "dark" |
Farbschema der Benutzeroberfläche. | "light" |
initialThread |
string | null |
Thread, der beim Einbinden der Komponente geöffnet wird. Bei null erscheint die Ansicht für einen neuen Thread. |
null |
clientTools |
Record<string, Function> |
Tools, die dem Modell zur Verfügung stehen und auf dem Client ausgeführt werden. | |
header |
object | boolean |
Konfiguration der Kopfzeile. Mit false blendest du sie aus. |
true |
newThreadView |
object |
Passt den Begrüßungstext und die Prompts für den Gesprächseinstieg an. | |
messages |
object |
Konfiguriert Nachrichtenfunktionen wie Feedback und Anmerkungen. | |
composer |
object |
Steuert Anhänge, Entitäts-Tags und Platzhaltertext. | |
entities |
object |
Callbacks für die Entitätssuche, die Verarbeitung von Klicks und die Vorschau. |