Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Aktionen in ChatKit

Löse auf dem Server Aktionen aus, wenn jemand mit deinem Chat interagiert.

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 event

Behandle 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.title
  • Select(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 → self
  • Select.onChangeAction → none
  • Card.confirm.action → container