Darbības, ko veic lietotājs
Šajā lapā
Nodarbība pārrakstīta 2026. gada 3. novembrī. Iepriekšējā versija apstrādāja klikšķus pielāgotajos React komponentos un izgudroja „ieteikumu darbības”. ChatKit vidē darbība ir objekts, kas pievienots logrīka komponentam (poga, saraksta rinda, veidlapa). Pēc noklusējuma tā tiek apstrādāta tavo serverī, izmantojot
actionmetodi klasēChatKitServer, vai pārlūkprogrammā, ja norādi citādi. Šī nodarbība seko rokasgrāmatai Actions in ChatKit unopenai-chatkitSDK 1.6.5. versijai. Serveris, veidnes un veidlapas tika palaistas lokāli; React kods tika pārbaudīts, kompilējot. Avoti: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Kas ir darbība?
Logrīks, kas tikai attēlo saturu, ir tikai skaista atbilde. Darbības padara to noderīgu: noklikšķinot uz „Atcelt pasūtījumu”, izvēloties rindu sarakstā vai iesniedzot veidlapu, tiek uzsākta apstrāde, nelietotājam neko nerakstot. ChatKit nosūta darbību tavam serverim, kas var veikt darbības tavās sistēmās, atjaunināt logrīku, pievienot atbildi pavedienam vai restartēt aģentu.
Tu deklarē darbību logrīka veidnē komponentam, kas to pieņem (onClickAction priekš Button vai ListViewItem, onChangeAction priekš Select, onSubmitAction priekš Form, confirm un cancel priekš Card). Tas ir neliels JSON objekts:
| Lauks | Loma |
|---|---|
type | Darbības nosaukums, ko pārbauda tavs kods: "order.cancel" |
payload | Noderīgi dati: {"number": "C-42"} |
handler | "server" (pēc noklusējuma) vai "client", lai apstrādātu to pārlūkprogrammā |
loadingBehavior | Ielādes stāvoklis, kas tiek rādīts apstrādes laikā (skatīt zemāk) |
Darbības apstrāde serverī
Paņemsim pasūtījuma karti, kas piedāvā atcelšanu. Veidnē darbība tiek deklarēta kartes Card apstiprināšanas un atcelšanas pogām:
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 }}}}}
}
"""
Servera pusē pievieno action metodi savai ChatKitServer klasei. Tā saņem pavedienu, darbību, logrīku, kas to ģenerēja (sender), un tavu kontekstu, un atgriež notikumus, piemēram, 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(...) : kā 17. nodarbībā
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 nāk no pārlūka: atkārtoti pārbaudi atļaujas
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)
# Izsekojamība modelim, nekad nerādīta lietotājam
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.")
No šī koda izriet trīs likumi:
- Payload nav uzticams. Tas nonāk no pārlūka, kur jebkurš to var modificēt: OpenAI rokasgrāmata pieprasa uzskatīt to par nepārbaudītiem datiem. Pirms atcelšanas serveris pārbauda, vai pasūtījums pieder autentificētajam lietotājam.
user_idkontekstā ir tas, ko tavs autentificētais galapunkts tur ievieto (21. nodarbība). - Modelim ir jāzina, kas noticis. Klikšķis nav ziņojums: bez izsekojamības aģents nākamajā solī ignorētu, ka pasūtījums ir atcelts.
HiddenContextItempievieno šo informāciju pavedienam, to nerādot. SDK automātiski ieraksta tikai apraidē esošos elementus, un slēptam elementam nekad nevajadzētu būt apraidē: tev tas pašam ir jāpievieno store. - Atbilde ir notikumu straume. Šeit vienkāršs ziņojums; tā varētu būt atjaunināts logrīks, kas tiek pārraidīts ar
stream_widget, kā iepriekšējā nodarbībā.
Lai aģents komentētu tikko notikušo, restartē to pēc darbības: async for event in self.respond(thread, None, context): yield event. Tava respond metode atkārtoti nolasa pavedienu, atrod slēpto elementu un atbilstoši reaģē.
Veidlapas
Kad ievades lauki (Input, Textarea, Select, Checkbox, DatePicker…) tiek izvietoti Form ietvaros, to vērtības tiek pievienotas jebkuras no šīs veidlapas ģenerētas darbības payload zem katra lauka nosaukuma:
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}
]}
]
}
"""
Iesniedzot, action.payload satur source, order, category un detail. Punktotais nosaukums, "client.name", ģenerē ligzdotu vērtību: payload["client"]["name"]. Ja lauka nosaukums sakrīt ar atslēgu, kas jau eksistē payload, lauka vērtība tiek ignorēta un ChatKit ģenerē kļūdas notikumu: izvēlies unikālus nosaukumus.
Veidlapas validācija notiek pārlūkprogrammā: required un pattern bloķē iesniegšanu, kamēr lauks ir nederīgs. Tas ir lietotāja ērtībām, nevis aizsardzībai: atkārtoti validē serverī, piemēram, izmantojot Pydantic modeli.
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)
# action metodē
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.")
Bagātīgākai validācijai ar pielāgotiem kļūdu ziņojumiem dokumentācija iesaka pāriet ārpus logrīka: klienta puses darbība atver logu tavā lietotnē, un rezultāts atgriežas ChatKit, izmantojot sendCustomAction. Ņem vērā arī to, ka Card, kas deklarēts ar "asForm": true, uzvedas kā veidlapa: tās lauki tiek validēti un nodoti tās confirm darbībai.
Apstiprināšana pirms darbības
Atcelšanas karte sākumā ilustrē noteikumu, ko vispārināt: neatgriezeniska vai sensitīva darbība prasa skaidru apstiprinājumu. Pasūtījuma atcelšana, e-pasta sūtīšana, naudas atmaksāšana, dzēšana: aģents ierosina, lietotājs apstiprina kartē, kas skaidri norāda, kas notiks, un tavs serveris, nevis modelis, to izpilda pēc atļauju atkārtotas pārbaudes. Card pogas confirm un cancel ir paredzētas tieši tam. To noklusējuma ielādes stāvoklis pelēko visu karti apstrādes laikā, kas novērš dubultklikšķus.
Darbības apstrāde pārlūkprogrammā
Dažām darbībām serverī nav ko darīt: lapas atvēršana tavā lietotnē, saites kopēšana, modālā loga rādīšana. Deklarē tās ar "handler": "client" veidnē, piemēram, {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Tad tās nonāk saskarnes opcijā 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');
// Paziņo serverim, kas var atjaunināt logrīku
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction nosūta darbību tavam serverim tā, it kā tā nāktu no logrīka. Tā darbojas arī ārpus ChatKit: tava lapas poga var izsaukt chatkit.sendCustomAction({ type: 'cart.empty' }), lai asistents reaģētu uz notikumiem citur lietotnē.
Ielādes stāvokļi
loadingBehavior kontrolē to, ko lietotājs redz darbības apstrādes laikā:
| Vērtība | Efekts |
|---|---|
auto (pēc noklusējuma) | Pielāgojas komponentam: tikai poga priekš Button, nekas priekš Select, visa karte priekš Card confirm |
self | Ielādes stāvoklis tikai vienam komponentam, kam pieder darbība |
container | Viss logrīks izbalē un kļūst neaktīvs |
none | Nav ielādes stāvokļa |
Dokumentācija iesaka saglabāt auto, ja vien tev nav specifiskas vajadzības. Pēc noklusējuma darbības logrīkā tiek bloķētas arī tad, kad tiek straumēta atbilde, lai izvairītos no konfliktiem. Kopš SDK 1.6.2. versijas darbība, kas deklarēta ar "streaming": false, apej šo bloķēšanu: to apstrādā servera sync_action metode, kas paredzēta darbībām, kuras tikai atjaunina savu logrīku vai darbojas ārpus pavediena.
Galvenās atziņas
- Darbība ir objekts
{type, payload, handler, loadingBehavior}, kas pievienots logrīka komponentam; tā uzsāk apstrādi bez lietotāja ziņojuma - Serverī
ChatKitServermetodeactionto saņem un atgriež notikumus: ziņojumu, atjauninātu logrīku vai jaunu aģenta atbildi, izmantojotrespond - Payload nāk no pārlūka: atkārtoti pārbaudi atļaujas un datus serverī (Pydantic), pat ja veidlapa jau validē
requiredunpattern HiddenContextItem, kas manuāli pievienots store, informē modeli par lietotāja darbībām- Sensitīvas darbības iziet caur apstiprināšanas karti; tīri lokālas darbības tiek apstrādātas pārlūkprogrammā (
handler: "client",widgets.onAction,sendCustomAction)