Radnje korisnika
Na ovoj stranici
Lekcija je ponovno napisana 3. studenog 2026. Prethodna verzija obrađivala je klikove u prilagođenim React komponentama i izmislila „prijedložene radnje“. U ChatKitu je radnja objekt povezan s komponentom widgeta (gumb, redak popisa, obrazac). Zadano se obrađuje na tvojem poslužitelju u metodi
actionklaseChatKitServer, ili u pregledniku ako to drugačije odrediš. Ova lekcija prati vodič Radnje u ChatKitu i SDKopenai-chatkitverzije 1.6.5. Poslužitelj, predlošci i obrazac pokrenuti su lokalno; React kod verificiran je kompilacijom. Izvori: Radnje u ChatKitu · Izgradnja interaktivnih odgovora s widgetima · Bilješke o izdanju Python SDK-a 1.6.2.
Što je radnja?
Widget koji samo prikazuje sadržaj samo je lijep odgovor. Radnje ga čine korisnim: klik na „Otkaži narudžbu“, odabir retka u popisu ili slanje obrasca pokreće obradu bez da korisnik mora upisati poruku. ChatKit šalje radnju na tvoj poslužitelj, koji može djelovati na tvojim sustavima, ažurirati widget, dodati odgovor u nit ili ponovno pokrenuti agenta.
Radnju deklariraš u predlošku widgeta na komponenti koja je prihvaća (onClickAction za Button ili ListViewItem, onChangeAction za Select, onSubmitAction za Form, confirm i cancel za Card). To je mali JSON objekt:
| Polje | Uloga |
|---|---|
type | Naziv radnje koji tvoj kod testira: "order.cancel" |
payload | Korisni podaci: {"number": "C-42"} |
handler | "server" (zadano) ili "client" za obradu u pregledniku |
loadingBehavior | Stanje učitavanja prikazano tijekom obrade (vidi dolje) |
Obrada radnje na poslužitelju
Uzmimo karticu narudžbe koja nudi otkazivanje. Predložak deklarira radnju na gumbima za potvrdu i odustajanje 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 poslužitelja dodaj metodu action svojoj klasi ChatKitServer. Ona prima nit, radnju, widget koji ju je emitirao (sender) i tvoj kontekst, te vraća događaje poput 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(...) : kao u 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 dolazi iz preglednika: ponovno provjeri dopuštenja
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)
# Trag za model, nikada nije prikazan korisniku
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 ovog koda proizlaze tri pravila:
- Payload nije od povjerenja. Dolazi iz preglednika gdje ga bilo tko može modificirati: vodič OpenAI-ja zahtijeva tretiranje kao neprovjerenih podataka. Prije otkazivanja, poslužitelj provjerava pripada li narudžba autentificiranom korisniku.
user_idu kontekstu je onaj koji tvoja autentificirana krajnja točka tamo postavlja (lekcija 21). - Model mora znati što se dogodilo. Klik nije poruka: bez traga, agent bi u sljedećem koraku ignorirao da je narudžba otkazana.
HiddenContextItemdodaje tu informaciju u nit bez da je prikazuje. SDK automatski bilježi samo emitirane elemente, a skriveni element se nikada ne smije emitirati: moraš ga sam dodati u store. - Odgovor je tok događaja. Ovdje jednostavna poruka; mogao bi biti ažurirani widget, emitiran s
stream_widgetkao u prethodnoj lekciji.
Da bi agent komentirao ono što se upravo dogodilo, ponovno ga pokreni nakon radnje: async for event in self.respond(thread, None, context): yield event. Tvoja metoda respond ponovno čita nit, pronalazi skriveni element i odgovara sukladno tome.
Obrasci
Kada se polja za unos (Input, Textarea, Select, Checkbox, DatePicker…) nalaze unutar Form, njihove vrijednosti se dodaju u payload bilo koje radnje emitirane iz tog obrasca, pod imenom svakog 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}
]}
]
}
"""
Prilikom slanja, action.payload sadrži source, order, category i detail. Točkasti naziv, "client.name", stvara ugniježđenu vrijednost: payload["client"]["name"]. Ako se naziv polja sukobi s ključem koji već postoji u payloadu, vrijednost polja se ignorira i ChatKit emitira događaj pogreške: odaberi jedinstvene nazive.
Validacija obrasca je na strani preglednika: required i pattern blokiraju slanje dok je polje neispravno. To je pogodnost za korisnika, a ne zaštita: ponovno validiraj na poslužitelju, na primjer s Pydantic modelom.
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)
# U 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 bogatiju validaciju s prilagođenim porukama o pogreškama, dokumentacija savjetuje izlazak izvan widgeta: radnja na strani klijenta otvara prozor u tvojoj aplikaciji, a rezultat se vraća u ChatKit putem sendCustomAction. Također imaj na umu da se Card deklariran s "asForm": true ponaša kao obrazac: njegova polja se validiraju i prosljeđuju njegovoj radnji confirm.
Potvrda prije djelovanja
Kartica za otkazivanje s početka ilustrira pravilo koje trebaš generalizirati: nepovratna ili osjetljiva radnja zahtijeva eksplicitnu potvrdu. Otkazivanje narudžbe, slanje e-pošte, povrat novca, brisanje: agent predlaže, korisnik potvrđuje na kartici koja jasno navodi što će se dogoditi, a tvoj poslužitelj, a ne model, izvršava radnju nakon ponovne provjere dopuštenja. Gumbi confirm i cancel komponente Card napravljeni su upravo za to. Njihovo zadano stanje učitavanja posivi cijelu karticu tijekom obrade, što sprječava dvostruke klikove.
Obrada radnje u pregledniku
Neke radnje nemaju što raditi na poslužitelju: otvaranje stranice u tvojoj aplikaciji, kopiranje poveznice, prikaz modalnog prozora. Deklariraj ih s "handler": "client" u predlošku, na primjer {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. One tada stižu u opciju widgets.onAction sučelja:
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');
// Obavijesti poslužitelj, koji može ažurirati widget
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction šalje radnju na tvoj poslužitelj kao da dolazi od widgeta. Također radi i izvan ChatKita: gumb na tvojoj stranici može pozvati chatkit.sendCustomAction({ type: 'cart.empty' }) kako bi asistent reagirao na ono što se događa drugdje u aplikaciji.
Stanja učitavanja
loadingBehavior kontrolira što korisnik vidi dok se radnja obrađuje:
| Vrijednost | Učinak |
|---|---|
auto (zadano) | Prilagođava se komponenti: samo gumb za Button, ništa za Select, cijela kartica za confirm od Card |
self | Stanje učitavanja na pojedinačnoj komponenti koja drži radnju |
container | Cijeli widget blijedi i postaje neaktivan |
none | Nema stanja učitavanja |
Dokumentacija preporučuje zadržavanje auto, osim ako nemaš specifičnu potrebu. Zadano su radnje na widgetu također blokirane dok odgovor struji, kako bi se izbjegli sukobi. Od verzije SDK-a 1.6.2, radnja deklarirana s "streaming": false zaobilazi ovo blokiranje: obrađuje je metoda sync_action poslužitelja, rezervirana za radnje koje samo ažuriraju vlastiti widget ili djeluju izvan niti.
Ključne točke
- Radnja je objekt
{type, payload, handler, loadingBehavior}povezan s komponentom widgeta; pokreće obradu bez korisničke poruke - Na poslužitelju, metoda
actionklaseChatKitServerprima ju i vraća događaje: poruku, ažurirani widget ili novi odgovor agenta putemrespond - Payload dolazi iz preglednika: ponovno provjeri dopuštenja i podatke na poslužitelju (Pydantic), čak i kada obrazac već validira
requiredipattern HiddenContextItem, ručno dodan u store, informira model o tome što je korisnik učinio- Osjetljive radnje prolaze kroz karticu za potvrdu; čisto lokalne radnje obrađuju se u pregledniku (
handler: "client",widgets.onAction,sendCustomAction)