Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Radnje korisnika

Lekcija 20 od 25 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Što je radnja?
  2. Obrada radnje na poslužitelju
  3. Obrasci
  4. Potvrda prije djelovanja
  5. Obrada radnje u pregledniku
  6. Stanja učitavanja
  7. Ključne točke

Lekcija je ponovno napisana 3. studenog 2026. Prethodna verzija obrađivala je klikove u prilagođenim React komponentama i izmislila „prijedložene radnje“. U ChatKitu je radnja objekt povezan s komponentom widgeta (gumb, redak popisa, obrazac). Zadano se obrađuje na tvojem poslužitelju u metodi action klase ChatKitServer, ili u pregledniku ako to drugačije odrediš. Ova lekcija prati vodič Radnje u ChatKitu i SDK openai-chatkit verzije 1.6.5. Poslužitelj, predlošci i obrazac pokrenuti su lokalno; React kod verificiran je kompilacijom. Izvori: Radnje u ChatKitu · Izgradnja interaktivnih odgovora s widgetima · Bilješke o izdanju Python SDK-a 1.6.2.

Što je radnja?

Widget koji samo prikazuje sadržaj samo je lijep odgovor. Radnje ga čine korisnim: klik na „Otkaži narudžbu“, odabir retka u popisu ili slanje obrasca pokreće obradu bez da korisnik mora upisati poruku. ChatKit šalje radnju na tvoj poslužitelj, koji može djelovati na tvojim sustavima, ažurirati widget, dodati odgovor u nit ili ponovno pokrenuti agenta.

Radnju deklariraš u predlošku widgeta na komponenti koja je prihvaća (onClickAction za Button ili ListViewItem, onChangeAction za Select, onSubmitAction za Form, confirm i cancel za Card). To je mali JSON objekt:

PoljeUloga
typeNaziv radnje koji tvoj kod testira: "order.cancel"
payloadKorisni podaci: {"number": "C-42"}
handler"server" (zadano) ili "client" za obradu u pregledniku
loadingBehaviorStanje učitavanja prikazano tijekom obrade (vidi dolje)

Obrada radnje na poslužitelju

Uzmimo karticu narudžbe koja nudi otkazivanje. Predložak deklarira radnju na gumbima za potvrdu i odustajanje 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 poslužitelja dodaj metodu action svojoj klasi ChatKitServer. Ona prima nit, radnju, widget koji ju je emitirao (sender) i tvoj kontekst, te vraća događaje poput 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(...) : kao u 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 dolazi iz preglednika: ponovno provjeri dopuštenja
            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)
            # Trag za model, nikada nije prikazan korisniku
            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 ovog koda proizlaze tri pravila:

  • Payload nije od povjerenja. Dolazi iz preglednika gdje ga bilo tko može modificirati: vodič OpenAI-ja zahtijeva tretiranje kao neprovjerenih podataka. Prije otkazivanja, poslužitelj provjerava pripada li narudžba autentificiranom korisniku. user_id u kontekstu je onaj koji tvoja autentificirana krajnja točka tamo postavlja (lekcija 21).
  • Model mora znati što se dogodilo. Klik nije poruka: bez traga, agent bi u sljedećem koraku ignorirao da je narudžba otkazana. HiddenContextItem dodaje tu informaciju u nit bez da je prikazuje. SDK automatski bilježi samo emitirane elemente, a skriveni element se nikada ne smije emitirati: moraš ga sam dodati u store.
  • Odgovor je tok događaja. Ovdje jednostavna poruka; mogao bi biti ažurirani widget, emitiran s stream_widget kao u prethodnoj lekciji.

Da bi agent komentirao ono što se upravo dogodilo, ponovno ga pokreni nakon radnje: async for event in self.respond(thread, None, context): yield event. Tvoja metoda respond ponovno čita nit, pronalazi skriveni element i odgovara sukladno tome.

Obrasci

