Interaktive Widgets
Auf dieser Seite
- Was ist ein ChatKit-Widget?
- Container und Komponenten
- Design des Widgets im Widget Builder
- Was eine Vorlage enthält
- Anzeige des Widgets über respond
- Dem Agenten die Entscheidung überlassen
- Eine anklickbare Liste
- Aktualisierung eines Widgets während der Anzeige
- Was ist mit den Python-Klassen?
- Wann ein Widget verwenden
- 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-SDKopenai-chatkit1.6.5, der Widgets aus.widget-Vorlagen erstellt: Die KlassenCard,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:
| Container | Verwendung |
|---|---|
Card | Eigenständiger Inhalt: eine Zusammenfassung, eine Bestätigung, ein Formular. Nimmt einen Status und Bestätigungs-/Absage-Buttons unter dem Inhalt auf |
ListView | Eine Menge von Optionen: Restaurants, Dateien, Bestellungen. Seine Kinder sind ListViewItems mit eingebaunter „Mehr anzeigen”-Funktionalität (limit) |
Basic | Vorbehaltlich 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 alstrueoderfalse) 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
buildfehlschlägt, anstatt ein halb leeres Widget zu erzeugen. buildvalidiert die Daten nicht gegen dasjsonSchema. 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 mitWidgetTemplate.from_file(...), und füllen Sie sie mitbuild(data); die KlassenCard,Text… sind veraltet - Senden Sie Broadcasts mit
stream_widgetausrespondoder von einem Agenten-Werkzeug mitctx.context.stream_widget - Ein asynchroner Generator aktualisiert das Widget live; nur
TextundMarkdownmit eineridstreamen Wort für Wort