Benutzeraktionen
Auf dieser Seite
Lektion am 3. November 2026 überarbeitet. Die vorherige Version behandelte Klicks in benutzerdefinierten React-Komponenten und erfand „Vorschlagsaktionen”. In ChatKit ist eine Aktion ein Objekt, das an ein Widget-Komponente (Button, Listenzeile, Formular) angehängt ist. Standardmäßig wird sie auf Ihrem Server in der
action-Methode vonChatKitSerververarbeitet, oder im Browser, wenn Sie dies explizit angeben. Diese Lektion folgt dem Leitfaden Aktionen in ChatKit und dem SDKopenai-chatkit1.6.5. Der Server, die Vorlagen und das Formular wurden lokal ausgeführt; der React-Code wurde durch Kompilierung verifiziert. Quellen: Aktionen in ChatKit · Interaktive Antworten mit Widgets erstellen · Release-Notes Python SDK 1.6.2.
Was ist eine Aktion?
Ein Widget, das nur Inhalte anzeigt, ist lediglich eine hübsche Antwort. Aktionen machen es nützlich: Ein Klick auf „Bestellung stornieren”, die Auswahl einer Zeile in einer Liste oder das Absenden eines Formulars löst eine Verarbeitung aus, ohne dass der Benutzer eine Nachricht tippen muss. ChatKit sendet die Aktion an Ihren Server, der in Ihren Systemen handeln, das Widget aktualisieren, eine Antwort an den Thread anhängen oder den Agenten neu starten kann.
Sie deklarieren eine Aktion in der Widget-Vorlage auf einer Komponente, die eine akzeptiert (onClickAction für ein Button oder ListViewItem, onChangeAction für ein Select, onSubmitAction für ein Form, confirm und cancel für ein Card). Es handelt sich um ein kleines JSON-Objekt:
| Feld | Rolle |
|---|---|
type | Der Aktionsname, den Ihr Code prüft: "order.cancel" |
payload | Nützliche Daten: {"number": "C-42"} |
handler | "server" (Standard) oder "client", um sie im Browser zu verarbeiten |
loadingBehavior | Der Ladezustand, der während der Verarbeitung angezeigt wird (siehe unten) |
Verarbeitung einer Aktion auf dem Server
Nehmen wir eine Bestellkarte, die eine Stornierung anbietet. Die Vorlage deklariert die Aktion auf den Bestätigungs- und Stornierungsknöpfen des Card:
CANCEL_TEMPLATE = """
{
"type": "Card",
"children": [
{"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
{"type": "Text", "value": "Möchten Sie diese Bestellung wirklich stornieren?"}
],
"confirm": {"label": "Bestellung stornieren",
"action": {"type": "order.cancel", "payload": {"number": {{ number | tojson }}}}},
"cancel": {"label": "Bestellung behalten",
"action": {"type": "order.keep", "payload": {"number": {{ number | tojson }}}}}
}
"""
Fügen Sie auf der Serverseite eine action-Methode zu Ihrem ChatKitServer hinzu. Sie erhält den Thread, die Aktion, das Widget, das sie ausgelöst hat (sender), und Ihren Kontext, und gibt Ereignisse wie respond zurück:
from datetime import datetime
from typing import Any, AsyncIterator
from chatkit.actions import Action
from chatkit.server import ChatKitServer
from chatkit.types import (
AssistantMessageContent,
AssistantMessageItem,
HiddenContextItem,
ThreadItemDoneEvent,
ThreadMetadata,
ThreadStreamEvent,
WidgetItem,
)
class MyChatKitServer(ChatKitServer[dict[str, Any]]):
# respond(...) : wie in Lektion 17
def message(self, thread: ThreadMetadata, context: dict[str, Any], text: str) -> ThreadItemDoneEvent:
return ThreadItemDoneEvent(
item=AssistantMessageItem(
thread_id=thread.id,
id=self.store.generate_item_id("message", thread, context),
created_at=datetime.now(),
content=[AssistantMessageContent(text=text)],
)
)
async def action(
self,
thread: ThreadMetadata,
action: Action[str, Any],
sender: WidgetItem | None,
context: dict[str, Any],
) -> AsyncIterator[ThreadStreamEvent]:
if action.type == "order.cancel":
number = str((action.payload or {}).get("number", ""))
# Die Payload stammt aus dem Browser: Berechtigungen erneut überprüfen
if not await is_user_order(number, context.get("user_id")):
yield self.message(thread, context, "Diese Bestellung gehört Ihnen nicht.")
return
await cancel_order(number)
# Ein Spur für das Modell, dem Benutzer niemals angezeigt
await self.store.add_thread_item(
thread.id,
HiddenContextItem(
id=self.store.generate_item_id("message", thread, context),
thread_id=thread.id,
created_at=datetime.now(),
content=f"<USER_ACTION>Benutzer hat Bestellung {number} storniert.</USER_ACTION>",
),
context,
)
yield self.message(thread, context, f"Fertig: Bestellung {number} wurde storniert.")
elif action.type == "order.keep":
yield self.message(thread, context, "Sehr gut, die Bestellung wird behalten.")
Aus diesem Code ergeben sich drei Regeln:
- Die Payload ist nicht vertrauenswürdig. Sie kommt aus dem Browser, wo jeder sie ändern kann: Der OpenAI-Leitfaden verlangt, sie als unverifizierte Daten zu behandeln. Bevor die Stornierung ausgeführt wird, überprüft der Server, ob die Bestellung dem authentifizierten Benutzer gehört. Die
user_idim Kontext ist diejenige, die Ihr authentifizierter Endpunkt dort einträgt (Lektion 21). - Das Modell muss wissen, was passiert ist. Ein Klick ist keine Nachricht: Ohne eine Spur würde der Agent im nächsten Turn ignorieren, dass die Bestellung storniert wurde. Ein
HiddenContextItemfügt diese Information dem Thread hinzu, ohne sie anzuzeigen. Das SDK zeichnet automatisch nur Broadcast-Elemente auf, und ein verstecktes Element darf niemals verbreitet werden: Sie müssen es selbst dem Speicher hinzufügen. - Die Antwort ist ein Stream von Ereignissen. Hier eine einfache Nachricht; es könnte ein aktualisiertes Widget sein, das mit
stream_widgetwie in der vorherigen Lektion verbreitet wird.
Damit der Agent kommentiert, was gerade passiert ist, starten Sie ihn nach der Aktion neu: async for event in self.respond(thread, None, context): yield event. Ihre respond-Methode liest den Thread erneut, findet das versteckte Element und antwortet entsprechend.
Formulare
Wenn Eingabefelder (Input, Textarea, Select, Checkbox, DatePicker …) in ein Form platziert werden, werden ihre Werte der Payload jeder Aktion hinzugefügt, die von diesem Formular ausgegeben wird, unter dem Namen jedes Feldes:
REPORT_TEMPLATE = """
{
"type": "Card",
"children": [
{"type": "Form", "direction": "col", "gap": 3,
"onSubmitAction": {"type": "ticket.create", "payload": {"source": "chat"}},
"children": [
{"type": "Title", "value": "Problem melden", "size": "sm"},
{"type": "Label", "value": "Bestellnummer", "fieldName": "order"},
{"type": "Input", "name": "order", "required": true, "pattern": "C-[0-9]+", "placeholder": "C-42"},
{"type": "Label", "value": "Kategorie", "fieldName": "category"},
{"type": "Select", "name": "category", "placeholder": "Auswählen",
"options": [{"label": "Beschädigte Sendung", "value": "damaged"},
{"label": "Verspätung", "value": "delay"},
{"label": "Sonstiges", "value": "other"}]},
{"type": "Textarea", "name": "detail", "rows": 3, "placeholder": "Beschreiben Sie das Problem"},
{"type": "Button", "label": "Absenden", "submit": true}
]}
]
}
"""
Beim Absenden enthält action.payload source, order, category und detail. Ein gepunkteter Name, "client.name", erzeugt einen verschachtelten Wert: payload["client"]["name"]. Wenn sich ein Feldname mit einem Schlüssel, der bereits in der Payload vorhanden ist, überschneidet, wird der Feldwert ignoriert und ChatKit sendet ein Fehlerereignis: Wählen Sie eindeutige Namen.
Die Formularvalidierung erfolgt browserseitig: required und pattern blockieren das Absenden, solange ein Feld ungültig ist. Dies ist eine Benutzerfreundlichkeit, kein Schutz: Validieren Sie auf dem Server erneut, beispielsweise mit einem Pydantic-Modell.
from typing import Literal
from pydantic import BaseModel, Field, ValidationError
class Report(BaseModel):
order: str = Field(pattern=r"^C-[0-9]+$")
category: Literal["damaged", "delay", "other"]
detail: str = Field(default="", max_length=2000)
# In der action-Methode
if action.type == "ticket.create":
try:
report = Report.model_validate(action.payload or {})
except ValidationError:
yield self.message(thread, context, "Das Formular ist unvollständig oder ungültig.")
return
ticket_number = await create_ticket(report, context.get("user_id"))
yield self.message(thread, context, f"Ticket {ticket_number} erstellt, wir melden uns bei Ihnen.")
Für eine reichhaltigere Validierung mit benutzerdefinierten Fehlermeldungen rät die Dokumentation, außerhalb des Widgets zu arbeiten: Eine clientseitige Aktion öffnet ein Fenster in Ihrer Anwendung, und das Ergebnis kehrt über sendCustomAction zu ChatKit zurück. Beachten Sie auch, dass ein Card, das mit "asForm": true deklariert ist, wie ein Formular verhält: Seine Felder werden validiert und an seine confirm-Aktion übergeben.
Bestätigung vor Ausführung
Die Stornierungskarte am Anfang illustriert eine Regel, die verallgemeinert werden soll: eine irreversible oder sensible Aktion erfordert eine explizite Bestätigung. Eine Bestellung stornieren, eine E-Mail senden, eine Rückerstattung durchführen, löschen: Der Agent schlägt vor, der Benutzer validiert auf einer Karte, die klar darlegt, was passieren wird, und es ist Ihr Server, nicht das Modell, der nach erneuter Überprüfung der Berechtigungen ausführt. Die confirm- und cancel-Knöpfe eines Card sind dafür gemacht. Ihr Standard-Ladezustand grau durch die gesamte Karte während der Verarbeitung, was Doppelklicks verhindert.
Verarbeitung einer Aktion im Browser
Manche Aktionen müssen auf dem Server nichts tun: Eine Seite in Ihrer Anwendung öffnen, einen Link kopieren, ein Modal anzeigen. Deklarieren Sie sie mit "handler": "client" in der Vorlage, beispielsweise {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Sie gelangen dann in die widgets.onAction-Option der Schnittstelle:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function AssistantOrders() {
const chatkit = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
widgets: {
onAction: async (action, widgetItem) => {
if (action.type === 'order.track') {
window.open(`/orders/${String(action.payload?.number ?? '')}`, '_blank');
// Benachrichtigen Sie den Server, der das Widget aktualisieren kann
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction sendet eine Aktion an Ihren Server, als käme sie von einem Widget. Es funktioniert auch außerhalb von ChatKit: Ein Knopf auf Ihrer Seite kann chatkit.sendCustomAction({ type: 'cart.empty' }) aufrufen, damit der Assistent auf das reagiert, was anderswo in der Anwendung passiert.
Ladezustände
loadingBehavior steuert, was der Benutzer während der Verarbeitung einer Aktion sieht:
| Wert | Effekt |
|---|---|
auto (Standard) | Passt sich der Komponente an: nur der Knopf für ein Button, nichts für ein Select, die gesamte Karte für das confirm eines Card |
self | Ladezustand auf der einzelnen Komponente, die die Aktion enthält |
container | Das gesamte Widget wird ausgeblendet und inaktiv |
none | Kein Ladezustand |
Die Dokumentation empfiehlt, auto beizubehalten, es sei denn, Sie haben einen spezifischen Bedarf. Standardmäßig werden Aktionen auf einem Widget auch blockiert, während eine Antwort gestreamt wird, um Konflikte zu vermeiden. Seit SDK-Version 1.6.2 wird eine Aktion, die mit "streaming": false deklariert ist, diesem Blockieren entzogen: Sie wird von der sync_action-Methode des Servers verarbeitet, die für Aktionen reserviert ist, die nur ihr eigenes Widget aktualisieren oder außerhalb des Threads handeln.
Kernaussagen
- Eine Aktion ist ein Objekt
{type, payload, handler, loadingBehavior}, das an eine Widget-Komponente angehängt ist; sie löst eine Verarbeitung aus, ohne dass eine Benutzer-Nachricht erforderlich ist - Auf dem Server erhält die
action-Methode vonChatKitServerdiese und gibt Ereignisse zurück: Nachricht, aktualisiertes Widget oder neue Agenten-Antwort überrespond - Die Payload stammt aus dem Browser: Überprüfen Sie Berechtigungen und Daten auf dem Server erneut (Pydantic), auch wenn das Formular bereits
requiredundpatternvalidiert - Ein
HiddenContextItem, manuell dem Speicher hinzugefügt, informiert das Modell darüber, was der Benutzer getan hat - Sensible Aktionen gehen durch eine Bestätigungskarte; rein lokale Aktionen werden im Browser verarbeitet (
handler: "client",widgets.onAction,sendCustomAction)