Mit Aktionen kann das Frontend des ChatKit SDK eine Streaming-Antwort auslösen, ohne dass jemand eine Nachricht senden muss. Aktionen können auch Seiteneffekte außerhalb des ChatKit SDK auslösen.
Aktionen auslösen
Auf Interaktionen mit Widgets reagieren
Um eine Aktion auszulösen, kannst du eine ActionConfig an jeden Widget-Node binden, der sie unterstützt. So kannst du zum Beispiel auf Klicks auf eine Schaltfläche reagieren. Klickt jemand auf diese Schaltfläche, sendet ChatKit die Aktion an deinen Server. Dort kannst du unter anderem das Widget aktualisieren, eine Inferenz ausführen oder neue Thread-Elemente streamen.
button = Button(
label="Example",
onClickAction=ActionConfig(
type="example",
payload={"id": 123},
),
)Dein Frontend kann Aktionen auch direkt mit sendCustomAction() senden. Das ist vor allem dann hilfreich, wenn ChatKit auf eine Interaktion außerhalb von ChatKit reagieren soll. Du kannst damit auch Aktionen verketten, wenn sowohl der Client als auch der Server reagieren sollen (mehr dazu weiter unten).
await chatKit.sendCustomAction({
type: "example",
payload: { id: 123 },
});Aktionen verarbeiten
Auf dem Server
Standardmäßig sendet ChatKit Aktionen an deinen Server. Um sie dort zu verarbeiten, implementiere die Methode action in ChatKitServer.
class MyChatKitServer(ChatKitServer[RequestContext]):
async def action(
self,
thread: ThreadMetadata,
action: Action[str, Any],
sender: WidgetItem | None,
context: RequestContext,
) -> AsyncIterator[Event]:
if action.type == "example":
await do_thing(action.payload["id"])
# Often you'll want to add a HiddenContextItem so the model
# can see that the user did something.
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="<USER_ACTION>The user did a thing</USER_ACTION>",
),
context,
)
# Then you might want to run inference to stream a response
# back to the user.
async for event in self.generate(context, thread):
yield eventBehandle Aktionen und ihre Payloads als nicht vertrauenswürdige Daten, da der Client sie an deinen Server sendet.
Auf dem Client
Manchmal ist es sinnvoll, Aktionen in deiner Client-Integration zu verarbeiten. Damit ChatKit die Aktion an den clientseitigen Aktionshandler sendet, füge handler="client" zur ActionConfig hinzu.
button = Button(
label="Example",
onClickAction=ActionConfig(type="example", payload={"id": 123}, handler="client"),
)Wird die Aktion ausgelöst, übergibt ChatKit sie an den Callback, den du beim Erstellen der ChatKit-Instanz angibst.
async function handleWidgetAction(action: { type: string }) {
if (action.type === "example") {
const res = await doSomething(action);
// You can fire off actions to your server from here as well.
// For example, stream new thread items or update a widget.
await chatKit.sendCustomAction({
type: "example_complete",
payload: res,
});
}
}
chatKit.setOptions({
// Other options...
widgets: { onAction: handleWidgetAction },
});Stark typisierte Aktionen
Standardmäßig sind Action und ActionConfig nicht stark typisiert. Mit der Hilfsmethode create von Action kannst du jedoch aus einer Menge stark typisierter Aktionen Objekte vom Typ ActionConfig erzeugen.
class ExamplePayload(BaseModel):
id: int
ExampleAction = Action[Literal["example"], ExamplePayload]
OtherAction = Action[Literal["other"], None]
AppAction = Annotated[
ExampleAction | OtherAction,
Field(discriminator="type"),
]
ActionAdapter: TypeAdapter[AppAction] = TypeAdapter(AppAction)
def parse_app_action(action: Action[str, Any]) -> AppAction:
return ActionAdapter.validate_python(action)
# Usage in a widget
# Action provides a create helper which makes it easy to generate
# ActionConfigs from strongly typed actions.
button = Button(
label="Example",
onClickAction=ExampleAction.create(ExamplePayload(id=123)),
)
# usage in action handler
class MyChatKitServer(ChatKitServer[RequestContext]):
async def action(
self,
thread: ThreadMetadata,
action: Action[str, Any],
sender: WidgetItem | None,
context: RequestContext,
) -> AsyncIterator[Event]:
# add custom error handling if needed
app_action = parse_app_action(action)
if app_action.type == "example":
await do_thing(app_action.payload.id)
yield ThreadItemDoneEvent(
item=AssistantMessageItem(
id=self.store.generate_item_id("message", thread, context),
thread_id=thread.id,
created_at=datetime.now(),
content=[AssistantMessageContent(text="Action complete.")],
)
)Eigene Formulare mit Widgets und Aktionen erstellen
Wenn du Widget-Nodes für Eingaben in ein Form einbindest, enthält der payload jeder Aktion, die innerhalb dieses Form ausgelöst wird, die Werte dieser Felder.
Im payload dient der name des jeweiligen Feldes als Schlüssel für den Formularwert. Beispiele:
Select(name="title")→action.payload.titleSelect(name="todo.title")→action.payload.todo.title
form = Form(
direction="col",
onSubmitAction=ActionConfig(
type="update_todo",
payload={"id": todo.id},
),
children=[
Title(value="Edit Todo"),
Text(value="Title", color="secondary", size="sm"),
Text(
value=todo.title,
editable=EditableProps(name="title", required=True),
),
Text(value="Description", color="secondary", size="sm"),
Text(
value=todo.description,
editable=EditableProps(name="description"),
),
Button(label="Save", submit=True),
],
)
class MyChatKitServer(ChatKitServer[RequestContext]):
async def action(
self,
thread: ThreadMetadata,
action: Action[str, Any],
sender: WidgetItem | None,
context: RequestContext,
) -> AsyncIterator[Event]:
if action.type == "update_todo":
todo_id = action.payload["id"]
# Any action that originates from within the Form will
# include title and description.
title = action.payload["title"]
description = action.payload["description"]
await update_todo(todo_id, title, description)
yield ThreadItemDoneEvent(
item=AssistantMessageItem(
id=self.store.generate_item_id("message", thread, context),
thread_id=thread.id,
created_at=datetime.now(),
content=[AssistantMessageContent(text="Todo updated.")],
)
)Validierung
Form nutzt die native Formularvalidierung. Sie prüft die Vorgaben required und pattern für die Felder, bei denen sie konfiguriert sind. Sobald ein Feld ungültig ist, lässt sich das Formular nicht absenden.
Künftig könnten weitere Validierungsmodi hinzukommen, etwa für eine bessere Bedienbarkeit, differenziertere Prüfregeln oder eine anpassbare Fehleranzeige. Bis dahin eignen sich Widgets nur bedingt für komplexe Formulare mit anspruchsvollen Prüfregeln. Wenn du ein solches Formular brauchst, öffne über den clientseitigen Aktionshandler ein modales Dialogfenster, zeige dort dein eigenes Formular an und übergib das Ergebnis mit sendAction zurück an ChatKit.
Card als Form verwenden
Wenn du asForm=True an Card übergibst, verhält sich die Karte wie ein Form. Sie führt die Validierung aus und übergibt die erfassten Feldwerte an ihre confirm-Aktion.
Namenskonflikte bei Payload-Schlüsseln
Wenn ein Feldname mit einem bereits vorhandenen, vordefinierten Schlüssel in der Payload übereinstimmt, ignoriert ChatKit den Formularwert. Da ein solcher Konflikt wahrscheinlich auf einen Fehler hindeutet, löst ChatKit in diesem Fall ein error-Ereignis aus.
Ladezustände in Widgets steuern
Mit ActionConfig.loadingBehavior legst du fest, welche Ladezustände Aktionen in einem Widget auslösen.
button = Button(
label="This may take a while...",
onClickAction=ActionConfig(
type="long_running_action_that_should_block_other_ui_interactions",
loadingBehavior="container",
),
)| Wert | Verhalten |
|---|---|
auto |
Das Verhalten hängt davon ab, wie die Aktion verwendet wird. (Standard) |
self |
Die Aktion versetzt den Widget-Node, an den sie gebunden ist, in den Ladezustand. |
container |
Die Aktion versetzt den gesamten Widget-Container in den Ladezustand. Das Widget wird leicht ausgeblendet und reagiert nicht mehr auf Eingaben. |
none |
Kein Ladezustand |
auto verwenden
In der Regel empfehlen wir die Standardeinstellung auto. Bei auto hängt der Ladezustand davon ab, wo die Aktion gebunden ist. Beispiele:
Button.onClickAction→selfSelect.onChangeAction→noneCard.confirm.action→container