Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Acties van gebruikers

Les 20 van 25 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Wat is een actie?
  2. Een actie op de server verwerken
  3. Formulieren
  4. Bevestigen voordat u handelt
  5. Een actie in de browser verwerken
  6. Laadstatussen
  7. Belangrijkste punten

Les herschreven op 3 november 2026. De vorige versie behandelde klikken in aangepaste React-componenten en verzon “suggestieacties”. In ChatKit is een actie een object dat aan een widgetcomponent (knop, lijstrij, formulier) is gekoppeld. Standaard wordt deze op uw server verwerkt in de action-methode van ChatKitServer, of in de browser als u anders specificeert. Deze les volgt de gids Actions in ChatKit en de openai-chatkit SDK 1.6.5. De server, sjablonen en het formulier zijn lokaal uitgevoerd; de React-code is geverifieerd door compilatie. Bronnen: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Wat is een actie?

Een widget die alleen inhoud weergeeft, is slechts een mooi antwoord. Acties maken het nuttig: klikken op “Bestelling annuleren”, selecteren van een rij in een lijst, of het indienen van een formulier start verwerking zonder dat de gebruiker een bericht hoeft te typen. ChatKit stuurt de actie naar uw server, die actie kan ondernemen in uw systemen, de widget kan bijwerken, een antwoord aan de thread kan toevoegen, of de agent opnieuw kan starten.

U declareert een actie in het widgetsjabloon op een component die er een accepteert (onClickAction voor een Button of ListViewItem, onChangeAction voor een Select, onSubmitAction voor een Form, confirm en cancel voor een Card). Het is een klein JSON-object:

VeldRol
typeDe actienaam die uw code test: "order.cancel"
payloadNuttige gegevens: {"number": "C-42"}
handler"server" (standaard) of "client" om deze in de browser te verwerken
loadingBehaviorDe laadstatus die tijdens de verwerking wordt weergegeven (zie hieronder)

Een actie op de server verwerken

Laten we een bestellingskaart nemen die annulering aanbiedt. Het sjabloon declareert de actie op de bevestigings- en annuleringsknoppen van de Card:

CANCEL_TEMPLATE = """
{
  "type": "Card",
  "children": [
    {"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
    {"type": "Text", "value": "Do you really want to cancel this order?"}
  ],
  "confirm": {"label": "Cancel Order",
              "action": {"type": "order.cancel", "payload": {"number": {{ number | tojson }}}}},
  "cancel": {"label": "Keep Order",
             "action": {"type": "order.keep", "payload": {"number": {{ number | tojson }}}}}
}
"""

Voeg aan de serverzijde een action-methode toe aan uw ChatKitServer. Deze ontvangt de thread, de actie, de widget die deze heeft gegenereerd (sender), en uw context, en retourneert gebeurtenissen zoals respond:

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(...) : zoals in les 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", ""))
            # De payload komt van de browser: verifieer rechten opnieuw
            if not await is_user_order(number, context.get("user_id")):
                yield self.message(thread, context, "This order does not belong to you.")
                return
            await cancel_order(number)
            # Een spoor voor het model, nooit getoond aan de gebruiker
            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>User canceled order {number}.</USER_ACTION>",
                ),
                context,
            )
            yield self.message(thread, context, f"Done: order {number} is canceled.")
        elif action.type == "order.keep":
            yield self.message(thread, context, "Very well, the order is kept.")

Drie regels komen uit deze code naar voren:

  • De payload is niet vertrouwd. Deze komt vanuit de browser, waar iedereen deze kan wijzigen: de OpenAI-gids vereist dat deze als ongeverifieerde gegevens wordt behandeld. Voordat er wordt geannuleerd, controleert de server of de bestelling toebehoort aan de geauthenticeerde gebruiker. De user_id in de context is degene die uw geauthenticeerde endpoint daar plaatst (les 21).
  • Het model moet weten wat er is gebeurd. Een klik is geen bericht: zonder spoor zou de agent bij de volgende beurt negeren dat de bestelling is geannuleerd. Een HiddenContextItem voegt deze informatie toe aan de thread zonder deze weer te geven. De SDK legt automatisch alleen broadcast-elementen vast, en een verborgen element mag nooit worden uitgezonden: u moet het zelf aan de store toevoegen.
  • Het antwoord is een stroom van gebeurtenissen. Hier een eenvoudig bericht; het zou een bijgewerkte widget kunnen zijn, uitgezonden met stream_widget zoals in de vorige les.

Om de agent commentaar te laten geven op wat zojuist is gebeurd, start u deze opnieuw na de actie: async for event in self.respond(thread, None, context): yield event. Uw respond-methode leest de thread opnieuw, vindt het verborgen element en reageert dienovereenkomstig.

Formulieren

Wanneer invoervelden (Input, Textarea, Select, Checkbox, DatePicker…) binnen een Form worden geplaatst, worden hun waarden toegevoegd aan de payload van elke actie die vanuit dat formulier wordt verzonden, onder de naam van elk veld:

