Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Erweiterte Integration in Ihre Anwendung

Lektion 21 von 25 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Was bleibt nach der Demo übrig
  2. Authentifizieren Sie jede Anfrage
  3. Jeder Nutzer erhält seine eigenen Konversationen
  4. Geben Sie dem Modell Ihren App-Kontext
  5. Clientseitige Werkzeuge
  6. Steuern Sie ChatKit von Ihrer Anwendung aus
  7. Beobachten Sie, was passiert
  8. Bevor Sie in die Produktion gehen
  9. Kernaussagen

Lektion neu geschrieben am 3. November 2026. Die vorherige Version stützte sich auf erfundene Eigenschaften und Ereignisse (ChatProvider, „Sidebar”-Modus, UI-basierte Persistenz). Sie orientiert sich nun an den Python-SDK openai-chatkit 1.6.5-Richtlinien (Vorbereiten Ihrer App für die Produktion, Übermitteln zusätzlichen App-Kontext, Client während einer Antwort aktualisieren) und den @openai/chatkit-react 1.6.1-Typen: Der Servercode wurde lokal ausgeführt, und der React-Code durch Kompilierung verifiziert. Quellen: Vorbereiten Ihrer App für die Produktion · Übermitteln zusätzlichen App-Kontext an Ihr Modell · Client während einer Antwort aktualisieren · Erweiterte Integrationen mit ChatKit.

Was bleibt nach der Demo übrig

Die vorherigen vier Lektionen liefern Ihnen einen funktionierenden Assistenten. Damit er in einem echten Produkt live geht, benötigt er das, was eine Demo von einem Service unterscheidet: Die Kenntnis, wer spricht, die Anzeige nur der Konversationen jedes einzelnen Nutzers, die Interaktion mit dem Rest der Anwendung und die Beobachtbarkeit. Diese Lektion behandelt diese Punkte einzeln.

Authentifizieren Sie jede Anfrage

Das SDK macht keine Annahmen über Ihre Authentifizierung: Es ermöglicht Ihnen, den Nutzer zu verifizieren und dessen Identität an server.process in einem Anfragekontext zu übermitteln. Dieser Kontext folgt jedem Aufruf: Sie finden ihn in respond, in action, im Store und in den Werkzeugen des Agents.

Auf der Schnittstellenseite ersetzt die api.fetch-Option die fetch-Funktion, die von ChatKit verwendet wird. Hier fügen Sie den Sitzungstoken Ihrer Anwendung hinzu:

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) => {
        // Header beibehalten, die von ChatKit gesetzt wurden, und unsere hinzufügen
        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]" />;
}

Auf der Serverseite verifiziert eine FastAPI-Abhängigkeit den Token und erstellt den Kontext. Die Schnittstellensprache kommt im Accept-Language-Header an, den ChatKit mit jeder Anfrage sendet:

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)  # Ihre Authentifizierung: Sitzung, 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")

Jeder Nutzer erhält seine eigenen Konversationen

Authentifizierung reicht nicht aus: Sie benötigen auch Autorisierung. Ohne Kontrolle könnte ein Nutzer, der eine Thread-ID errät, die Konversation eines anderen lesen. Der richtige Ort für diese Kontrolle ist der Store, durch den alle Lesevorgänge laufen. In diesem Beispiel speichert jeder Thread den Namen des Eigentümers in seinen Metadaten, die das SDK niemals an die Schnittstelle übermittelt:

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")  # Offenbaren Sie nicht, dass er existiert
        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

Der try-Block im Endpunkt macht hier Sinn: Ohne ihn würde das direkte Lesen eines Threads eines anderen Nutzers mit einem 500-Fehler enden, statt mit einem 404; bei einer gestreamten Anfrage, wie dem Hinzufügen einer Nachricht, unterbricht das SDK den Stream, ohne etwas zu senden. In der Produktion erfolgt dieses Filtern direkt in der SQL-Abfrage selbst (ein WHERE owner = … behandelt auch die Paginierung korrekt). Wenden Sie dieselbe Regel auf Anhänge an. Die Dokumentation erinnert Sie auch daran, zu entscheiden, was Sie speichern und wie lange: Threads enthalten Text, Dateien und Werkzeugergebnisse, also oft personenbezogene Daten.

Geben Sie dem Modell Ihren App-Kontext

Das Modell weiß nichts über die Seite, die der Nutzer betrachtet, sein Abonnement oder das offene Dokument. Die Dokumentation schlägt drei Wege vor, es zu unterrichten:

  • Bei jeder Anfrage, über Header, die in api.fetch hinzugefügt werden (X-Page, X-Plan…), die der Server im Kontext speichert;
  • Auf Abruf, über ein Server-Werkzeug, das ctx.context.request_context liest und die Informationen abruft;
  • Im Browser, über ein clientseitiges Werkzeug, wenn die Informationen nur dort existieren (siehe den nächsten Abschnitt).

Eine Vorsichtsmaßnahme, die aus der Produktionsanleitung stammt: Erstellen Sie niemals die Systemanweisungen des Modells aus Werten, die vom Nutzer kommen, auch nicht indirekt (Thread-Titel, Ticket-Betreff). Halten Sie diese fest und übermitteln Sie den variablen Kontext als Daten.

Clientseitige Werkzeuge