Kada se polja za unos (Input, Textarea, Select, Checkbox, DatePicker…) nalaze unutar Form, njihove vrijednosti se dodaju u payload bilo koje radnje emitirane iz tog obrasca, pod imenom svakog 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}
     ]}
  ]
}
"""

Prilikom slanja, action.payload sadrži source, order, category i detail. Točkasti naziv, "client.name", stvara ugniježđenu vrijednost: payload["client"]["name"]. Ako se naziv polja sukobi s ključem koji već postoji u payloadu, vrijednost polja se ignorira i ChatKit emitira događaj pogreške: odaberi jedinstvene nazive.

Validacija obrasca je na strani preglednika: required i pattern blokiraju slanje dok je polje neispravno. To je pogodnost za korisnika, a ne zaštita: ponovno validiraj na poslužitelju, na primjer s Pydantic modelom.

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)


# U 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 bogatiju validaciju s prilagođenim porukama o pogreškama, dokumentacija savjetuje izlazak izvan widgeta: radnja na strani klijenta otvara prozor u tvojoj aplikaciji, a rezultat se vraća u ChatKit putem sendCustomAction. Također imaj na umu da se Card deklariran s "asForm": true ponaša kao obrazac: njegova polja se validiraju i prosljeđuju njegovoj radnji confirm.

Potvrda prije djelovanja

Kartica za otkazivanje s početka ilustrira pravilo koje trebaš generalizirati: nepovratna ili osjetljiva radnja zahtijeva eksplicitnu potvrdu. Otkazivanje narudžbe, slanje e-pošte, povrat novca, brisanje: agent predlaže, korisnik potvrđuje na kartici koja jasno navodi što će se dogoditi, a tvoj poslužitelj, a ne model, izvršava radnju nakon ponovne provjere dopuštenja. Gumbi confirm i cancel komponente Card napravljeni su upravo za to. Njihovo zadano stanje učitavanja posivi cijelu karticu tijekom obrade, što sprječava dvostruke klikove.

Obrada radnje u pregledniku

Neke radnje nemaju što raditi na poslužitelju: otvaranje stranice u tvojoj aplikaciji, kopiranje poveznice, prikaz modalnog prozora. Deklariraj ih s "handler": "client" u predlošku, na primjer {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. One tada stižu u opciju widgets.onAction sučelja:

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');
          // Obavijesti poslužitelj, koji može ažurirati widget
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction šalje radnju na tvoj poslužitelj kao da dolazi od widgeta. Također radi i izvan ChatKita: gumb na tvojoj stranici može pozvati chatkit.sendCustomAction({ type: 'cart.empty' }) kako bi asistent reagirao na ono što se događa drugdje u aplikaciji.

Stanja učitavanja

loadingBehavior kontrolira što korisnik vidi dok se radnja obrađuje:

VrijednostUčinak
auto (zadano)Prilagođava se komponenti: samo gumb za Button, ništa za Select, cijela kartica za confirm od Card
selfStanje učitavanja na pojedinačnoj komponenti koja drži radnju
containerCijeli widget blijedi i postaje neaktivan
noneNema stanja učitavanja

Dokumentacija preporučuje zadržavanje auto, osim ako nemaš specifičnu potrebu. Zadano su radnje na widgetu također blokirane dok odgovor struji, kako bi se izbjegli sukobi. Od verzije SDK-a 1.6.2, radnja deklarirana s "streaming": false zaobilazi ovo blokiranje: obrađuje je metoda sync_action poslužitelja, rezervirana za radnje koje samo ažuriraju vlastiti widget ili djeluju izvan niti.

Ključne točke

  • Radnja je objekt {type, payload, handler, loadingBehavior} povezan s komponentom widgeta; pokreće obradu bez korisničke poruke
  • Na poslužitelju, metoda action klase ChatKitServer prima ju i vraća događaje: poruku, ažurirani widget ili novi odgovor agenta putem respond
  • Payload dolazi iz preglednika: ponovno provjeri dopuštenja i podatke na poslužitelju (Pydantic), čak i kada obrazac već validira required i pattern
  • HiddenContextItem, ručno dodan u store, informira model o tome što je korisnik učinio
  • Osjetljive radnje prolaze kroz karticu za potvrdu; čisto lokalne radnje obrađuju se u pregledniku (handler: "client", widgets.onAction, sendCustomAction)