Acțiuni ale utilizatorului
Pe această pagină
Lecție rescrisă la 3 noiembrie 2026. Versiunea anterioară gestiona clicurile în componente React personalizate și inventa „acțiuni de sugestie“. În ChatKit, o acțiune este un obiect atașat unei componente widget (buton, rând de listă, formular). Implicit, aceasta este procesată pe serverul dumneavoastră în metoda
actiona claseiChatKitServer, sau în browser dacă specificați altfel. Această lecție urmează ghidul Actions in ChatKit și SDK-ulopenai-chatkitversiunea 1.6.5. Serverul, șabloanele și formularul au fost rulate local; codul React a fost verificat prin compilare. Surse: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Ce este o acțiune?
Un widget care afișează doar conținut este doar un răspuns estetic. Acțiunile îl fac util: făcând clic pe „Anulează comanda“, selectând un rând într-o listă sau trimițând un formular, declanșați o procesare fără ca utilizatorul să fie nevoit să tasteze un mesaj. ChatKit trimite acțiunea către serverul dumneavoastră, care poate acționa asupra sistemelor dumneavoastră, poate actualiza widget-ul, poate adăuga un răspuns în firul de conversație sau poate reporni agentul.
Declarați o acțiune în șablonul widget-ului pe o componentă care acceptă una (onClickAction pentru un Button sau ListViewItem, onChangeAction pentru un Select, onSubmitAction pentru un Form, confirm și cancel pentru un Card). Este un mic obiect JSON:
| Câmp | Rol |
|---|---|
type | Numele acțiunii pe care codul dumneavoastră o testează: "order.cancel" |
payload | Date utile: {"number": "C-42"} |
handler | "server" (implicit) sau "client" pentru a o procesa în browser |
loadingBehavior | Starea de încărcare afișată în timpul procesării (vezi mai jos) |
Procesarea unei acțiuni pe server
Să luăm un card de comandă care oferă opțiunea de anulare. Șablonul declară acțiunea pe butoanele de confirmare și anulare ale 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 }}}}}
}
"""
Pe partea de server, adăugați o metodă action în ChatKitServer. Aceasta primește firul de conversație (thread), acțiunea, widget-ul care a emis-o (sender) și contextul dumneavoastră, și returnează evenimente precum 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(...) : ca în lecția 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", ""))
# Payload-ul vine din browser: reverificați permisiunile
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)
# O urmă pentru model, niciodată afișată utilizatorului
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.")
Din acest cod reies trei reguli:
- Payload-ul nu este de încredere. Acesta provine din browser, unde oricine îl poate modifica: ghidul OpenAI cere tratarea sa ca date neverificate. Înainte de anulare, serverul verifică dacă comanda aparține utilizatorului autentificat.
user_iddin context este cel pe care endpoint-ul dumneavoastră autentificat îl plasează acolo (lecția 21). - Modelul trebuie să știe ce s-a întâmplat. Un clic nu este un mesaj: fără o urmă, agentul ar ignora la următorul tur faptul că comanda a fost anulată. Un
HiddenContextItemadaugă această informație în firul de conversație fără a-l afișa. SDK înregistrează automat doar elementele difuzate, iar un element ascuns nu trebuie niciodată difuzat: trebuie să îl adăugați dumneavoastră în store. - Răspunsul este un flux de evenimente. Aici un mesaj simplu; ar putea fi un widget actualizat, difuzat cu
stream_widgetca în lecția anterioară.
Pentru ca agentul să comenteze ceea ce tocmai s-a întâmplat, reporniți-l după acțiune: async for event in self.respond(thread, None, context): yield event. Metoda dumneavoastră respond recitește firul de conversație, găsește elementul ascuns și răspunde în consecință.
Formulare
Când câmpurile de intrare (Input, Textarea, Select, Checkbox, DatePicker…) sunt plasate în interiorul unui Form, valorile lor sunt adăugate la payload-ul oricărei acțiuni emise din acel formular, sub numele fiecărui câmp:
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}
]}
]
}
"""
La submit, action.payload conține source, order, category și detail. Un nume punctat, "client.name", produce o valoare imbricată: payload["client"]["name"]. Dacă un nume de câmp intră în conflict cu o cheie deja prezentă în payload, valoarea câmpului este ignorată și ChatKit emite un eveniment de eroare: alegeți nume distincte.
Validarea formularului se face în browser: required și pattern blochează trimiterea cât timp un câmp este invalid. Aceasta este o comoditate pentru utilizator, nu o protecție: revalidați pe server, de exemplu cu un model Pydantic.
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)
# În metoda action
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.")
Pentru o validare mai bogată, cu mesaje de eroare personalizate, documentația sfătuiește să ieșiți din widget: o acțiune lato-client deschide o fereastră în aplicația dumneavoastră, iar rezultatul se întoarce la ChatKit prin sendCustomAction. Rețineți, de asemenea, că un Card declarat cu "asForm": true se comportă ca un formular: câmpurile sale sunt validate și transmise acțiunii sale confirm.
Confirmare înainte de acțiune
Cardul de anulare de la început ilustrează o regulă de generalizat: o acțiune ireversibilă sau sensibilă necesită o confirmare explicită. Anularea unei comenzi, trimiterea unui e-mail, rambursarea, ștergerea: agentul propune, utilizatorul validează pe un card care indică clar ce se va întâmpla, iar serverul dumneavoastră, nu modelul, execută după reverificarea permisiunilor. Butoanele confirm și cancel ale unui Card sunt făcute pentru acest scop. Starea lor implicită de încărcare grișează întregul card în timpul procesării, ceea ce previne dublele clicuri.
Procesarea unei acțiuni în browser
Unele acțiuni nu au nimic de făcut pe server: deschiderea unei pagini în aplicația dumneavoastră, copierea unui link, afișarea unui modal. Declarați-le cu "handler": "client" în șablon, de exemplu {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Acestea ajung apoi în opțiunea widgets.onAction a interfeței:
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');
// Notifică serverul, care poate actualiza widget-ul
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction trimite o acțiune către serverul dumneavoastră ca și cum ar veni de la un widget. Funcționează și în afara ChatKit: un buton de pe pagina dumneavoastră poate apela chatkit.sendCustomAction({ type: 'cart.empty' }) astfel încât asistentul să reacționeze la ceea ce se întâmplă în altă parte în aplicație.
Stări de încărcare
loadingBehavior controlează ceea ce vede utilizatorul în timp ce o acțiune este procesată:
| Valoare | Efect |
|---|---|
auto (implicit) | Se adaptează la componentă: doar butonul pentru un Button, nimic pentru un Select, întregul card pentru confirm al unui Card |
self | Stare de încărcare pe singura componentă care deține acțiunea |
container | Întregul widget devine estompat și inactiv |
none | Nicio stare de încărcare |
Documentația recomandă păstrarea lui auto,除非 aveți o nevoie specifică. Implicit, acțiunile asupra unui widget sunt, de asemenea, blocate în timp ce un răspuns este transmis în flux, pentru a evita conflictele. Începând cu versiunea SDK 1.6.2, o acțiune declarată cu "streaming": false ocolește acest blocaj: aceasta este procesată de metoda sync_action a serverului, rezervată acțiunilor care își actualizează doar propriul widget sau acționează în afara firului de conversație.
Puncte cheie
- O acțiune este un obiect
{type, payload, handler, loadingBehavior}atașat unei componente widget; declanșează o procesare fără un mesaj al utilizatorului - Pe server, metoda
actionaChatKitServero primește și returnează evenimente: mesaj, widget actualizat sau nou răspuns al agentului prinrespond - Payload-ul vine din browser: reverificați permisiunile și datele pe server (Pydantic), chiar și atunci când formularul validează deja
requiredșipattern - Un
HiddenContextItem, adăugat manual în store, informează modelul despre ceea ce a făcut utilizatorul - Acțiunile sensibile trec printr-un card de confirmare; acțiunile pur locale sunt procesate în browser (
handler: "client",widgets.onAction,sendCustomAction)