Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Akce uživatele

Lekce 20 z 25 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Co je to akce?
  2. Zpracování akce na serveru
  3. Formuláře
  4. Potvrzení před provedením
  5. Zpracování akce v prohlížeči
  6. Stavy načítání
  7. Klíčové poznatky

Lekce přepsána 3. listopadu 2026. Předchozí verze zpracovávala kliknutí ve vlastních komponentách React a vymýšlela „návrhové akce“. V ChatKitu je akce objekt připojený ke komponentě widgetu (tlačítko, řádek seznamu, formulář). Ve výchozím nastavení se zpracovává na vašem serveru v metodě action třídy ChatKitServer, nebo v prohlížeči, pokud určíte jinak. Tato lekce vychází z průvodce Akce v ChatKitu a SDK openai-chatkit verze 1.6.5. Server, šablony a formulář byly spuštěny lokálně; kód React byl ověřen kompilací. Zdroje: Akce v ChatKitu · Vytváření interaktivních odpovědí s widgety · Poznámky k vydání Python SDK 1.6.2.

Co je to akce?

Widget, který pouze zobrazuje obsah, je jen hezká odpověď. Akce z něj dělají užitečný nástroj: kliknutí na „Zrušit objednávku“, výběr řádku v seznamu nebo odeslání formuláře spustí zpracování bez toho, aby uživatel musel psát zprávu. ChatKit odešle akci na váš server, který může zasáhnout do vašich systémů, aktualizovat widget, přidat do vlákna odpověď nebo restartovat agenta.

Akci deklarujete v šabloně widgetu na komponentě, která ji přijímá (onClickAction pro Button nebo ListViewItem, onChangeAction pro Select, onSubmitAction pro Form, confirm a cancel pro Card). Jedná se o malý JSON objekt:

PoleRole
typeNázev akce, který váš kód testuje: "order.cancel"
payloadUžitečná data: {"number": "C-42"}
handler"server" (výchozí) nebo "client" pro zpracování v prohlížeči
loadingBehaviorStav načítání zobrazený během zpracování (viz níže)

Zpracování akce na serveru

Vezměme si kartu objednávky, která nabízí zrušení. Šablona deklaruje akci na tlačítkách potvrzení a zrušení komponenty 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 }}}}}
}
"""

Na straně serveru přidejte do své třídy ChatKitServer metodu action. Přijímá vlákno, akci, widget, který ji vydal (sender), a váš kontext, a vrací události jako 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(...) : jako v lekci 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 přichází z prohlížeče: znovu ověřte oprávnění
            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)
            # Stopa pro model, nikdy nezobrazená uživateli
            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 tohoto kódu vyplývají tři pravidla:

  • Payload není důvěryhodný. Přichází z prohlížeče, kde jej kdokoli může upravit: průvodce OpenAI vyžaduje zacházet s ním jako s neověřenými daty. Před zrušením server zkontroluje, zda objednávka patří přihlášenému uživateli. user_id v kontextu je to, které tam umístí váš autentizovaný koncový bod (lekce 21).
  • Model se musí dozvědět, co se stalo. Kliknutí není zpráva: bez stopy by agent v dalším kole ignoroval, že objednávka byla zrušena. HiddenContextItem přidá tuto informaci do vlákna, aniž by ji zobrazil. SDK automaticky zaznamenává pouze prvky určené k vysílání a skrytý prvek nesmí být nikdy vysílán: musíte jej sami přidat do úložiště (store).
  • Odpověď je proud událostí. Zde jednoduchá zpráva; mohlo by jít o aktualizovaný widget, vysílaný pomocí stream_widget jako v předchozí lekci.

Aby se agent vyjádřil k tomu, co se právě stalo, restartujte jej po akci: async for event in self.respond(thread, None, context): yield event. Vaše metoda respond znovu přečte vlákno, najde skrytý prvek a odpoví odpovídajícím způsobem.

Formuláře

Když jsou vstupní pole (Input, Textarea, Select, Checkbox, DatePicker…) umístěna uvnitř Form, jejich hodnoty se přidají do payloadu jakékoli akce vyslané z tohoto formuláře pod názvem každého pole:

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}
     ]}
  ]
}
"""

