Действия на потребителя
На тази страница
Урокът е пренаписан на 3 ноември 2026 г. Предишната версия обработваше кликвания в персонализирани React компоненти и измисляше „предложени действия“. В ChatKit действието е обект, прикачен към уиджет компонент (бутон, ред от списък, форма). По подразбиране то се обработва на вашия сървър в метода
actionнаChatKitServer, или в браузъра, ако уточните друго. Този урок следва ръководството Actions in ChatKit и SDKopenai-chatkitверсия 1.6.5. Сървърът, шаблоните и формата бяха стартирани локално; React кодът беше проверен чрез компилация. Източници: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Какво е действие?
Уиджет, който само показва съдържание, е просто красив отговор. Действията го правят полезен: кликването върху „Отказ на поръчка“, избирането на ред в списък или изпращането на форма задейства обработка без потребителят да трябва да пише съобщение. ChatKit изпраща действието до вашия сървър, който може да действа върху вашите системи, да актуализира уиджета, да добави отговор в нишката или да рестартира агента.
Вие декларирате действие в шаблона на уиджета върху компонент, който приема такова (onClickAction за Button или ListViewItem, onChangeAction за Select, onSubmitAction за Form, confirm и cancel за Card). То представлява малък JSON обект:
| Поле | Роля |
|---|---|
type | Името на действието, което вашият код тества: "order.cancel" |
payload | Полезни данни: {"number": "C-42"} |
handler | "server" (по подразбиране) или "client" за обработка в браузъра |
loadingBehavior | Състоянието на зареждане, показано по време на обработката (вижте по-долу) |
Обработка на действие на сървъра
Нека разгледаме карта за поръчка, която предлага отмяна. Шаблонът декларира действието върху бутоните за потвърждение и отказ на 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 }}}}}
}
"""
От страната на сървъра добавете метод action към вашия ChatKitServer. Той получава нишката, действието, уиджета, който го е издал (sender), и вашия контекст, и връща събития като 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(...) : както в урок 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 идва от браузъра: проверете отново правата
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)
# След за модела, никога не се показва на потребителя
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.")
От този код произлизат три правила:
- Payload е ненадежден. Той идва от браузъра, където всеки може да го модифицира: ръководството на OpenAI изисква третирането му като непроверени данни. Преди отмяна сървърът проверява дали поръчката принадлежи на удостоверения потребител.
user_idв контекста е този, който вашият удостоверен крайпоставя там (урок 21). - Моделът трябва да знае какво се е случило. Кликът не е съобщение: без следа агентът би игнорирал при следващия ход, че поръчката е отменена.
HiddenContextItemдобавя тази информация към нишката, без да я показва. SDK автоматично записва само излъчвани елементи, а скрит елемент никога не трябва да се излъчва: трябва сами да го добавите към хранилището (store). - Отговорът е поток от събития. Тук просто съобщение; може да бъде актуализиран уиджет, излъчен чрез
stream_widget, както в предишния урок.
За да може агентът да коментира току-що случилото се, рестартирайте го след действието: async for event in self.respond(thread, None, context): yield event. Вашият метод respond препрочита нишката, открива скрития елемент и отговаря съответно.
Форми
Когато полета за въвеждане (Input, Textarea, Select, Checkbox, DatePicker…) са поставени вътре в Form, техните стойности се добавят към payload на всяко действие, излъчено от тази форма, под името на всяко поле:
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}
]}
]
}
"""
При изпращане action.payload съдържа source, order, category и detail. Име с точка, като "client.name", създава вложена стойност: payload["client"]["name"]. Ако име на поле съвпада с ключ, вече присъстващ в payload, стойността на полето се игнорира и ChatKit излъчва събитие за грешка: избирайте различни имена.
Валидирането на формата е от страната на браузъра: required и pattern блокират изпращането, докато дадено поле е невалидно. Това е удобство за потребителя, а не защита: валидирайте отново на сървъра, например с 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)
# В метода за действие
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.")
За по-богато валидиране с персонализирани съобщения за грешки, документацията съветва да излезете извън уиджета: действие от страна на клиента отваря прозорец във вашето приложение, а резултатът се връща в ChatKit чрез sendCustomAction. Освен това Card, декларирана с "asForm": true, се държи като форма: нейните полета се валидират и се предават на нейното действие confirm.
Потвърждение преди действие
Картата за отмяна в началото илюстрира правило за обобщаване: необратимо или чувствително действие изисква изрично потвърждение. Отмяна на поръчка, изпращане на имейл, възстановяване на средства, изтриване: агентът предлага, потребителят валидира върху карта, която ясно посочва какво ще се случи, и вашият сървър, а не моделът, изпълнява действието след повторна проверка на правата. Бутоните confirm и cancel на Card са създадени за това. Тяхното състояние на зареждане по подразбиране оцветява цялата карта в сиво по време на обработката, което предотвратява двойните кликвания.
Обработка на действие в браузъра
Някои действия нямат какво да правят на сървъра: отваряне на страница във вашето приложение, копиране на връзка, показване на модален прозорец. Декларирайте ги с "handler": "client" в шаблона, например {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Тогава те пристигат в опцията 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');
// Уведомете сървъра, който може да актуализира уиджета
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction изпраща действие до вашия сървър, сякаш идва от уиджет. То работи и извън ChatKit: бутон на вашата страница може да извика chatkit.sendCustomAction({ type: 'cart.empty' }), така че асистентът да реагира на случващото се другаде в приложението.
Състояния на зареждане
loadingBehavior контролира какво вижда потребителят, докато се обработва дадено действие:
| Стойност | Ефект |
|---|---|
auto (по подразбиране) | Адаптира се към компонента: само бутонът за Button, нищо за Select, цялата карта за confirm на Card |
self | Състояние на зареждане върху единствения компонент, съдържащ действието |
container | Целият уиджет избледнява и става неактивен |
none | Няма състояние на зареждане |
Документацията препоръчва запазването на auto, освен ако нямате специфична нужда. По подразбиране действията върху уиджет също са блокирани, докато се излъчва отговор, за да се избегнат конфликти. От версия 1.6.2 на SDK, действие, декларирано с "streaming": false, заобикаля това блокиране: то се обработва от метода sync_action на сървъра, запазен за действия, които само актуализират собствения си уиджет или действат извън нишката.
Ключови изводи
- Действието е обект
{type, payload, handler, loadingBehavior}, прикачен към уиджет компонент; то задейства обработка без потребителско съобщение - На сървъра методът
actionнаChatKitServerго получава и връща събития: съобщение, актуализиран уиджет или нов отговор на агента чрезrespond - Payload идва от браузъра: проверете отново правата и данните на сървъра (Pydantic), дори когато формата вече валидира
requiredиpattern HiddenContextItem, ръчно добавен към хранилището, информира модела какво е направил потребителят- Чувствителните действия минават през карта за потвърждение; чисто локалните действия се обработват в браузъра (
handler: "client",widgets.onAction,sendCustomAction)