Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Interaktive Widgets

Lektion 19 von 25 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Was ist ein ChatKit-Widget?
  2. Container und Komponenten
  3. Design des Widgets im Widget Builder
  4. Was eine Vorlage enthält
  5. Anzeige des Widgets über respond
  6. Dem Agenten die Entscheidung überlassen
  7. Eine anklickbare Liste
  8. Aktualisierung eines Widgets während der Anzeige
  9. Was ist mit den Python-Klassen?
  10. Wann ein Widget verwenden
  11. Kernaussagen

Lektion neu geschrieben am 3. November 2026. Die vorherige Version beschrieb Widgets als von Entwicklern geschriebene React-Komponenten, die in der Schnittstelle registriert wurden, und verwies auf ein nicht existierendes Modul @openai/chatkit/react. In ChatKit ist ein Widget eine deklarative Beschreibung, die Ihrer Server erstellt und die ChatKit selbst rendert. Diese Lektion folgt dem Python-SDK openai-chatkit 1.6.5, der Widgets aus .widget-Vorlagen erstellt: Die Klassen Card, Text, Badge… sind veraltet. Die Beispiele wurden auf einem lokalen ChatKit-Server ausgeführt. Quellen: ChatKit Widgets · Widgets (Python SDK) · Interaktive Antworten mit Widgets erstellen · Widget Builder.

Was ist ein ChatKit-Widget?

Eine Textantwort reicht für Erklärungen aus. Um jedoch eine Bestellung darzustellen, drei Pläne zu vergleichen oder einen Termin zu bestätigen, wird Text schnell zu einer Wand aus Zeilen, die der Nutzer erneut lesen muss. Widgets ersetzen diesen Text durch eine Schnittstelle: eine Karte, eine Liste, ein Formular oder ein Diagramm, das innerhalb des Gesprächsverlaufs angezeigt wird.

Der Ansatz ist deklarativ. Ihr Server liefert weder HTML noch eine React-Komponente: Er beschreibt das Widget in JSON unter Verwendung eines geschlossenen Satzes von Komponenten und Eigenschaften und sendet es als vollwertiges Element (ein WidgetItem) in den Thread. ChatKit zeichnet es mit seinen eigenen Komponenten, unter Verwendung der Farbschemata aus der vorherigen Lektion. Daraus ergeben sich zwei Konsequenzen:

  • Sie können nur Komponenten und Eigenschaften verwenden, die ChatKit kennt. Im Gegenzug bleibt das Rendering mit dem übrigen Interface konsistent, und kein willkürliches HTML oder JavaScript vom Server gelangt auf die Seite.
  • Das Widget ist Teil der Historie: In nachfolgenden Durchgängen wird es in Eingabe für das Modell umgewandelt, welches daher „sieht”, was es dem Nutzer gezeigt hat.

Container und Komponenten

Jedes Widget hat eine Wurzel, die aus drei Containern gewählt wird:

ContainerVerwendung
CardEigenständiger Inhalt: eine Zusammenfassung, eine Bestätigung, ein Formular. Nimmt einen Status und Bestätigungs-/Absage-Buttons unter dem Inhalt auf
ListViewEine Menge von Optionen: Restaurants, Dateien, Bestellungen. Seine Kinder sind ListViewItems mit eingebaunter „Mehr anzeigen”-Funktionalität (limit)
BasicVorbehaltlich für Entitätsvorschauen, die beim Überfahren eines Erwähnungselements angezeigt werden

Darin montieren Sie Komponenten: Text (Title, Text, Caption, Markdown), Beschriftungen (Badge), Layout (Row, Col, Box, Spacer, Divider), Medien (Image, Icon), Befehle (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, die ein Form gruppieren kann), Diagramme (Chart) und Animationen (Transition). Die Komponentenseite des Widget Builders listet die Eigenschaften jeder Komponente auf, mit einem Editor, um sie auszuprobieren.

Design des Widgets im Widget Builder

Der beabsichtigte Arbeitsablauf beginnt im Widget Builder von ChatKit Studio. Dort entwerfen Sie das Layout, füllen das Datenfeld mit Beispielwerten aus, um das Rendering zu beurteilen, und exportieren anschließend eine .widget-Datei. Dies ist eine JSON-Datei, die die Vorlage, das Schema der erwarteten Daten (jsonSchema) und die Beispielwerte kombiniert. Verwalten Sie diese Versionskontrolliert zusammen mit Ihrem Servercode, beispielsweise in einem widgets/-Ordner.

Auf der Serverseite lädt WidgetTemplate die Datei und build füllt sie mit echten Daten:

from chatkit.widgets import WidgetTemplate

order_template = WidgetTemplate.from_file("widgets/order.widget")

