Gníomhartha Úsáideora
Ar an leathanach seo
Ceacht athscríofa an 3 Samhain 2026. Láimhsíodh briatharú i gcomhpháirteanna React saincheaptha sa leagan roimhe seo agus cheap sé “suggestion actions”. I ChatKit, is réad é gníomh a bhaineann le comhpháirt widget (cnaipe, sraith liosta, foirm). De réir réamhshocraithe, próiseáiltear ar do fhreastalaí é i modh
actionde chuidChatKitServer, nó sa bhrabhsálaí má shonraíonn tú a mhalairt. Leanann an cheacht seo an treoir Actions in ChatKit agus SDKopenai-chatkit1.6.5. Rithheadh an freastalaí, na teimpléid agus an fhoirm go háitiúil; fíoraíodh an cód React le compileáil. Foinsí: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Cad is gníomh ann?
Níl i widget nach dtaispeánann ach ábhar ach freagra deas. Déanann gníomhartha úsáideach é: spreagann brú ar “Cancel Order”, roghnú sraith i liosta, nó foirm a chur isteach próiseáil gan gá don úsáideoir teachtaireacht a chlóscríobh. Seolann ChatKit an gníomh chuig d’fhreastalaí, a d’fhéadfadh gníomhú ar do chórais, an widget a nuashonrú, freagra a chur leis an snáithe, nó an t-aonán a atosú.
Fógraíonn tú gníomh i dteimpléad an widget ar chomhpháirt a ghlacann leis (onClickAction do Button nó ListViewItem, onChangeAction do Select, onSubmitAction do Form, confirm agus cancel do Card). Is réad JSON beag é:
| Réimse | Ról |
|---|---|
type | Ainm an ghnímh a thástálann do chód: "order.cancel" |
payload | Sonraí úsáideacha: {"number": "C-42"} |
handler | "server" (réamhshocraithe) nó "client" chun é a phróiseáil sa bhrabhsálaí |
loadingBehavior | An staid ualaithe a thaispeántar le linn próiseála (féach thíos) |
Gníomh a phróiseáil ar an bhfreastalaí
Tógaimis cárta orduithe a chuireann cealú ar fáil. Fógraíonn an teimpléad an gníomh ar chnaipí deimhnithe agus cealaithe an 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 }}}}}
}
"""
Ar thaobh an fhreastalaí, cuir modh action le do ChatKitServer. Faigheann sé an snáithe, an gníomh, an widget a sheol é (sender) agus do chomhthéacs, agus filleann sé teagmhasaim ar nós 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(...) : as in lesson 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", ""))
# The payload comes from the browser: re-verify permissions
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)
# A trace for the model, never shown to the user
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.")
Tagann trí riail chun solais ón gcód seo:
- Tagann an payload gan iontaoibh. Tiocfaidh sé ón mbrabhsálaí, áit a bhféadfadh duine ar bith é a athrú: éilíonn treoir OpenAI é a láimhseáil mar shonraí neamhfíordheimhnithe. Roimh chealú, seiceálann an freastalaí gur don úsáideoir fíordheimhnithe atá an t-ordú. Is é
user_idsa chomhthéacs an ceann a chuireann do chríochphointe fíordheimhnithe ann (ceacht 21). - Caithfidh an múnla a fháil amach cad a tharla. Ní teachtaireacht í briogáil: gan rian, bheadh ar an aonán a bheith gan fhios ag an chéad seal eile gur cealaíodh an t-ordú. Cuireann
HiddenContextIteman t-eolas seo leis an snáithe gan é a thaispeáint. Ní thaifeadann an SDK go huathoibríoch ach eilimintí craoltha, agus níor cheart eilimint fholaithe a chraoladh riamh: ní mór duit féin í a chur leis an store. - Sruth teagmhas is ea an freagra. Teachtaireacht shimplí anseo; d’fhéadfadh sé a bheith ina widget nuashonraithe, craolta le
stream_widgetmar sa cheacht roimhe.
Chun go ndéanfaidh an t-aonán trácht ar an méid a tharla anois díreach, atos é tar éis an ghnímh: async for event in self.respond(thread, None, context): yield event. Athléann do mhodh respond an snáithe, aimsíonn sé an eilimint fholaithe, agus freagraíonn dá réir.
Foirmeacha
Nuair a chuirtear réimsí ionchuir (Input, Textarea, Select, Checkbox, DatePicker…) isteach i Form, cuirtear a luachanna le payload aon ghnímh a sheoltar ón bhfoirm sin, faoi ainm gach réimse:
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}
]}
]
}
"""
Ar sheoladh, beidh source, order, category agus detail i action.payload. Gineann ainm poncaithe, "client.name", luach neadaithe: payload["client"]["name"]. Má bhuaileann ainm réimse le eochair atá sa payload cheana, déantar neamhaird den luach agus seolann ChatKit teagmhas earráide: roghnaigh ainmneacha ar leith.
Is ar thaobh an bhrabhsúraigh atá bailíochtú na foirme: cuireann required agus pattern cosc ar sheoladh fad is atá réimse neamhbhailí. Compord úsáideora é seo, ní cosaint: athbhailíochtaigh ar an bhfreastalaí, le samhail Pydantic mar shampla.
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)
# In the action method
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.")
I gcás bailíochtú níos saibhre, le teachtaireachtaí earráide saincheaptha, molann an doiciméadacht imeacht ón widget: osclaíonn gníomh cliaint fuinneog i d’fheidhmchlár, agus filleann an toradh ar ChatKit trí sendCustomAction. Tabhair faoi deara freisin go bhfeidhmíonn Card arna fhógra le "asForm": true mar fhoirm: bailíochtaítear a réimsí agus seoltar iad chuig a ghníomh confirm.
Deimhnigh sula ngníomhaíonn tú
Léiríonn an cárta cealaithe ag an tús riail ba chóir a ghinearálú: teastaíonn deimhniú soiléir d’gníomh nach féidir a chasadh ar ais nó a bhfuil íogaireacht leis. Cealú ordu, seoladh ríomhphoist, aisíocaíocht, scriosadh: molann an t-aonán, deimhníonn an t-úsáideoir ar chárta a deir go soiléir cad a tharlóidh, agus is é do fhreastalaí, ní an múnla, a fhorghníomhnaíonn tar éis ceadanna a athsheiceáil. Rinneadh cnaipí confirm agus cancel de chuid Card dá chomhair. Liathann a staid ualaithe réamhshocraithe an cárta ar fad le linn próiseála, rud a chuireann cosc ar dhéchriog.
Gníomh a phróiseáil sa bhrabhsálaí
Níl áit ar bith ag gníomhartha áirithe ar an bhfreastalaí: leathanach a oscailt i d’fheidhmchlár, nasc a chóipeáil, módal a thaispeáint. Fógraíonn tú iad le "handler": "client" sa teimpléad, mar shampla {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Tiocfaidh siad ansin isteach sa rogha widgets.onAction den chomhéadan:
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');
// Notify the server, which can update the widget
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
Seolann sendCustomAction gníomh chuig d’fhreastalaí amhail is dá dtarlódh sé ó widget. Feidhmíonn sé lasmuigh de ChatKit freisin: is féidir le cnaipe ar do leathán chatkit.sendCustomAction({ type: 'cart.empty' }) a ghlaoch ionas go ndéanann an cúntóir freagairt don méid atá ag tarlú in áit eile san iarratas.
Stáit Ualaithe
Rialaíonn loadingBehavior an méid a fheiceann an t-úsáideoir le linn gníomh á phróiseáil:
| Luach | Iarmhairt |
|---|---|
auto (réamhshocraithe) | Oiriúnaíonn don chomhpháirt: an cnaipe leis féin do Button, tada do Select, an cárta ar fad do confirm de chuid Card |
self | Staid ualaithe ar an gcomhpháirt aonair a iompraíonn an gníomh |
container | Maolaíonn an widget ar fad agus éiríonn neamhghníomhach |
none | Gan staid ualaithe |
Molann an doiciméadacht auto a choinneáil, mura bhfuil gá ar leith agat. De réir réamhshocraithe, cuirter bac ar ghníomhartha ar widget le linn freagra ag sruthú chomh maith, chun coinbhleachtaí a sheachaint. Ó leagan 1.6.2 den SDK, téann gníomh arna fhógra le "streaming": false thar an mbac seo: próiseálann modh sync_action an fhreastalaí é, atá in áirithe do ghníomhartha a nuashonraíonn a widget féin amháin nó a ghníomhaíonn lasmuigh den snáithe.
Príomhphointí
- Is réad é gníomh
{type, payload, handler, loadingBehavior}a bhaineann le comhpháirt widget; spreagann sé próiseáil gan teachtaireacht úsáideora - Ar an bhfreastalaí, faigheann modh
actionde chuidChatKitServeré agus filleann sé teagmhasaim: teachtaireacht, widget nuashonraithe, nó freagra nua ón aonán trírespond - Tagann an payload ón mbrabhsálaí: athsheiceáil ceadanna agus sonraí ar an bhfreastalaí (Pydantic), fiú nuair a bhailíochtaíonn an fhoirm
requiredaguspatternann féin - Cuirtear
HiddenContextItem, arna chur leis an store de láimh, an múnla ar an eolas faoin méid a rinne an t-úsáideoir - Téann gníomhartha íogair trí chárta deimhnithe; próiseáiltear gníomhartha atá go hiomlán áitiúil sa bhrabhsálaí (
handler: "client",widgets.onAction,sendCustomAction)