Uporabniška dejanja
Na tej strani
Lekcija ponovno napisana 3. novembra 2026. Prejšnja različica je obravnavala klike v komponentah React po meri in si izmislila „dejanja predlogov”. V ChatKitu je dejanje objekt, pripet komponenti gradnika (gumb, vrstica seznama, obrazec). Privzeto se obdela na vašem strežniku v metodi
actionrazredaChatKitServerali v brskalniku, če določite drugače. Ta lekcija sledi vodniku Actions in ChatKit in SDKopenai-chatkitrazličice 1.6.5. Strežnik, predloge in obrazec so bili zagnani lokalno; koda React je bila preverjena s kompilacijo. Viri: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Kaj je dejanje?
Gradnik, ki le prikazuje vsebino, je zgolj lep odgovor. Dejanja ga naredijo uporabnega: klik na „Prekliči naročilo”, izbor vrstice v seznamu ali oddaja obrazca sproži obdelavo brez potrebe, da bi uporabnik vtipkal sporočilo. ChatKit pošlje dejanje na vaš strežnik, ki lahko deluje na vaših sistemih, posodobi gradnik, doda odgovor v nit ali ponovno zažene agenta.
Dejanje deklarirate v predlogi gradnika na komponenti, ki ga sprejme (onClickAction za Button ali ListViewItem, onChangeAction za Select, onSubmitAction za Form, confirm in cancel za Card). Gre za majhen objekt JSON:
| Polje | Vloga |
|---|---|
type | Ime dejanja, ki ga vaša koda preverja: "order.cancel" |
payload | Uporabni podatki: {"number": "C-42"} |
handler | "server" (privzeto) ali "client" za obdelavo v brskalniku |
loadingBehavior | Stanje nalaganja, prikazano med obdelavo (glej spodaj) |
Obdelava dejanja na strežniku
Vzemimo kartico naročila, ki ponuja preklic. Predloga deklarira dejanje na gumbih za potrditev in preklic komponente 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 strani strežnika dodajte metodo action svojemu razredu ChatKitServer. Ta prejme nit, dejanje, gradnik, ki ga je sprožil (sender), in vaš kontekst ter vrne dogodke, kot je 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(...) : kot v lekciji 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 prihaja iz brskalnika: ponovno preverite dovoljenja
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)
# Sled za model, nikoli prikazano uporabniku
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.")
Iz te kode izhajajo tri pravila:
- Payload ni zaupanja vreden. Prispe iz brskalnika, kjer ga lahko kdorkoli spremeni: vodnik OpenAI zahteva obravnavo kot nepreverjenih podatkov. Pred preklicem strežnik preveri, ali naročilo pripada avtenticiranemu uporabniku.
user_idv kontekstu je tisti, ki ga tam postavi vaša avtenticirana končna točka (lekcija 21). - Model mora vedeti, kaj se je zgodilo. Klik ni sporočilo: brez sledi bi agent v naslednjem koraku ignoriral, da je naročilo preklicano.
HiddenContextItemdoda te informacije v nit, ne da bi jih prikazal. SDK samodejno beleži le elemente za oddajanje, skriti element pa se nikoli ne sme oddajati: dodati ga morate sami v shrambo (store). - Odgovor je tok dogodkov. Tukaj preprosto sporočilo; lahko bi bil posodobljen gradnik, oddan s
stream_widget, kot v prejšnji lekciji.
Če želite, da agent komentira pravkar dogodivščino, ga po dejanju ponovno zaženite: async for event in self.respond(thread, None, context): yield event. Vaša metoda respond ponovno prebere nit, najde skriti element in ustrezno odgovori.
Obrazci
Ko so vnosna polja (Input, Textarea, Select, Checkbox, DatePicker…) postavljena znotraj Form, se njihove vrednosti dodajo v payload kateregakoli dejanja, sproženega iz tega obrazca, pod imenom vsakega polja:
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}
]}
]
}
"""
Ob oddaji action.payload vsebuje source, order, category in detail. Ime s piko, "client.name", ustvari gnezdeno vrednost: payload["client"]["name"]. Če se ime polja ujema s ključem, ki je že prisoten v payloadu, se vrednost polja ignorira in ChatKit odda dogodek napake: izberite različna imena.
Veljavnost obrazca se preverja na strani brskalnika: required in pattern blokirata oddajo, dokler je polje neveljavno. To je udobje za uporabnika, ne zaščita: ponovno preverite na strežniku, na primer z modelom 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 metodi 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.")
Za bogatejše preverjanje veljavnosti z prilagojenimi sporočili o napakah dokumentacija svetuje premik zunaj gradnika: dejanje na strani odpre okno v vaši aplikaciji, rezultat pa se vrne v ChatKit prek sendCustomAction. Upoštevajte tudi, da se Card, deklariran z "asForm": true, obnaša kot obrazec: njegova polja so validirana in posredovana njegovemu dejanju confirm.
Potrditev pred dejanjem
Kartica za preklic na začetku ponazarja pravilo, ki ga je treba posplošiti: nepovratno ali občutljivo dejanje zahteva izrecno potrditev. Preklic naročila, pošiljanje e-pošte, povračilo, brisanje: agent predlaga, uporabnik potrdi na kartici, ki jasno navaja, kaj se bo zgodilo, izvršitev pa opravi vaš strežnik, ne model, in sicer po ponovnem preverjanju dovoljenj. Gumba confirm in cancel komponente Card sta namenjena prav temu. Njuno privzeto stanje nalaganja osivi celotno kartico med obdelavo, kar preprečuje dvojne klike.
Obdelava dejanja v brskalniku
Nekatera dejanja na strežniku nimajo kaj opraviti: odpiranje strani v vaši aplikaciji, kopiranje povezave, prikaz modalnega okna. Deklarirajte jih z "handler": "client" v predlogi, na primer {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Nato prispejo v možnost widgets.onAction vmesnika:
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');
// Obvesti strežnik, ki lahko posodobi gradnik
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction pošlje dejanje na vaš strežnik, kot da bi prišlo iz gradnika. Deluje tudi zunaj ChatKita: gumb na vaši strani lahko pokliče chatkit.sendCustomAction({ type: 'cart.empty' }), tako da asistent reagira na dogodke drugje v aplikaciji.
Stanja nalaganja
loadingBehavior nadzira, kaj uporabnik vidi med obdelavo dejanja:
| Vrednost | Učinek |
|---|---|
auto (privzeto) | Prilagodi se komponenti: samo gumb za Button, nič za Select, celotna kartica za confirm komponente Card |
self | Stanje nalaganja na posamezni komponenti, ki ima dejanje |
container | Celoten gradnik zbledi in postane neaktiven |
none | Brez stanja nalaganja |
Dokumentacija priporoča ohranjanje vrednosti auto, razen če imate specifično potrebo. Privzeto so dejanja na gradniku blokirana tudi med pretakanjem odgovora, da se preprečijo konflikti. Od različice SDK 1.6.2 dalje dejanje, deklarirano z "streaming": false, obide to blokado: obdela ga metoda sync_action strežnika, rezervirana za dejanja, ki le posodabljajo svoj lasten gradnik ali delujejo zunaj niti.
Ključne ugotovitve
- Dejanje je objekt
{type, payload, handler, loadingBehavior}, pripet komponenti gradnika; sproži obdelavo brez uporabniškega sporočila - Na strežniku metoda
actionrazredaChatKitServerprejme dejanje in vrne dogodke: sporočilo, posodobljen gradnik ali nov odgovor agenta prekrespond - Payload prihaja iz brskalnika: ponovno preverite dovoljenja in podatke na strežniku (Pydantic), tudi če obrazec že validira
requiredinpattern HiddenContextItem, ročno dodan v shrambo, obvesti model o uporabnikovem dejanju- Občutljiva dejanja gredo skozi potrditveno kartico; čisto lokalna dejanja se obdelajo v brskalniku (
handler: "client",widgets.onAction,sendCustomAction)