card = order_template.build({
    "number": "C-42",
    "status": "Shipped",
    "color": "success",
    "items": [{"name": "Keyboard", "price": "$49.90"}, {"name": "Mouse", "price": "$10.00"}],
    "total": "$59.90",
})

Ein relativer Pfad wird vom Python-Datei gelöst, die from_file aufruft, nicht vom Startverzeichnis. build akzeptiert ein Wörterbuch oder ein Pydantic-Modell.

Was eine Vorlage enthält

Die Vorlage ist ein Jinja-Modell, das das JSON des Widgets erzeugt. Die Vorlage für die Bestellkarte sieht wie folgt aus:

ORDER_TEMPLATE = """
{
  "type": "Card",
  "children": [
    {"type": "Row", "justify": "between", "align": "center", "children": [
      {"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
      {"type": "Badge", "label": {{ status | tojson }}, "color": {{ color | tojson }}}
    ]},
    {"type": "Divider"},
    {"type": "Col", "gap": 2, "children": [
      {%- for item in items %}
      {"type": "Row", "justify": "between", "children": [
        {"type": "Text", "value": {{ item.name | tojson }}},
        {"type": "Text", "value": {{ item.price | tojson }}}
      ]}{% if not loop.last %},{% endif %}
      {%- endfor %}
    ]},
    {"type": "Divider"},
    {"type": "Row", "justify": "between", "children": [
      {"type": "Text", "value": "Total", "weight": "semibold"},
      {"type": "Text", "value": {{ total | tojson }}, "weight": "semibold"}
    ]}
  ]
}
"""

order_template = WidgetTemplate({"version": "1.0", "name": "order", "template": ORDER_TEMPLATE})

Sie werden eine Vorlage selten manuell schreiben, da der Widget Builder sie generiert. Das Lesen einer jedoch spart Ihnen Zeit, wenn das erste Problem auftritt. Drei Anmerkungen:

  • Der tojson-Filter wandelt jeden Wert in gültiges JSON um (ein abgegrenzter String, ein Boolean als true oder false) und entflechtet Sonderzeichen: Ein Apostroph oder Anführungszeichen in einem Produktnamen wird das JSON nicht brechen.
  • Jinja läuft im strengen Modus: Fehlende Daten führen dazu, dass build fehlschlägt, anstatt ein halb leeres Widget zu erzeugen.
  • build validiert die Daten nicht gegen das jsonSchema. Dieses Schema dokumentiert die Daten; wenn diese von einem Werkzeug oder einer Datenbank stammen, validieren Sie sie vorher, beispielsweise mit einem Pydantic-Modell.

Der Konstruktor WidgetTemplate(...) nimmt denselben Inhalt wie eine bereits gelesene .widget-Datei auf: Dies ist praktisch für Tests oder für eine Vorlage, die von Ihrem eigenen Code generiert wird.

Anzeige des Widgets über respond

Um das Widget in den Thread zu senden, erzeugt stream_widget die entsprechenden ChatKit-Ereignisse. Sie leiten diese von Ihrer respond-Methode weiter:

from chatkit.server import stream_widget

# In Ihrer ChatKitServer-Klasse
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # Ihre Daten
    async for event in stream_widget(
        thread,
        card,
        copy_text="Order C-42: shipped, $59.90",
        generate_id=lambda item_type: self.store.generate_item_id(item_type, thread, context),
    ):
        yield event

copy_text ist der Text, der in die Zwischenablage kopiert wird, wenn der Nutzer auf die Kopier-Schaltfläche unter der Antwort klickt. Der Server speichert das Widget im Store selbst, wie jedes andere Broadcast-Element.

Dem Agenten die Entscheidung überlassen

Meistens ist es nicht Ihr Code, der entscheidet, eine Karte anzuzeigen, sondern der Agent, wenn das Gespräch dies erfordert. Geben Sie ihm ein Werkzeug, das das Widget mit AgentContext.stream_widget sendet: stream_agent_response, gesehen in Lektion 17, übermittelt es in der Mitte der Antwort an die Schnittstelle.

from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext


