Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Uporabniška dejanja

Lekcija 20 od 25 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Kaj je dejanje?
  2. Obdelava dejanja na strežniku
  3. Obrazci
  4. Potrditev pred dejanjem
  5. Obdelava dejanja v brskalniku
  6. Stanja nalaganja
  7. Ključne ugotovitve

Lekcija ponovno napisana 3. novembra 2026. Prejšnja različica je obravnavala klike v komponentah React po meri in si izmislila „dejanja predlogov”. V ChatKitu je dejanje objekt, pripet komponenti gradnika (gumb, vrstica seznama, obrazec). Privzeto se obdela na vašem strežniku v metodi action razreda ChatKitServer ali v brskalniku, če določite drugače. Ta lekcija sledi vodniku Actions in ChatKit in SDK openai-chatkit različice 1.6.5. Strežnik, predloge in obrazec so bili zagnani lokalno; koda React je bila preverjena s kompilacijo. Viri: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Kaj je dejanje?

Gradnik, ki le prikazuje vsebino, je zgolj lep odgovor. Dejanja ga naredijo uporabnega: klik na „Prekliči naročilo”, izbor vrstice v seznamu ali oddaja obrazca sproži obdelavo brez potrebe, da bi uporabnik vtipkal sporočilo. ChatKit pošlje dejanje na vaš strežnik, ki lahko deluje na vaših sistemih, posodobi gradnik, doda odgovor v nit ali ponovno zažene agenta.

Dejanje deklarirate v predlogi gradnika na komponenti, ki ga sprejme (onClickAction za Button ali ListViewItem, onChangeAction za Select, onSubmitAction za Form, confirm in cancel za Card). Gre za majhen objekt JSON:

PoljeVloga
typeIme dejanja, ki ga vaša koda preverja: "order.cancel"
payloadUporabni podatki: {"number": "C-42"}
handler"server" (privzeto) ali "client" za obdelavo v brskalniku
loadingBehaviorStanje nalaganja, prikazano med obdelavo (glej spodaj)

Obdelava dejanja na strežniku

Vzemimo kartico naročila, ki ponuja preklic. Predloga deklarira dejanje na gumbih za potrditev in preklic komponente 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 strani strežnika dodajte metodo action svojemu razredu ChatKitServer. Ta prejme nit, dejanje, gradnik, ki ga je sprožil (sender), in vaš kontekst ter vrne dogodke, kot je 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(...) : kot v lekciji 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 prihaja iz brskalnika: ponovno preverite dovoljenja
            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)
            # Sled za model, nikoli prikazano uporabniku
            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.")

Iz te kode izhajajo tri pravila:

  • Payload ni zaupanja vreden. Prispe iz brskalnika, kjer ga lahko kdorkoli spremeni: vodnik OpenAI zahteva obravnavo kot nepreverjenih podatkov. Pred preklicem strežnik preveri, ali naročilo pripada avtenticiranemu uporabniku. user_id v kontekstu je tisti, ki ga tam postavi vaša avtenticirana končna točka (lekcija 21).
  • Model mora vedeti, kaj se je zgodilo. Klik ni sporočilo: brez sledi bi agent v naslednjem koraku ignoriral, da je naročilo preklicano. HiddenContextItem doda te informacije v nit, ne da bi jih prikazal. SDK samodejno beleži le elemente za oddajanje, skriti element pa se nikoli ne sme oddajati: dodati ga morate sami v shrambo (store).
  • Odgovor je tok dogodkov. Tukaj preprosto sporočilo; lahko bi bil posodobljen gradnik, oddan s stream_widget, kot v prejšnji lekciji.

Če želite, da agent komentira pravkar dogodivščino, ga po dejanju ponovno zaženite: async for event in self.respond(thread, None, context): yield event. Vaša metoda respond ponovno prebere nit, najde skriti element in ustrezno odgovori.

Obrazci

Ko so vnosna polja (Input, Textarea, Select, Checkbox, DatePicker…) postavljena znotraj Form, se njihove vrednosti dodajo v payload kateregakoli dejanja, sproženega iz tega obrazca, pod imenom vsakega polja:

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

