Akcje użytkownika
Na tej stronie
Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja obsługiwała kliknięcia w niestandardowych komponentach React i wymyślała „akcje sugerowane“. W ChatKit akcja to obiekt dołączony do komponentu widżetu (przycisk, wiersz listy, formularz). Domyślnie jest przetwarzana na Twoim serwerze w metodzie
actionklasyChatKitServerlub w przeglądarce, jeśli określisz inaczej. Lekcja ta podąża za przewodnikiem Actions in ChatKit oraz SDKopenai-chatkitw wersji 1.6.5. Serwer, szablony i formularz uruchomiono lokalnie; kod React zweryfikowano poprzez kompilację. Źródła: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Czym jest akcja?
Widżet, który jedynie wyświetla treść, to tylko ładna odpowiedź. Akcje sprawiają, że staje się użyteczny: kliknięcie „Anuluj zamówienie“, wybranie wiersza na liście lub przesłanie formularza uruchamia przetwarzanie bez konieczności wpisywania wiadomości przez użytkownika. ChatKit wysyła akcję na Twój serwer, który może podjąć działania w Twoich systemach, zaktualizować widżet, dodać odpowiedź do wątku lub uruchomić agenta ponownie.
Deklarujesz akcję w szablonie widżetu na komponencie, który ją akceptuje (onClickAction dla Button lub ListViewItem, onChangeAction dla Select, onSubmitAction dla Form, confirm i cancel dla Card). Jest to mały obiekt JSON:
| Pole | Rola |
|---|---|
type | Nazwa akcji testowana przez Twój kod: "order.cancel" |
payload | Przydatne dane: {"number": "C-42"} |
handler | "server" (domyślnie) lub "client" do przetwarzania w przeglądarce |
loadingBehavior | Stan ładowania wyświetlany podczas przetwarzania (patrz poniżej) |
Przetwarzanie akcji na serwerze
Weźmy kartę zamówienia oferującą anulowanie. Szablon deklaruje akcję na przyciskach potwierdzenia i anulowania komponentu 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 }}}}}
}
"""
Po stronie serwera dodaj metodę action do swojej klasy ChatKitServer. Otrzymuje ona wątek, akcję, widżet, który ją wyemitował (sender), oraz Twój kontekst, a zwraca zdarzenia takie jak 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(...) : jak w lekcji 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 pochodzi z przeglądarki: ponownie zweryfikuj uprawnienia
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)
# Ślad dla modelu, nigdy niewyświetlany użytkownikowi
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.")
Z tego kodu wynikają trzy zasady:
- Payload jest niezaufany. Przybywa z przeglądarki, gdzie każdy może go zmodyfikować: przewodnik OpenAI wymaga traktowania go jako danych niezweryfikowanych. Przed anulowaniem serwer sprawdza, czy zamówienie należy do uwierzytelnionego użytkownika.
user_idw kontekście to wartość umieszczona tam przez Twój uwierzytelniony punkt końcowy (lekcja 21). - Model musi wiedzieć, co się stało. Kliknięcie to nie wiadomość: bez śladu agent w następnej turze zignorowałby fakt anulowania zamówienia.
HiddenContextItemdodaje tę informację do wątku bez jej wyświetlania. SDK automatycznie rejestruje jedynie elementy nadawane (broadcast), a element ukryty nigdy nie powinien być nadawany: musisz dodać go samodzielnie do store. - Odpowiedź to strumień zdarzeń. Tutaj prosta wiadomość; mogłaby to być zaktualizowany widżet, nadawany za pomocą
stream_widgetjak w poprzedniej lekcji.
Aby agent skomentował to, co właśnie się wydarzyło, uruchom go ponownie po akcji: async for event in self.respond(thread, None, context): yield event. Twoja metoda respond ponownie odczytuje wątek, znajduje ukryty element i odpowiada odpowiednio.
Formularze
Gdy pola wprowadzania danych (Input, Textarea, Select, Checkbox, DatePicker…) zostaną umieszczone wewnątrz Form, ich wartości są dodawane do payloadu dowolnej akcji emitowanej z tego formularza pod nazwą każdego pola:
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}
]}
]
}
"""
Przy przesłaniu action.payload zawiera source, order, category i detail. Nazwa kropkowana, np. "client.name", tworzy wartość zagnieżdżoną: payload["client"]["name"]. Jeśli nazwa pola koliduje z kluczem już obecnym w payloadzie, wartość pola jest ignorowana, a ChatKit emituje zdarzenie błędu: wybieraj unikalne nazwy.
Walidacja formularza odbywa się po stronie przeglądarki: required i pattern blokują przesłanie, dopóki pole jest nieprawidłowe. To wygoda dla użytkownika, a nie zabezpieczenie: przeprowadź walidację ponownie na serwerze, na przykład za pomocą modelu 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)
# W metodzie action
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.")
W przypadku bardziej zaawansowanej walidacji z niestandardowymi komunikatami o błędach dokumentacja zaleca wyjście poza widżet: akcja po stronie klienta otwiera okno w Twojej aplikacji, a wynik wraca do ChatKit przez sendCustomAction. Zauważ również, że Card zadeklarowany z "asForm": true zachowuje się jak formularz: jego pola są walidowane i przekazywane do jego akcji confirm.
Potwierdzenie przed działaniem
Karta anulowania z początku ilustruje zasadę, którą warto uogólnić: akcja nieodwracalna lub wrażliwa wymaga wyraźnego potwierdzenia. Anulowanie zamówienia, wysyłanie e-maila, zwrot pieniędzy, usuwanie: agent proponuje, użytkownik zatwierdza na karcie, która jasno określa, co się stanie, a to Twój serwer, a nie model, wykonuje działanie po ponownej weryfikacji uprawnień. Przyciski confirm i cancel komponentu Card służą właśnie do tego. Ich domyślny stan ładowania wyszarza całą kartę podczas przetwarzania, co zapobiega podwójnym kliknięciom.
Przetwarzanie akcji w przeglądarce
Niektóre akcje nie wymagają żadnych działań po stronie serwera: otwarcie strony w Twojej aplikacji, skopiowanie linku, wyświetlenie modalu. Zadeklaruj je z "handler": "client" w szablonie, na przykład {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Trafiają one wtedy do opcji widgets.onAction interfejsu:
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');
// Powiadom serwer, który może zaktualizować widżet
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction wysyła akcję na Twój serwer tak, jakby pochodziła z widżetu. Działa to również poza ChatKit: przycisk na Twojej stronie może wywołać chatkit.sendCustomAction({ type: 'cart.empty' }), aby asystent zareagował na to, co dzieje się gdzie indziej w aplikacji.
Stany ładowania
loadingBehavior kontroluje to, co widzi użytkownik podczas przetwarzania akcji:
| Wartość | Efekt |
|---|---|
auto (domyślnie) | Dostosowuje się do komponentu: sam przycisk dla Button, nic dla Select, cała karta dla confirm w Card |
self | Stan ładowania na pojedynczym komponencie posiadającym akcję |
container | Cały widżet blaknie i staje się nieaktywny |
none | Brak stanu ładowania |
Dokumentacja zaleca pozostawienie auto, chyba że masz specyficzną potrzebę. Domyślnie akcje na widżecie są również blokowane podczas strumieniowania odpowiedzi, aby uniknąć konfliktów. Od wersji SDK 1.6.2 akcja zadeklarowana z "streaming": false omija to blokowanie: jest przetwarzana przez metodę sync_action serwera, zarezerwowaną dla akcji, które jedynie aktualizują swój własny widżet lub działają poza wątkiem.
Kluczowe wnioski
- Akcja to obiekt
{type, payload, handler, loadingBehavior}dołączony do komponentu widżetu; uruchamia przetwarzanie bez wiadomości od użytkownika - Na serwerze metoda
actionklasyChatKitServerotrzymuje ją i zwraca zdarzenia: wiadomość, zaktualizowany widżet lub nową odpowiedź agenta przezrespond - Payload pochodzi z przeglądarki: ponownie zweryfikuj uprawnienia i dane na serwerze (Pydantic), nawet jeśli formularz już waliduje
requiredipattern HiddenContextItem, ręcznie dodany do store, informuje model o tym, co zrobił użytkownik- Akcje wrażliwe przechodzą przez kartę potwierdzenia; akcje czysto lokalne są przetwarzane w przeglądarce (
handler: "client",widgets.onAction,sendCustomAction)