Einige Informationen leben nur im Browser: Auswahl in einem Editor, Canvas-Zustand, ein unveröffentlichter Entwurf. Ein clientseitiges Werkzeug ermöglicht es dem Modell, diese in der Mitte eines Durchgangs anzufordern: Ihr Server pausiert den Agenten, ChatKit führt Ihre Funktion im Browser aus und gibt das Ergebnis an den Server zurück, der den Vorgang wieder aufnimmt.

Auf der Serverseite macht das Werkzeug nur die Anfrage, und der Agent stoppt daran:

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]),
)

Auf der Schnittstellenseite empfängt onClientTool die Anfrage; der Name muss übereinstimmen, und das zurückgegebene Objekt geht an den Server:

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onClientTool: async ({ name }) => {
    if (name === 'read_selection') {
      return { text: window.getSelection()?.toString() ?? '' };
    }
    return {};
  },
});

Nur ein clientseitiges Werkzeug kann pro Durchgang ausgeführt werden. Und wenn Sie keine Antwort erwarten, bevorzugen Sie einen Effekt: Der Server sendet ein ClientEffectEvent(name="refresh_cart", data={...}), von respond, action oder einem Werkzeug über ctx.context.stream(...), und die Schnittstelle empfängt es in onEffect, ohne die Antwort zu unterbrechen. Effekte werden nicht im Thread gespeichert.

Steuern Sie ChatKit von Ihrer Anwendung aus

useChatKit gibt zusätzlich zu control Methoden zurück, um die Schnittstelle vom Rest Ihres Codes aus zu steuern:

MethodeEffekt
sendUserMessage({ text })Sendet eine Nachricht, als hätte der Nutzer sie eingegeben
setComposerValue({ text })Füllt das Eingabefeld vorab, ohne zu senden
setThreadId(id)Öffnet einen bestehenden Thread oder einen neuen Thread mit null
focusComposer()Platziert den Cursor im Eingabefeld
showHistory(), hideHistory()Öffnet oder schließt die Konversationshistorie
sendCustomAction(action)Sendet eine Aktion an den Server (Lektion 20)
fetchUpdates()Lädt den Thread vom Server neu

Eine Schaltfläche „Assistent fragen” auf einem Produktdatenblatt wird zu einer Zeile 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]" />
    </>
  );
}

Die initialThread-Option öffnet einen spezifischen Thread beim Mounten, beispielsweise den, den der Nutzer offen gelassen hat; mit null (der Standardwert) zeigt ChatKit den Startbildschirm an.

Beobachten Sie, was passiert

ChatKit sendet Ereignisse: Bereit (onReady), Antwortstart und -ende (onResponseStart, onResponseEnd), Thread-Änderung (onThreadChange), Logs (onLog) und Fehler (onError). In React sind dies Optionen für 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 }),
});

Die Produktionsanleitung besteht auf einem Punkt: Diese Ereignisse können personenbezogene Daten und Nachrichtentext enthalten. Senden Sie nicht den gesamten Inhalt an Ihr Tracking-Tool: Extrahieren Sie nützliche Felder (Ereignisname, Thread-ID, Fehlercode). Auf der Serverseite protokollieren Sie jede Anfrage an /chatkit, Aufrufe an den Store und das Modell sowie Werkzeugfehler, zusammen mit der Nutzer- und Thread-ID, damit Sie beide Seiten korrelieren können.

Bei langsamen Werkzeugen halten Sie den Nutzer informiert: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) zeigt sofortigen Fortschritt an, wird durch den Rest der Antwort ersetzt und niemals im Thread gespeichert.

Bevor Sie in die Produktion gehen

Die Checkliste, entnommen aus der offiziellen Anleitung:

  • Domänen: Jeder Produktions-Hostname ist auf der Domain allowlist-Seite der OpenAI-Plattform aufgeführt, und sein Schlüssel befindet sich in domainKey;
  • Authentifizierung und Autorisierung: Jede Anfrage an /chatkit wird authentifiziert, Threads und Anhänge werden nach Nutzer gefiltert;
  • Geheimnisse: Der API-Schlüssel und interne Credentials befinden sich in Umgebungsvariablen oder einem Secrets Manager, niemals im Repository;
  • Eingaben: Nachrichten, Dateien, Aktionslasten und Werkzeugergebnisse werden als unzuverlässig behandelt und validiert, bevor sie Ihre Systeme erreichen;
  • Personenbezogene Daten: Speicherfrist festgelegt und im Store angewendet, Verschlüsselung im Ruhezustand, keine unnötigen Daten in Metadaten;
  • Sprache: Die Accept-Language-Sprache steuert die Antworten des Agents und Ihre Werkzeugnachrichten;
  • Tracking: Schnittstellenevents und Server-Logs gesammelt, ohne sensible Inhalte.

Kernaussagen

  • Die Identität des Nutzers geht über api.fetch auf der Schnittstellenseite, dann über den Kontext von server.process und verbreitet sich überallhin
  • Autorisierung erfolgt im Store: Jeder Thread gehört einem Nutzer, und der Thread eines anderen Nutzers ist „nicht gefunden”
  • App-Kontext kommt über Header, Server-Werkzeuge oder clientseitige Werkzeuge (onClientTool + StopAtTools) an; Effekte (onEffect) dienen, wenn keine Antwort erwartet wird
  • Methoden von useChatKit (sendUserMessage, setThreadId, setComposerValue…) steuern ChatKit vom Rest der Anwendung aus
  • Ereignisse (onError, onLog…) füttern Ihr Tracking, ohne personenbezogene Daten darin zu kopieren; die Produktionscheckliste deckt Domänen, Rechte, Geheimnisse, Eingaben und Daten ab