@function_tool(description_override="Zeigt Bestelldetails als Karte an.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
    data = await get_order_data(number)  # Ihr Datenzugriff
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Fügen Sie das Werkzeug der tools-Liste des Agenten hinzu. Der vom Werkzeug zurückgegebene String dient dem Modell, welches somit weiß, dass die Karte auf dem Bildschirm ist, und kann sich darauf beziehen, anstatt sie zu wiederholen.

Eine anklickbare Liste

Um eine Auswahl anzubieten, präsentiert ListView anklickbare Zeilen. Jedes ListViewItem kann eine Aktion tragen, die beim Klicken ausgelöst wird, ohne dass der Nutzer etwas tippen muss; die nächste Lektion zeigt, wie dies auf der Serverseite gehandhabt wird.

LIST_TEMPLATE = """
{
  "type": "ListView",
  "limit": 5,
  "children": [
    {%- for o in orders %}
    {
      "type": "ListViewItem",
      "key": {{ o.number | tojson }},
      "onClickAction": {"type": "order.open", "payload": {"number": {{ o.number | tojson }}}},
      "children": [
        {"type": "Col", "children": [
          {"type": "Text", "value": {{ ("Order " ~ o.number) | tojson }}},
          {"type": "Caption", "value": {{ o.date | tojson }}}
        ]}
      ]
    }{% if not loop.last %},{% endif %}
    {%- endfor %}
  ]
}
"""

order_list_template = WidgetTemplate({"version": "1.0", "name": "order_list", "template": LIST_TEMPLATE})
list_widget = order_list_template.build({"orders": [{"number": "C-42", "date": "November 2"}, {"number": "C-41", "date": "October 28"}]})

Neben dem limit zeigt ChatKit einen „Mehr anzeigen”-Link an.

Aktualisierung eines Widgets während der Anzeige

Ein Widget kann sich vor den Augen des Nutzers entwickeln, beispielsweise um einen Entwurf anzuzeigen, den das Modell schreibt. Geben Sie stream_widget einen asynchronen Generator, der aufeinanderfolgende Zustände des Widgets erzeugt: ChatKit berechnet die Unterschiede und sendet nur, was sich ändert.

from collections.abc import AsyncGenerator

from chatkit.widgets import DynamicWidgetRoot, WidgetTemplate

draft_template = WidgetTemplate({
    "version": "1.0",
    "name": "draft",
    "template": """{"type": "Card", "children": [
        {"type": "Title", "value": "Draft"},
        {"type": "Text", "id": "body", "value": {{ text | tojson }}, "streaming": {{ in_progress | tojson }}}
    ]}""",
})


async def streaming_draft(chunks: AsyncGenerator[str, None]) -> AsyncGenerator[DynamicWidgetRoot, None]:
    text = ""
    async for chunk in chunks:
        text += chunk
        yield draft_template.build({"text": text, "in_progress": True})
    # Endgültiger Zustand, sobald der Text vollständig ist
    yield draft_template.build({"text": text, "in_progress": False})

Nur Text- und Markdown-Komponenten mit einer id zeigen ihre Updates in einem Stream Wort für Wort an; bei anderen ersetzt ChatKit den veränderten Teil des Widgets.

Was ist mit den Python-Klassen?

Sie werden auf Widgets stoßen, die mit Klassen erstellt wurden, selbst in OpenAI-Leitfäden: Card(children=[Text(value="…")]). Diese funktionieren weiterhin, aber das SDK openai-chatkit 1.6.5 erklärt sie als veraltet zugunsten von WidgetTemplate: Die Verwendung davon sendet eine Warnung aus, die auf .widget-Dateien verweist. Für ein neues Projekt beginnen Sie mit Vorlagen. Für ein bestehendes Projekt migrieren Sie in Ihrem eigenen Tempo: Die Warnung blockiert nichts, aber eine veraltete Klasse könnte in einer zukünftigen Version verschwinden.

Wann ein Widget verwenden

Die Dokumentation nennt typische Anwendungen:

  • das Sammeln von strukturierten Eingaben mit einem Formular oder das Präsentieren eines reichen Ergebnisses (Tabelle, Karte, Diagramm), das schlecht durch Text gerendert wird;
  • das Angebot einer Auswahl zwischen mehreren Optionen;
  • die Kombination des Widgets mit Aktionen, um eine Auswahl zu validieren, einen Schritt zu bestätigen oder serverseitige Verarbeitung zu starten;
  • das Begleiten eines kurzen erläuternden Textes mit einem interaktiven Befehl.

Umgekehrt sollten Sie sie nicht überall einsetzen. Ein Widget, das Wort für Wort wiederholt, was der Text sagt, bringt nichts, und ein Gespräch, das mit Karten gesättigt ist, wird so schwer zu lesen wie eine Textwand.

Kernaussagen

  • Ein ChatKit-Widget ist eine deklarative Beschreibung (JSON), die von Ihrem Server erstellt wird, keine React-Komponente: ChatKit rendert es selbst
  • Drei Container: Card (Eigenständiger Inhalt), ListView (Liste von Optionen), Basic (Entitätsvorschauen)
  • Design im Widget Builder, exportieren Sie eine .widget-Datei, laden Sie sie mit WidgetTemplate.from_file(...), und füllen Sie sie mit build(data); die Klassen Card, Text… sind veraltet
  • Senden Sie Broadcasts mit stream_widget aus respond oder von einem Agenten-Werkzeug mit ctx.context.stream_widget
  • Ein asynchroner Generator aktualisiert das Widget live; nur Text und Markdown mit einer id streamen Wort für Wort