Ob oddaji action.payload vsebuje source, order, category in detail. Ime s piko, "client.name", ustvari gnezdeno vrednost: payload["client"]["name"]. Če se ime polja ujema s ključem, ki je že prisoten v payloadu, se vrednost polja ignorira in ChatKit odda dogodek napake: izberite različna imena.

Veljavnost obrazca se preverja na strani brskalnika: required in pattern blokirata oddajo, dokler je polje neveljavno. To je udobje za uporabnika, ne zaščita: ponovno preverite na strežniku, na primer z modelom 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 metodi 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.")

Za bogatejše preverjanje veljavnosti z prilagojenimi sporočili o napakah dokumentacija svetuje premik zunaj gradnika: dejanje na strani odpre okno v vaši aplikaciji, rezultat pa se vrne v ChatKit prek sendCustomAction. Upoštevajte tudi, da se Card, deklariran z "asForm": true, obnaša kot obrazec: njegova polja so validirana in posredovana njegovemu dejanju confirm.

Potrditev pred dejanjem

Kartica za preklic na začetku ponazarja pravilo, ki ga je treba posplošiti: nepovratno ali občutljivo dejanje zahteva izrecno potrditev. Preklic naročila, pošiljanje e-pošte, povračilo, brisanje: agent predlaga, uporabnik potrdi na kartici, ki jasno navaja, kaj se bo zgodilo, izvršitev pa opravi vaš strežnik, ne model, in sicer po ponovnem preverjanju dovoljenj. Gumba confirm in cancel komponente Card sta namenjena prav temu. Njuno privzeto stanje nalaganja osivi celotno kartico med obdelavo, kar preprečuje dvojne klike.

Obdelava dejanja v brskalniku

Nekatera dejanja na strežniku nimajo kaj opraviti: odpiranje strani v vaši aplikaciji, kopiranje povezave, prikaz modalnega okna. Deklarirajte jih z "handler": "client" v predlogi, na primer {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Nato prispejo v možnost widgets.onAction vmesnika:

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');
          // Obvesti strežnik, ki lahko posodobi gradnik
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction pošlje dejanje na vaš strežnik, kot da bi prišlo iz gradnika. Deluje tudi zunaj ChatKita: gumb na vaši strani lahko pokliče chatkit.sendCustomAction({ type: 'cart.empty' }), tako da asistent reagira na dogodke drugje v aplikaciji.

Stanja nalaganja

loadingBehavior nadzira, kaj uporabnik vidi med obdelavo dejanja:

VrednostUčinek
auto (privzeto)Prilagodi se komponenti: samo gumb za Button, nič za Select, celotna kartica za confirm komponente Card
selfStanje nalaganja na posamezni komponenti, ki ima dejanje
containerCeloten gradnik zbledi in postane neaktiven
noneBrez stanja nalaganja

Dokumentacija priporoča ohranjanje vrednosti auto, razen če imate specifično potrebo. Privzeto so dejanja na gradniku blokirana tudi med pretakanjem odgovora, da se preprečijo konflikti. Od različice SDK 1.6.2 dalje dejanje, deklarirano z "streaming": false, obide to blokado: obdela ga metoda sync_action strežnika, rezervirana za dejanja, ki le posodabljajo svoj lasten gradnik ali delujejo zunaj niti.

Ključne ugotovitve

  • Dejanje je objekt {type, payload, handler, loadingBehavior}, pripet komponenti gradnika; sproži obdelavo brez uporabniškega sporočila
  • Na strežniku metoda action razreda ChatKitServer prejme dejanje in vrne dogodke: sporočilo, posodobljen gradnik ali nov odgovor agenta prek respond
  • Payload prihaja iz brskalnika: ponovno preverite dovoljenja in podatke na strežniku (Pydantic), tudi če obrazec že validira required in pattern
  • HiddenContextItem, ročno dodan v shrambo, obvesti model o uporabnikovem dejanju
  • Občutljiva dejanja gredo skozi potrditveno kartico; čisto lokalna dejanja se obdelajo v brskalniku (handler: "client", widgets.onAction, sendCustomAction)