Azzjonijiet tal-Utent
F'din il-paġna
Lezzjoni miktuba mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kienet tittratta l-klikks f’komponenti React personalizzati u ħolqot “azzjonijiet ta’ suġġeriment” inventati. F’ChatKit, azzjoni hija oġġett imwaħħal ma’ komponent widget (buttuna, ringiela ta’ lista, formola). B’mod default, tiġi pproċessata fis-server tiegħek fil-metodu
actionta’ChatKitServer, jew fil-browser jekk tispeċifika mod ieħor. Din il-lezzjoni ssegwi l-gwida Actions in ChatKit u l-SDKopenai-chatkit1.6.5. Is-server, it-templates, u l-formola tħaddmu lokalment; il-kodiċi React ġie vverifikat permezz tal-kompilazzjoni. Sorsi: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
X’inhi azzjoni?
Widget li juri biss kontenut huwa sempliċiment tweġiba sabiħa. L-azzjonijiet jagħmluha utli: il-klikk fuq “Ikkanċella l-Ordni”, l-għażla ta’ ringiela f’lista, jew is-sottomissjoni ta’ formola jattivaw l-ipproċessar mingħajr ma l-utent ikollu jikteb messaġġ. ChatKit jibgħat l-azzjoni lis-server tiegħek, li jista’ jaġixxi fuq is-sistemi tiegħek, jaġġorna l-widget, iżid tweġiba fit-thread, jew jerġa’ jibda l-aġent.
Tiddikjara azzjoni fit-template tal-widget fuq komponent li jaċċettaha (onClickAction għal Button jew ListViewItem, onChangeAction għal Select, onSubmitAction għal Form, confirm u cancel għal Card). Huwa oġġett JSON żgħir:
| Qasam | Rwol |
|---|---|
type | L-isem tal-azzjoni li l-kodiċi tiegħek jittestja: "order.cancel" |
payload | Data utli: {"number": "C-42"} |
handler | "server" (default) jew "client" biex tipproċessaha fil-browser |
loadingBehavior | L-istat ta’ tagħbija muri waqt l-ipproċessar (ara hawn taħt) |
Ipproċessar ta’ azzjoni fuq is-server
Ħa nieħdu kard tal-ordni li toffri l-kanċellazzjoni. It-template jiddikjara l-azzjoni fuq il-buttuni ta’ konferma u kanċellazzjoni tal-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 }}}}}
}
"""
Fuq in-naħa tas-server, żid metodu action fil-ChatKitServer tiegħek. Jirċievi t-thread, l-azzjoni, il-widget li emettiha (sender), u l-kuntest tiegħek, u jirritorna avvenimenti bħal 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(...) : kif fil-lezzjoni 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", ""))
# Il-payload jiġi mill-browser: ivverifika mill-ġdid il-permessi
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)
# Traċċa għall-mudell, qatt muriha lill-utent
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.")
Tliet regoli joħorġu minn dan il-kodiċi:
- Il-payload mhuwiex affidabbli. Jasal mill-browser, fejn kulħadd jista’ jimmodifikah: il-gwida ta’ OpenAI teħtieġ li tittrattah bħala data mhux ivverifikata. Qabel ma tikkanċella, is-server jiċċekkja li l-ordni tappartjeni lill-utent awtentikat. L-
user_idfil-kuntest huwa dak li l-endpoint awtentikat tiegħek ipoġġi hemmhekk (lezzjoni 21). - Il-mudell irid ikun jaf x’ġara. Klikk mhix messaġġ: mingħajr traċċa, l-aġent jinjora fit-tidwira li jmiss li l-ordni ġiet ikkanċellata.
HiddenContextItemiżid din l-informazzjoni fit-thread mingħajr ma juriha. L-SDK jirreġistra awtomatikament biss elementi mxandra, u element moħbi qatt m’għandu jintbagħat b’broadcast: trid iżidu int stess fil-maħżen (store). - It-tweġiba hija fluss ta’ avvenimenti. Hawnhekk messaġġ sempliċi; jista’ jkun widget aġġornat, mxandar b’
stream_widgetbħal fil-lezzjoni preċedenti.
Biex l-aġent jikkummenta dwar dak li għadu kemm ġara, erġa’ bdieh wara l-azzjoni: async for event in self.respond(thread, None, context): yield event. Il-metodu respond tiegħek jerġa’ jaqra t-thread, isib l-element moħbi, u jwieġeb skont dan.
Formoli
Meta oqsma ta’ input (Input, Textarea, Select, Checkbox, DatePicker…) jitqiegħdu ġewwa Form, il-valuri tagħhom jiżdiedu mal-payload ta’ kwalunkwe azzjoni emessa minn dik il-formola, taħt l-isem ta’ kull qasam:
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}
]}
]
}
"""
Mas-sottomissjoni, action.payload fih source, order, category, u detail. Isem b’punt, "client.name", jipproduċi valur imbejjat: payload["client"]["name"]. Jekk isem ta’ qasam jikkolliża ma’ ċavetta diġà preżenti fil-payload, il-valur tal-qasam jiġi injorat u ChatKit jemetti avveniment ta’ żball: agħżel ismijiet distinti.
Il-validazzjoni tal-formola hija fuq in-naħa tal-browser: required u pattern jimblokkaw is-sottomissjoni waqt li qasam ikun invalidu. Din hija konvenjenza għall-utent, mhux protezzjoni: erġa’ vvalida fuq is-server, pereżempju b’mudell 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)
# Fil-metodu tal-azzjoni
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.")
Għal validazzjoni aktar rikka, b’messaġġi ta’ żball personalizzati, id-dokumentazzjoni tissuġġerixxi li toħroġ barra mill-widget: azzjoni fuq in-naħa tal-klijent tiftaħ tieqa fl-applikazzjoni tiegħek, u r-riżultat jerġa’ lura lejn ChatKit permezz ta’ sendCustomAction. Innota wkoll li Card iddikjarata b’"asForm": true tiġi ttrattata bħala formola: il-kampi tagħha jiġu vvalidati u mgħoddija lill-azzjoni confirm tagħha.
Ikkonferma qabel ma taġixxi
Il-kard tal-kanċellazzjoni fil-bidu turi regola li għandha tiġi ġeneralizzata: azzjoni irreversibbli jew sensittiva teħtieġ konferma espliċita. Il-kanċellazzjoni ta’ ordni, l-ibgħat ta’ email, ir-rimbors, it-tħassir: l-aġent jipproponi, l-utent jivvalida fuq kard li tiddikjara b’mod ċar x’se jiġri, u huwa s-server tiegħek, mhux il-mudell, li jesegwixxi wara li jerġa’ jivverifika l-permessi. Il-buttuni confirm u cancel ta’ Card huma magħmula għal dan. L-istat ta’ tagħbija default tagħhom jagħmel il-kard kollha griża waqt l-ipproċessar, li jipprevjeni d-doppju klikk.
Ipproċessar ta’ azzjoni fil-browser
Xi azzjonijiet m’għandhom x’jaqsmu xejn mas-server: il-ftuħ ta’ paġna fl-applikazzjoni tiegħek, il-kopja ta’ link, jew il-wiri ta’ modali. Iddikjarahom b’"handler": "client" fit-template, pereżempju {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Imbagħad jaslu fl-għażla widgets.onAction tal-interfaċċa:
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');
// Avża lis-server, li jista' jaġġorna l-widget
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction jibgħat azzjoni lis-server tiegħek daqslikieku ġejja minn widget. Taħdem ukoll barra minn ChatKit: buttuna fil-paġna tiegħek tista’ ssejjaħ chatkit.sendCustomAction({ type: 'cart.empty' }) biex l-assistent jirreaġixxi għal dak li qed jiġri f’post ieħor fl-applikazzjoni.
Stati ta’ tagħbija
loadingBehavior jikkontrolla x’jara l-utent waqt li azzjoni tkun qed tiġi pproċessata:
| Valur | Effett |
|---|---|
auto (default) | Jadatta għall-komponent: il-buttuna waħedha għal Button, xejn għal Select, il-kard kollha għall-confirm ta’ Card |
self | Stat ta’ tagħbija fuq il-komponent wieħed li fih l-azzjoni |
container | Il-widget kollu jsir ċar u jsir inattiv |
none | L-ebda stat ta’ tagħbija |
Id-dokumentazzjoni tirrakkomanda li żżomm auto, sakemm ma jkollokx ħtieġa speċifika. B’mod default, l-azzjonijiet fuq widget huma mblukkati wkoll waqt li tweġiba tkun qed tiġi mxandra, biex jiġu evitati kunflitti. Mill-verżjoni 1.6.2 tal-SDK ‘l quddiem, azzjoni ddikjarata b’"streaming": false taqbeż dan il-blokk: tiġi pproċessata mill-metodu sync_action tas-server, riżervat għal azzjonijiet li jaġġornaw biss il-widget tagħhom stess jew jaġixxu barra mit-thread.
Punti Ewlenin
- Azzjoni hija oġġett
{type, payload, handler, loadingBehavior}imwaħħal ma’ komponent widget; tattivaw l-ipproċessar mingħajr messaġġ tal-utent - Fuq is-server, il-metodu
actionta’ChatKitServerjirċieviha u jirritorna avvenimenti: messaġġ, widget aġġornat, jew tweġiba ġdida tal-aġent permezz ta’respond - Il-payload jiġi mill-browser: erġa’ vverifika l-permessi u d-data fuq is-server (Pydantic), anke meta l-formola diġà tivvalida
requiredupattern HiddenContextItem, miżjud manwalment fil-maħżen, jinforma lill-mudell dwar dak li għamel l-utent- Azzjonijiet sensittivi jgħaddu minn kard ta’ konferma; azzjonijiet purament lokali jiġu pproċessati fil-browser (
handler: "client",widgets.onAction,sendCustomAction)