REPORT_TEMPLATE = """
{
  "type": "Card",
  "children": [
    {"type": "Form", "direction": "col", "gap": 3,
     "onSubmitAction": {"type": "ticket.create", "payload": {"source": "chat"}},
     "children": [
       {"type": "Title", "value": "Report an Issue", "size": "sm"},
       {"type": "Label", "value": "Order Number", "fieldName": "order"},
       {"type": "Input", "name": "order", "required": true, "pattern": "C-[0-9]+", "placeholder": "C-42"},
       {"type": "Label", "value": "Category", "fieldName": "category"},
       {"type": "Select", "name": "category", "placeholder": "Select",
        "options": [{"label": "Damaged Package", "value": "damaged"},
                    {"label": "Delay", "value": "delay"},
                    {"label": "Other", "value": "other"}]},
       {"type": "Textarea", "name": "detail", "rows": 3, "placeholder": "Describe the issue"},
       {"type": "Button", "label": "Submit", "submit": true}
     ]}
  ]
}
"""

Bij verzending bevat action.payload source, order, category en detail. Een puntgescheiden naam, "client.name", produceert een geneste waarde: payload["client"]["name"]. Als een veldnaam botst met een sleutel die al in de payload aanwezig is, wordt de veldwaarde genegeerd en zendt ChatKit een foutgebeurtenis uit: kies unieke namen.

Formuliervalidatie gebeurt aan de browserzijde: required en pattern blokkeren verzending zolang een veld ongeldig is. Dit is gebruiksgemak, geen bescherming: valideer opnieuw op de server, bijvoorbeeld met een Pydantic-model.

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 de action-methode
if action.type == "ticket.create":
    try:
        report = Report.model_validate(action.payload or {})
    except ValidationError:
        yield self.message(thread, context, "The form is incomplete or invalid.")
        return
    ticket_number = await create_ticket(report, context.get("user_id"))
    yield self.message(thread, context, f"Ticket {ticket_number} created, we will get back to you.")

Voor rijkere validatie, met aangepaste foutberichten, adviseert de documentatie om buiten de widget te treden: een client-side actie opent een venster in uw applicatie, en het resultaat keert terug naar ChatKit via sendCustomAction. Merk ook op dat een Card gedeclareerd met "asForm": true zich gedraagt als een formulier: de velden worden gevalideerd en doorgegeven aan de confirm-actie.

Bevestigen voordat u handelt

De annuleringskaart aan het begin illustreert een regel die u moet generaliseren: een onomkeerbare of gevoelige actie vereist expliciete bevestiging. Een bestelling annuleren, een e-mail verzenden, terugbetalen, verwijderen: de agent stelt voor, de gebruiker valideert op een kaart die duidelijk aangeeft wat er zal gebeuren, en het is uw server, niet het model, die uitvoert na opnieuw verifiëren van rechten. De confirm- en cancel-knoppen van een Card zijn hiervoor gemaakt. Hun standaard laadstatus grijst de hele kaart uit tijdens de verwerking, wat dubbelklikken voorkomt.

Een actie in de browser verwerken

Sommige acties hebben niets op de server te doen: een pagina openen in uw applicatie, een link kopiëren, een modaal venster weergeven. Declareer deze met "handler": "client" in het sjabloon, bijvoorbeeld {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Ze komen dan binnen in de widgets.onAction-optie van de interface:

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');
          // De server op de hoogte stellen, die de widget kan bijwerken
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

  return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}

sendCustomAction stuurt een actie naar uw server alsof deze van een widget kwam. Het werkt ook buiten ChatKit: een knop op uw pagina kan chatkit.sendCustomAction({ type: 'cart.empty' }) aanroepen zodat de assistent reageert op wat er elders in de applicatie gebeurt.

Laadstatussen

loadingBehavior bepaalt wat de gebruiker ziet terwijl een actie wordt verwerkt:

WaardeEffect
auto (standaard)Past zich aan de component aan: alleen de knop voor een Button, niets voor een Select, de hele kaart voor de confirm van een Card
selfLaadstatus op de enkele component die de actie bevat
containerDe hele widget vervaagt en wordt inactief
noneGeen laadstatus

De documentatie raadt aan om auto te behouden, tenzij u een specifieke behoefte heeft. Standaard worden acties op een widget ook geblokkeerd terwijl een antwoord wordt gestreamd, om conflicten te voorkomen. Sinds SDK-versie 1.6.2 omzeilt een actie gedeclareerd met "streaming": false deze blokkering: deze wordt verwerkt door de sync_action-methode van de server, gereserveerd voor acties die alleen hun eigen widget bijwerken of buiten de thread handelen.

Belangrijkste punten

  • Een actie is een object {type, payload, handler, loadingBehavior} gekoppeld aan een widgetcomponent; het start verwerking zonder gebruikersbericht
  • Op de server ontvangt de action-methode van ChatKitServer deze en retourneert gebeurtenissen: bericht, bijgewerkte widget, of nieuw agent-antwoord via respond
  • De payload komt van de browser: verifieer rechten en gegevens opnieuw op de server (Pydantic), zelfs wanneer het formulier al required en pattern valideert
  • Een HiddenContextItem, handmatig toegevoegd aan de store, informeert het model over wat de gebruiker heeft gedaan
  • Gevoelige acties gaan via een bevestigingskaart; puur lokale acties worden in de browser verwerkt (handler: "client", widgets.onAction, sendCustomAction)