Acties van gebruikers
Op deze pagina
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 vanChatKitServer, of in de browser als u anders specificeert. Deze les volgt de gids Actions in ChatKit en deopenai-chatkitSDK 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:
| Veld | Rol |
|---|---|
type | De actienaam die uw code test: "order.cancel" |
payload | Nuttige gegevens: {"number": "C-42"} |
handler | "server" (standaard) of "client" om deze in de browser te verwerken |
loadingBehavior | De 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_idin 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
HiddenContextItemvoegt 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_widgetzoals 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:
| Waarde | Effect |
|---|---|
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 |
self | Laadstatus op de enkele component die de actie bevat |
container | De hele widget vervaagt en wordt inactief |
none | Geen 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 vanChatKitServerdeze en retourneert gebeurtenissen: bericht, bijgewerkte widget, of nieuw agent-antwoord viarespond - De payload komt van de browser: verifieer rechten en gegevens opnieuw op de server (Pydantic), zelfs wanneer het formulier al
requiredenpatternvalideert - 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)