Při odeslání obsahuje action.payload položky source, order, category a detail. Tečkovaný název, "client.name", vytvoří vnořenou hodnotu: payload["client"]["name"]. Pokud název pole koliduje s klíčem, který již v payloadu existuje, hodnota pole se ignoruje a ChatKit vydá chybovou událost: vybírejte jedinečné názvy.

Validace formuláře probíhá na straně prohlížeče: required a pattern blokují odeslání, dokud je pole neplatné. Je to uživatelské pohodlí, nikoli ochrana: znovu validujte na serveru, například 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)


# V metodě 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.")

Pro sofistikovanější validaci s vlastními chybovými zprávami dokumentace doporučuje přesunout se mimo widget: akce na straně klienta otevře okno ve vaší aplikaci a výsledek se vrátí do ChatKitu prostřednictvím sendCustomAction. Všimněte si také, že Card deklarovaná s "asForm": true se chová jako formulář: její pole jsou validována a předána její akci confirm.

Potvrzení před provedením

Karta pro zrušení na začátku ilustruje pravidlo, které byste měli zobecnit: nevratná nebo citlivá akce vyžaduje explicitní potvrzení. Zrušení objednávky, odeslání e-mailu, vrácení peněz, smazání: agent navrhne, uživatel potvrdí na kartě, která jasně uvádí, co se stane, a až váš server (nikoli model) provede akci po opětovném ověření oprávnění. Tlačítka confirm a cancel komponenty Card jsou určena právě pro toto. Jejich výchozí stav načítání zešedí celou kartu během zpracování, což zabraňuje dvojímu kliknutí.

Zpracování akce v prohlížeči

Některé akce nemají na serveru co dělat: otevření stránky ve vaší aplikaci, zkopírování odkazu, zobrazení modálního okna. Deklarujte je v šabloně s "handler": "client", například {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Poté dorazí do volby widgets.onAction rozhraní:

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');
          // Upozornit server, který může aktualizovat widget
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

  return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}

sendCustomAction odešle akci na váš server, jako by přišla z widgetu. Funguje také mimo ChatKit: tlačítko na vaší stránce může zavolat chatkit.sendCustomAction({ type: 'cart.empty' }), aby asistent reagoval na to, co se děje jinde v aplikaci.

Stavy načítání

loadingBehavior řídí, co uživatel vidí, zatímco se akce zpracovává:

HodnotaEfekt
auto (výchozí)Přizpůsobí se komponentě: pouze tlačítko pro Button, nic pro Select, celá karta pro confirm u Card
selfStav načítání na jediné komponentě, která akci obsahuje
containerCelý widget zbledne a stane se neaktivním
noneŽádný stav načítání

Dokumentace doporučuje ponechat auto, pokud nemáte specifickou potřebu. Ve výchozím nastavení jsou akce na widgetu také blokovány, zatímco probíhá streamování odpovědi, aby se předešlo konfliktům. Od verze SDK 1.6.2 akce deklarovaná s "streaming": false toto blokování obchází: zpracovává ji metoda sync_action serveru, vyhrazená pro akce, které pouze aktualizují svůj vlastní widget nebo působí mimo vlákno.

Klíčové poznatky

  • Akce je objekt {type, payload, handler, loadingBehavior} připojený ke komponentě widgetu; spouští zpracování bez uživatelské zprávy
  • Na serveru ji přijímá metoda action třídy ChatKitServer a vrací události: zprávu, aktualizovaný widget nebo novou odpověď agenta přes respond
  • Payload přichází z prohlížeče: znovu ověřte oprávnění a data na serveru (Pydantic), i když formulář již validuje required a pattern
  • HiddenContextItem, ručně přidaný do úložiště, informuje model o tom, co uživatel provedl
  • Citlivé akce procházejí potvrzovací kartou; čistě lokální akce se zpracovávají v prohlížeči (handler: "client", widgets.onAction, sendCustomAction)