Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Akcie používateľa

Lekcia 20 z 25 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Čo je to akcia?
  2. Spracovanie akcie na serveri
  3. Formuláre
  4. Potvrdenie pred konaním
  5. Spracovanie akcie v prehliadači
  6. Stavy načítania
  7. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia spracovávala kliknutia vo vlastných komponentoch React a vymýšľala „návrhové akcie“. V ChatKite je akcia objekt pripojený ku komponentu widgetu (tlačidlo, riadok zoznamu, formulár). Predvolene sa spracúva na vašom serveri v metóde action triedy ChatKitServer, alebo v prehliadači, ak to špecifikujete inak. Táto lekcia vychádza z príručky Actions in ChatKit a SDK openai-chatkit 1.6.5. Server, šablóny a formulár boli spustené lokálne; kód React bol overený kompiláciou. Zdroje: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Čo je to akcia?

Widget, ktorý iba zobrazuje obsah, je len pekná odpoveď. Akcie z neho robia užitočný nástroj: kliknutie na „Zrušiť objednávku“, výber riadku v zozname alebo odoslanie formulára spustí spracovanie bez toho, aby používateľ musel písať správu. ChatKit odošle akciu na váš server, ktorý môže konať vo vašich systémoch, aktualizovať widget, pridať odpoveď do vlákna alebo reštartovať agenta.

Akciu deklarujete v šablóne widgetu na komponente, ktorý ju akceptuje (onClickAction pre Button alebo ListViewItem, onChangeAction pre Select, onSubmitAction pre Form, confirm a cancel pre Card). Ide o malý JSON objekt:

PoleÚloha
typeNázov akcie, ktorý váš kód testuje: "order.cancel"
payloadUžitočné dáta: {"number": "C-42"}
handler"server" (predvolené) alebo "client" na spracovanie v prehliadači
loadingBehaviorStav načítania zobrazený počas spracovania (viď nižšie)

Spracovanie akcie na serveri

