Veiksmai, kuriuos atlieka naudotojas
Šiame puslapyje
Pamoka perrašyta 2026 m. lapkričio 3 d. Ankstesnė versija apdorojo paspaudimus individualiuose „React“ komponentuose ir sugalvojo „pasiūlymų veiksmus“. „ChatKit“ sistemoje veiksmas yra objektas, prijungtas prie valdiklio komponento (mygtuko, sąrašo eilutės, formos). Pagal nutylėjimą jis apdorojamas jūsų serveryje, naudojant
actionmetodą klasėjeChatKitServer, arba naršyklėje, jei nurodote kitaip. Ši pamoka remiasi Actions in ChatKit vadovu iropenai-chatkitSDK 1.6.5 versija. Serveris, šablonai ir forma buvo paleisti lokaliai; „React“ kodas patikrintas kompiliuojant. Šaltiniai: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Kas yra veiksmas?
Valdiklis, kuris tik rodo turinį, yra tiesiog gražus atsakymas. Veiksmai suteikia jam naudingojo krūvio: paspaudus „Atšaukti užsakymą“, pasirinkus eilutę sąraše arba pateikus formą, inicijuojamas apdorojimas nespausdinant naudotojui jokio pranešimo. „ChatKit“ išsiunčia veiksmą į jūsų serverį, kuris gali atlikti operacijas jūsų sistemose, atnaujinti valdiklį, pridėti atsakymą į giją arba paleisti agentą iš naujo.
Veiksmą deklaruojate valdiklio šablone komponentui, kuris jį priima (onClickAction komponentams Button arba ListViewItem, onChangeAction – Select, onSubmitAction – Form, confirm ir cancel – Card). Tai mažas JSON objektas:
| Laukas | Vaidmuo |
|---|---|
type | Veiksmo pavadinimas, kurį tikrina jūsų kodas: "order.cancel" |
payload | Naudingi duomenys: {"number": "C-42"} |
handler | "server" (pagal nutylėjimą) arba "client" apdorojimui naršyklėje |
loadingBehavior | Krovinio būsena, rodoma apdorojimo metu (žr. toliau) |
Veiksmo apdorojimas serveryje
Paimkime užsakymo kortelę, siūlančią atšaukimą. Šablone veiksmas deklaruojamas ant Card komponento patvirtinimo ir atšaukimo mygtukų:
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 }}}}}
}
"""
Serverio pusėje pridėkite metodą action savo ChatKitServer klasei. Jis gauna giją, veiksmą, valdiklį, kuris jį išsiuntė (sender), ir jūsų kontekstą, o grąžina įvykius, pavyzdžiui, 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(...) : kaip 17 pamokoje
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 ateina iš naršyklės: iš naujo patikrinkite leidimus
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)
# Pėdsakas modeliui, niekada nerodomas naudotojui
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.")
Iš šio kodo išplaukia trys taisyklės:
- Payload yra nepatikimas. Jis ateina iš naršyklės, kur bet kas gali jį pakeisti: „OpenAI“ gidas reikalauja laikyti jį nepatvirtintais duomenimis. Prieš atšaukdami serveris patikrina, ar užsakymas priklauso autentifikaciją atlikusiam naudotojui. Kontekste esantis
user_idyra tas, kurį jūsų autentifikacijos galinis taškas ten įdeda (21 pamoka). - Modelis turi žinoti, kas įvyko. Paspaudimas nėra žinutė: be pėdsako agentas kitame etape ignoruotų tai, kad užsakymas atšauktas.
HiddenContextItemprideda šią informaciją į giją jos nerodydamas. SDK automatiškai įrašo tik transliuojamus elementus, o paslėptas elementas niekada neturi būti transliuojamas: turite jį patys pridėti į saugyklą (store). - Atsakymas yra įvykių srautas. Čia tai paprasta žinutė; tai galėtų būti atnaujintas valdiklis, transliuojamas naudojant
stream_widget, kaip ir ankstesnėje pamokoje.
Jei norite, kad agentas pakomentuotų ką tik įvykusį veiksmą, paleiskite jį iš naujo po veiksmo: async for event in self.respond(thread, None, context): yield event. Jūsų metodas respond iš naujo nuskaitys giją, ras paslėptą elementą ir atsakys atitinkamai.
Formos
Kai įvesties laukai (Input, Textarea, Select, Checkbox, DatePicker…) patalpinami į Form, jų reikšmės pridedamos prie bet kokio veiksmo, išsiųsto iš tos formos, payload, pagal kiekvieno lauko pavadinimą:
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}
]}
]
}
"""
Pateikus formą, action.payload contient source, order, category ir detail. Taškinis pavadinimas, pavyzdžiui, "client.name", sukuria įdėtą reikšmę: payload["client"]["name"]. Jei lauko pavadinimas sutampa su jau esamu raktu payload’e, lauko reikšmė ignoruojama ir „ChatKit“ išmeta klaidos įvykį: rinkitės unikalius pavadinimus.
Formos validavimas vyksta naršyklės pusėje: required ir pattern blokuoja pateikimą, kol laukas yra neteisingas. Tai naudotojo patogumas, o ne apsauga: iš naujo patikrinkite serveryje, pavyzdžiui, naudodami „Pydantic“ modelį.
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)
# Veiksmo metode
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.")
Sudėtingesniam validavimui su individualiomis klaidų žinutėmis dokumentacija rekomenduoja išeiti už valdiklio ribų: kliento pusės veiksmas atidaro langą jūsų programoje, o rezultatas grąžinamas į „ChatKit“ per sendCustomAction. Taip pat noteikite, kad Card, deklaruotas su "asForm": true, elgiasi kaip forma: jo laukai validuojami ir perduodami jo confirm veiksmui.
Patvirtinimas prieš veiksmą
Atšaukimo kortelė pamokos pradžioje iliustruoja taisyklę, kurią verta taikyti plačiau: negrįžtamas arba jautrus veiksmas reikalauja aiškaus patvirtinimo. Užsakymo atšaukimas, el. laiško siuntimas, pinigų grąžinimas, trynimas: agentas siūlo, naudotojas patvirtina kortelėje, kurioje aiškiai nurodyta, kas nutiks, o vykdo tai jūsų serveris, o ne modelis, dar kartą patikrinęs leidimus. Tam skirti Card mygtukai confirm ir cancel. Jų numatytoji krovinio būsena pilkai nuspalvina visą kortelę apdorojimo metu, taip užkertant kelią dvigubiems paspaudimams.
Veiksmo apdorojimas naršyklėje
Kai kuriems veiksmams serveris nereikalingas: puslapio atidarymas jūsų programoje, nuorodos nukopijavimas, modalinio lango rodymas. Deklaruokite juos šablone su "handler": "client", pavyzdžiui, {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Tuomet jie patenka į sąsajos parinktį widgets.onAction:
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');
// Informuokite serverį, kuris gali atnaujinti valdiklį
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction išsiunčia veiksmą į jūsų serverį taip, lyg jis būtų atėjęs iš valdiklio. Tai veikia ir už „ChatKit“ ribų: jūsų puslapio mygtukas gali iškviesti chatkit.sendCustomAction({ type: 'cart.empty' }), kad asistentas sureaguotų į tai, kas vyksta kitur programoje.
Krovinio būsenos
loadingBehavior valdo, ką naudotojas mato veiksmo apdorojimo metu:
| Reikšmė | Poveikis |
|---|---|
auto (pagal nutylėjimą) | Prisitaiko prie komponento: tik mygtukas Button atveju, nieko Select atveju, visa kortelė Card confirm atveju |
self | Krovinio būsena tik tame komponente, kuris turi veiksmą |
container | Visas valdiklis išblunka ir tampa neaktyvus |
none | Jokia krovinio būsena nerodoma |
Dokumentacija rekomenduoja palikti auto, nebent turite specifinį poreikį. Pagal nutylėjimą veiksmai valdiklyje taip pat blokuojami, kol transliuojamas atsakymas, siekiant išvengti konfliktų. Nuo SDK 1.6.2 versijos veiksmas, deklaruotas su "streaming": false, apeina šį blokavimą: jį apdoroja serverio metodas sync_action, skirtas veiksmams, kurie tik atnaujina savo valdiklį arba veikia už gijos ribų.
Svarbiausi punktai
- Veiksmas yra objektas
{type, payload, handler, loadingBehavior}, prijungtas prie valdiklio komponento; jis inicijuoja apdorojimą be naudotojo žinutės - Serveryje
ChatKitServermetodasactionjį gauna ir grąžina įvykius: žinutę, atnaujintą valdiklį arba naują agento atsakymą perrespond - Payload ateina iš naršyklės: iš naujo patikrinkite leidimus ir duomenis serveryje („Pydantic“), net jei forma jau validavo
requiredirpattern HiddenContextItem, rankiniu būdu pridėtas į saugyklą (store), informuoja modelį apie naudotojo atliktus veiksmus- Jautrūs veiksmai eina per patvirtinimo kortelę; gryni lokaliniai veiksmai apdorojami naršyklėje (
handler: "client",widgets.onAction,sendCustomAction)