Akcie používateľa
Na tejto strane
Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia spracovávala kliknutia vo vlastných komponentoch React a vymýšľala „návrhové akcie“. V ChatKite je akcia objekt pripojený ku komponentu widgetu (tlačidlo, riadok zoznamu, formulár). Predvolene sa spracúva na vašom serveri v metóde
actiontriedyChatKitServer, alebo v prehliadači, ak to špecifikujete inak. Táto lekcia vychádza z príručky Actions in ChatKit a SDKopenai-chatkit1.6.5. Server, šablóny a formulár boli spustené lokálne; kód React bol overený kompiláciou. Zdroje: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Čo je to akcia?
Widget, ktorý iba zobrazuje obsah, je len pekná odpoveď. Akcie z neho robia užitočný nástroj: kliknutie na „Zrušiť objednávku“, výber riadku v zozname alebo odoslanie formulára spustí spracovanie bez toho, aby používateľ musel písať správu. ChatKit odošle akciu na váš server, ktorý môže konať vo vašich systémoch, aktualizovať widget, pridať odpoveď do vlákna alebo reštartovať agenta.
Akciu deklarujete v šablóne widgetu na komponente, ktorý ju akceptuje (onClickAction pre Button alebo ListViewItem, onChangeAction pre Select, onSubmitAction pre Form, confirm a cancel pre Card). Ide o malý JSON objekt:
| Pole | Úloha |
|---|---|
type | Názov akcie, ktorý váš kód testuje: "order.cancel" |
payload | Užitočné dáta: {"number": "C-42"} |
handler | "server" (predvolené) alebo "client" na spracovanie v prehliadači |
loadingBehavior | Stav načítania zobrazený počas spracovania (viď nižšie) |
Spracovanie akcie na serveri
Vezmime si kartu objednávky, ktorá ponúka zrušenie. Šablóna deklaruje akciu na tlačidlách potvrdenia a zrušenia komponentu 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 }}}}}
}
"""
Na strane servera pridajte do svojej triedy ChatKitServer metódu action. Prijíma vlákno, akciu, widget, ktorý ju vydal (sender), a váš kontext, a vracia udalosti ako 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(...) : ako v lekcii 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 prichádza z prehliadača: znovu overte oprávnenia
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)
# Stopa pre model, nikdy nezobrazovaná používateľovi
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.")
Z tohto kódu vyplývajú tri pravidlá:
- Payload je nedôveryhodný. Prichádza z prehliadača, kde ho ktokoľvek môže upraviť: príručka OpenAI vyžaduje zaobchádzať s ním ako s neoverenými dátami. Pred zrušením server skontroluje, či objednávka patrí autentifikovanému používateľovi.
user_idv kontexte je to, čo tam vloží váš autentifikovaný koncový bod (lekcia 21). - Model musí vedieť, čo sa stalo. Kliknutie nie je správa: bez stopy by agent v ďalšom kole ignoroval, že objednávka bola zrušená.
HiddenContextItempridá túto informáciu do vlákna bez toho, aby ju zobrazil. SDK automaticky zaznamenáva iba vysielané prvky a skrytý prvok sa nikdy nesmie vysielať: musíte ho sami pridať do úložiska (store). - Odpoveď je prúd udalostí. Tu jednoduchá správa; mohlo by ísť o aktualizovaný widget, vysielaný pomocou
stream_widgetako v predchádzajúcej lekcii.
Ak chcete, aby sa agent vyjadril k tomu, čo sa práve stalo, reštartujte ho po akcii: async for event in self.respond(thread, None, context): yield event. Vaša metóda respond znova prečíta vlákno, nájde skrytý prvok a zodpovedajúcim spôsobom odpovie.
Formuláre
Keď sú vstupné polia (Input, Textarea, Select, Checkbox, DatePicker…) umiestnené vo vnútri Form, ich hodnoty sa pridajú do payloadu akejkoľvek akcie vydanej z tohto formulára pod názvom každého poľa:
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}
]}
]
}
"""
Pri odoslaní action.payload obsahuje source, order, category a detail. Bodkovaný názov, napr. "client.name", vytvorí vnorenú hodnotu: payload["client"]["name"]. Ak sa názov poľa zhoduje s kľúčom, ktorý už v payloade existuje, hodnota poľa sa ignoruje a ChatKit vydá chybovú udalosť: vyberajte si jedinečné názvy.
Validácia formulára prebieha na strane prehliadača: required a pattern blokujú odoslanie, kým je pole neplatné. Ide o pohodlie používateľa, nie o ochranu: na serveri validáciu zopakujte, napríklad pomocou modelu 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)
# V metóde 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.")
Pre bohatšiu validáciu s vlastnými chybovými hláseniami dokumentácia odporúča presunúť sa mimo widget: akcia na strane klienta otvorí okno vo vašej aplikácii a výsledok sa vráti do ChatKitu cez sendCustomAction. Všimnite si tiež, že Card deklarovaný s "asForm": true sa správa ako formulár: jeho polia sa validujú a odovzdajú jeho akcii confirm.
Potvrdenie pred konaním
Karta zrušenia na začiatku ilustruje pravidlo, ktoré treba zovšeobecniť: nevratná alebo citlivá akcia vyžaduje explicitné potvrdenie. Zrušenie objednávky, odoslanie e-mailu, vrátenie peňazí, vymazanie: agent navrhne, používateľ potvrdí na karte, ktorá jasne uvádza, čo sa stane, a vykonanie po opätovnom overení oprávnení je na vašom serveri, nie na modeli. Na tento účel slúžia tlačidlá confirm a cancel komponentu Card. Ich predvolený stav načítania počas spracovania zašedí celú kartu, čo zabraňuje dvojitému kliknutiu.
Spracovanie akcie v prehliadači
Niektoré akcie nemajú na serveri čo robiť: otvorenie stránky vo vašej aplikácii, kopírovanie odkazu, zobrazenie modálneho okna. Deklarujte ich v šablóne s "handler": "client", napríklad {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Následne prídu do možnosti widgets.onAction rozhrania:
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');
// Upovedomiť server, ktorý môže aktualizovať widget
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction odošle akciu na váš server, akoby pochádzala z widgetu. Funguje to aj mimo ChatKit: tlačidlo na vašej stránke môže zavolať chatkit.sendCustomAction({ type: 'cart.empty' }), aby asistent reagoval na to, čo sa deje inde v aplikácii.
Stavy načítania
loadingBehavior riadi, čo používateľ vidí počas spracovania akcie:
| Hodnota | Efekt |
|---|---|
auto (predvolené) | Prispôsobí sa komponentu: samotné tlačidlo pre Button, nič pre Select, celá karta pre confirm komponentu Card |
self | Stav načítania na jedinom komponente, ktorý drží akciu |
container | Celý widget stmavne a stane sa neaktívnym |
none | Žiadny stav načítania |
Dokumentácia odporúča ponechať auto, pokiaľ nemáte špecifickú potrebu. Predvolene sú akcie na widgete tiež blokované, kým prebieha streamovanie odpovede, aby sa predišlo konfliktom. Od verzie SDK 1.6.2 akcia deklarovaná s "streaming": false obchádza toto blokovanie: spracováva ju metóda sync_action servera, vyhradená pre akcie, ktoré iba aktualizujú svoj vlastný widget alebo konajú mimo vlákna.
Kľúčové poznatky
- Akcia je objekt
{type, payload, handler, loadingBehavior}pripojený ku komponentu widgetu; spúšťa spracovanie bez používateľskej správy - Na serveri ju prijíma metóda
actiontriedyChatKitServera vracia udalosti: správu, aktualizovaný widget alebo novú odpoveď agenta cezrespond - Payload prichádza z prehliadača: na serveri znovu overte oprávnenia a dáta (Pydantic), aj keď formulár už validuje
requiredapattern HiddenContextItem, manuálne pridaný do úložiska, informuje model o tom, čo používateľ urobil- Citlivé akcie prechádzajú potvrdzovacou kartou; čisto lokálne akcie sa spracúvajú v prehliadači (
handler: "client",widgets.onAction,sendCustomAction)