Przejdź do głównej treści
Polski— Wybierz język
Menu

Akcje użytkownika

Lekcja 20 z 25 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Czym jest akcja?
  2. Przetwarzanie akcji na serwerze
  3. Formularze
  4. Potwierdzenie przed działaniem
  5. Przetwarzanie akcji w przeglądarce
  6. Stany ładowania
  7. Kluczowe wnioski

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 action klasy ChatKitServer lub w przeglądarce, jeśli określisz inaczej. Lekcja ta podąża za przewodnikiem Actions in ChatKit oraz SDK openai-chatkit w 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:

PoleRola
typeNazwa akcji testowana przez Twój kod: "order.cancel"
payloadPrzydatne dane: {"number": "C-42"}
handler"server" (domyślnie) lub "client" do przetwarzania w przeglądarce
loadingBehaviorStan ł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_id w 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. HiddenContextItem dodaje 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_widget jak 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
selfStan ładowania na pojedynczym komponencie posiadającym akcję
containerCały widżet blaknie i staje się nieaktywny
noneBrak 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 action klasy ChatKitServer otrzymuje ją i zwraca zdarzenia: wiadomość, zaktualizowany widżet lub nową odpowiedź agenta przez respond
  • Payload pochodzi z przeglądarki: ponownie zweryfikuj uprawnienia i dane na serwerze (Pydantic), nawet jeśli formularz już waliduje required i pattern
  • 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)