Akce uživatele
Na této stránce
Lekce přepsána 3. listopadu 2026. Předchozí verze zpracovávala kliknutí ve vlastních komponentách React a vymýšlela „návrhové akce“. V ChatKitu je akce objekt připojený ke komponentě widgetu (tlačítko, řádek seznamu, formulář). Ve výchozím nastavení se zpracovává na vašem serveru v metodě
actiontřídyChatKitServer, nebo v prohlížeči, pokud určíte jinak. Tato lekce vychází z průvodce Akce v ChatKitu a SDKopenai-chatkitverze 1.6.5. Server, šablony a formulář byly spuštěny lokálně; kód React byl ověřen kompilací. Zdroje: Akce v ChatKitu · Vytváření interaktivních odpovědí s widgety · Poznámky k vydání Python SDK 1.6.2.
Co je to akce?
Widget, který pouze zobrazuje obsah, je jen hezká odpověď. Akce z něj dělají užitečný nástroj: kliknutí na „Zrušit objednávku“, výběr řádku v seznamu nebo odeslání formuláře spustí zpracování bez toho, aby uživatel musel psát zprávu. ChatKit odešle akci na váš server, který může zasáhnout do vašich systémů, aktualizovat widget, přidat do vlákna odpověď nebo restartovat agenta.
Akci deklarujete v šabloně widgetu na komponentě, která ji přijímá (onClickAction pro Button nebo ListViewItem, onChangeAction pro Select, onSubmitAction pro Form, confirm a cancel pro Card). Jedná se o malý JSON objekt:
| Pole | Role |
|---|---|
type | Název akce, který váš kód testuje: "order.cancel" |
payload | Užitečná data: {"number": "C-42"} |
handler | "server" (výchozí) nebo "client" pro zpracování v prohlížeči |
loadingBehavior | Stav načítání zobrazený během zpracování (viz níže) |
Zpracování akce na serveru
Vezměme si kartu objednávky, která nabízí zrušení. Šablona deklaruje akci na tlačítkách potvrzení a zrušení komponenty 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 straně serveru přidejte do své třídy ChatKitServer metodu action. Přijímá vlákno, akci, widget, který ji vydal (sender), a váš kontext, a vrací události jako 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(...) : jako v lekci 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 přichází z prohlížeče: znovu ověřte oprávnění
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 pro model, nikdy nezobrazená uživateli
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 tohoto kódu vyplývají tři pravidla:
- Payload není důvěryhodný. Přichází z prohlížeče, kde jej kdokoli může upravit: průvodce OpenAI vyžaduje zacházet s ním jako s neověřenými daty. Před zrušením server zkontroluje, zda objednávka patří přihlášenému uživateli.
user_idv kontextu je to, které tam umístí váš autentizovaný koncový bod (lekce 21). - Model se musí dozvědět, co se stalo. Kliknutí není zpráva: bez stopy by agent v dalším kole ignoroval, že objednávka byla zrušena.
HiddenContextItempřidá tuto informaci do vlákna, aniž by ji zobrazil. SDK automaticky zaznamenává pouze prvky určené k vysílání a skrytý prvek nesmí být nikdy vysílán: musíte jej sami přidat do úložiště (store). - Odpověď je proud událostí. Zde jednoduchá zpráva; mohlo by jít o aktualizovaný widget, vysílaný pomocí
stream_widgetjako v předchozí lekci.
Aby se agent vyjádřil k tomu, co se právě stalo, restartujte jej po akci: async for event in self.respond(thread, None, context): yield event. Vaše metoda respond znovu přečte vlákno, najde skrytý prvek a odpoví odpovídajícím způsobem.
Formuláře
Když jsou vstupní pole (Input, Textarea, Select, Checkbox, DatePicker…) umístěna uvnitř Form, jejich hodnoty se přidají do payloadu jakékoli akce vyslané z tohoto formuláře pod názvem každého pole:
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}
]}
]
}
"""
Při odeslání obsahuje action.payload položky source, order, category a detail. Tečkovaný název, "client.name", vytvoří vnořenou hodnotu: payload["client"]["name"]. Pokud název pole koliduje s klíčem, který již v payloadu existuje, hodnota pole se ignoruje a ChatKit vydá chybovou událost: vybírejte jedinečné názvy.
Validace formuláře probíhá na straně prohlížeče: required a pattern blokují odeslání, dokud je pole neplatné. Je to uživatelské pohodlí, nikoli ochrana: znovu validujte na serveru, například pomocí 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 metodě 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.")
Pro sofistikovanější validaci s vlastními chybovými zprávami dokumentace doporučuje přesunout se mimo widget: akce na straně klienta otevře okno ve vaší aplikaci a výsledek se vrátí do ChatKitu prostřednictvím sendCustomAction. Všimněte si také, že Card deklarovaná s "asForm": true se chová jako formulář: její pole jsou validována a předána její akci confirm.
Potvrzení před provedením
Karta pro zrušení na začátku ilustruje pravidlo, které byste měli zobecnit: nevratná nebo citlivá akce vyžaduje explicitní potvrzení. Zrušení objednávky, odeslání e-mailu, vrácení peněz, smazání: agent navrhne, uživatel potvrdí na kartě, která jasně uvádí, co se stane, a až váš server (nikoli model) provede akci po opětovném ověření oprávnění. Tlačítka confirm a cancel komponenty Card jsou určena právě pro toto. Jejich výchozí stav načítání zešedí celou kartu během zpracování, což zabraňuje dvojímu kliknutí.
Zpracování akce v prohlížeči
Některé akce nemají na serveru co dělat: otevření stránky ve vaší aplikaci, zkopírování odkazu, zobrazení modálního okna. Deklarujte je v šabloně s "handler": "client", například {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Poté dorazí do volby widgets.onAction rozhraní:
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');
// Upozornit server, který může aktualizovat widget
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction odešle akci na váš server, jako by přišla z widgetu. Funguje také mimo ChatKit: tlačítko na vaší stránce může zavolat chatkit.sendCustomAction({ type: 'cart.empty' }), aby asistent reagoval na to, co se děje jinde v aplikaci.
Stavy načítání
loadingBehavior řídí, co uživatel vidí, zatímco se akce zpracovává:
| Hodnota | Efekt |
|---|---|
auto (výchozí) | Přizpůsobí se komponentě: pouze tlačítko pro Button, nic pro Select, celá karta pro confirm u Card |
self | Stav načítání na jediné komponentě, která akci obsahuje |
container | Celý widget zbledne a stane se neaktivním |
none | Žádný stav načítání |
Dokumentace doporučuje ponechat auto, pokud nemáte specifickou potřebu. Ve výchozím nastavení jsou akce na widgetu také blokovány, zatímco probíhá streamování odpovědi, aby se předešlo konfliktům. Od verze SDK 1.6.2 akce deklarovaná s "streaming": false toto blokování obchází: zpracovává ji metoda sync_action serveru, vyhrazená pro akce, které pouze aktualizují svůj vlastní widget nebo působí mimo vlákno.
Klíčové poznatky
- Akce je objekt
{type, payload, handler, loadingBehavior}připojený ke komponentě widgetu; spouští zpracování bez uživatelské zprávy - Na serveru ji přijímá metoda
actiontřídyChatKitServera vrací události: zprávu, aktualizovaný widget nebo novou odpověď agenta přesrespond - Payload přichází z prohlížeče: znovu ověřte oprávnění a data na serveru (Pydantic), i když formulář již validuje
requiredapattern HiddenContextItem, ručně přidaný do úložiště, informuje model o tom, co uživatel provedl- Citlivé akce procházejí potvrzovací kartou; čistě lokální akce se zpracovávají v prohlížeči (
handler: "client",widgets.onAction,sendCustomAction)