Vezmime si kartu objednávky, ktorá ponúka zrušenie. Šablóna deklaruje akciu na tlačidlách potvrdenia a zrušenia 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 }}}}}
}
"""

Na strane servera pridajte do svojej triedy ChatKitServer metódu action. Prijíma vlákno, akciu, widget, ktorý ju vydal (sender), a váš kontext, a vracia udalosti ako 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(...) : ako v lekcii 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 prichádza z prehliadača: znovu overte oprávnenia
            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 pre model, nikdy nezobrazovaná používateľovi
            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 tohto kódu vyplývajú tri pravidlá:

  • Payload je nedôveryhodný. Prichádza z prehliadača, kde ho ktokoľvek môže upraviť: príručka OpenAI vyžaduje zaobchádzať s ním ako s neoverenými dátami. Pred zrušením server skontroluje, či objednávka patrí autentifikovanému používateľovi. user_id v kontexte je to, čo tam vloží váš autentifikovaný koncový bod (lekcia 21).
  • Model musí vedieť, čo sa stalo. Kliknutie nie je správa: bez stopy by agent v ďalšom kole ignoroval, že objednávka bola zrušená. HiddenContextItem pridá túto informáciu do vlákna bez toho, aby ju zobrazil. SDK automaticky zaznamenáva iba vysielané prvky a skrytý prvok sa nikdy nesmie vysielať: musíte ho sami pridať do úložiska (store).
  • Odpoveď je prúd udalostí. Tu jednoduchá správa; mohlo by ísť o aktualizovaný widget, vysielaný pomocou stream_widget ako v predchádzajúcej lekcii.

Ak chcete, aby sa agent vyjadril k tomu, čo sa práve stalo, reštartujte ho po akcii: async for event in self.respond(thread, None, context): yield event. Vaša metóda respond znova prečíta vlákno, nájde skrytý prvok a zodpovedajúcim spôsobom odpovie.

Formuláre

Keď sú vstupné polia (Input, Textarea, Select, Checkbox, DatePicker…) umiestnené vo vnútri Form, ich hodnoty sa pridajú do payloadu akejkoľvek akcie vydanej z tohto formulára pod názvom každého poľa:

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

Pri odoslaní action.payload obsahuje source, order, category a detail. Bodkovaný názov, napr. "client.name", vytvorí vnorenú hodnotu: payload["client"]["name"]. Ak sa názov poľa zhoduje s kľúčom, ktorý už v payloade existuje, hodnota poľa sa ignoruje a ChatKit vydá chybovú udalosť: vyberajte si jedinečné názvy.

Validácia formulára prebieha na strane prehliadača: required a pattern blokujú odoslanie, kým je pole neplatné. Ide o pohodlie používateľa, nie o ochranu: na serveri validáciu zopakujte, napríklad pomocou 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 metóde 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.")

Pre bohatšiu validáciu s vlastnými chybovými hláseniami dokumentácia odporúča presunúť sa mimo widget: akcia na strane klienta otvorí okno vo vašej aplikácii a výsledok sa vráti do ChatKitu cez sendCustomAction. Všimnite si tiež, že Card deklarovaný s "asForm": true sa správa ako formulár: jeho polia sa validujú a odovzdajú jeho akcii confirm.

Potvrdenie pred konaním

Karta zrušenia na začiatku ilustruje pravidlo, ktoré treba zovšeobecniť: nevratná alebo citlivá akcia vyžaduje explicitné potvrdenie. Zrušenie objednávky, odoslanie e-mailu, vrátenie peňazí, vymazanie: agent navrhne, používateľ potvrdí na karte, ktorá jasne uvádza, čo sa stane, a vykonanie po opätovnom overení oprávnení je na vašom serveri, nie na modeli. Na tento účel slúžia tlačidlá confirm a cancel komponentu Card. Ich predvolený stav načítania počas spracovania zašedí celú kartu, čo zabraňuje dvojitému kliknutiu.

Spracovanie akcie v prehliadači

Niektoré akcie nemajú na serveri čo robiť: otvorenie stránky vo vašej aplikácii, kopírovanie odkazu, zobrazenie modálneho okna. Deklarujte ich v šablóne s "handler": "client", napríklad {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Následne prídu do možnosti widgets.onAction rozhrania:

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');
          // Upovedomiť server, ktorý môže aktualizovať widget
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction odošle akciu na váš server, akoby pochádzala z widgetu. Funguje to aj mimo ChatKit: tlačidlo na vašej stránke môže zavolať chatkit.sendCustomAction({ type: 'cart.empty' }), aby asistent reagoval na to, čo sa deje inde v aplikácii.

Stavy načítania

loadingBehavior riadi, čo používateľ vidí počas spracovania akcie:

HodnotaEfekt
auto (predvolené)Prispôsobí sa komponentu: samotné tlačidlo pre Button, nič pre Select, celá karta pre confirm komponentu Card
selfStav načítania na jedinom komponente, ktorý drží akciu
containerCelý widget stmavne a stane sa neaktívnym
noneŽiadny stav načítania

Dokumentácia odporúča ponechať auto, pokiaľ nemáte špecifickú potrebu. Predvolene sú akcie na widgete tiež blokované, kým prebieha streamovanie odpovede, aby sa predišlo konfliktom. Od verzie SDK 1.6.2 akcia deklarovaná s "streaming": false obchádza toto blokovanie: spracováva ju metóda sync_action servera, vyhradená pre akcie, ktoré iba aktualizujú svoj vlastný widget alebo konajú mimo vlákna.

Kľúčové poznatky

  • Akcia je objekt {type, payload, handler, loadingBehavior} pripojený ku komponentu widgetu; spúšťa spracovanie bez používateľskej správy
  • Na serveri ju prijíma metóda action triedy ChatKitServer a vracia udalosti: správu, aktualizovaný widget alebo novú odpoveď agenta cez respond
  • Payload prichádza z prehliadača: na serveri znovu overte oprávnenia a dáta (Pydantic), aj keď formulár už validuje required a pattern
  • HiddenContextItem, manuálne pridaný do úložiska, informuje model o tom, čo používateľ urobil
  • Citlivé akcie prechádzajú potvrdzovacou kartou; čisto lokálne akcie sa spracúvajú v prehliadači (handler: "client", widgets.onAction, sendCustomAction)