Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Veiksmai, kuriuos atlieka naudotojas

Paskaita 20 iš 25 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Kas yra veiksmas?
  2. Veiksmo apdorojimas serveryje
  3. Formos
  4. Patvirtinimas prieš veiksmą
  5. Veiksmo apdorojimas naršyklėje
  6. Krovinio būsenos
  7. Svarbiausi punktai

Pamoka perrašyta 2026 m. lapkričio 3 d. Ankstesnė versija apdorojo paspaudimus individualiuose „React“ komponentuose ir sugalvojo „pasiūlymų veiksmus“. „ChatKit“ sistemoje veiksmas yra objektas, prijungtas prie valdiklio komponento (mygtuko, sąrašo eilutės, formos). Pagal nutylėjimą jis apdorojamas jūsų serveryje, naudojant action metodą klasėje ChatKitServer, arba naršyklėje, jei nurodote kitaip. Ši pamoka remiasi Actions in ChatKit vadovu ir openai-chatkit SDK 1.6.5 versija. Serveris, šablonai ir forma buvo paleisti lokaliai; „React“ kodas patikrintas kompiliuojant. Šaltiniai: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Kas yra veiksmas?

Valdiklis, kuris tik rodo turinį, yra tiesiog gražus atsakymas. Veiksmai suteikia jam naudingojo krūvio: paspaudus „Atšaukti užsakymą“, pasirinkus eilutę sąraše arba pateikus formą, inicijuojamas apdorojimas nespausdinant naudotojui jokio pranešimo. „ChatKit“ išsiunčia veiksmą į jūsų serverį, kuris gali atlikti operacijas jūsų sistemose, atnaujinti valdiklį, pridėti atsakymą į giją arba paleisti agentą iš naujo.

Veiksmą deklaruojate valdiklio šablone komponentui, kuris jį priima (onClickAction komponentams Button arba ListViewItem, onChangeAction – Select, onSubmitAction – Form, confirm ir cancel – Card). Tai mažas JSON objektas:

LaukasVaidmuo
typeVeiksmo pavadinimas, kurį tikrina jūsų kodas: "order.cancel"
payloadNaudingi duomenys: {"number": "C-42"}
handler"server" (pagal nutylėjimą) arba "client" apdorojimui naršyklėje
loadingBehaviorKrovinio būsena, rodoma apdorojimo metu (žr. toliau)

Veiksmo apdorojimas serveryje

Paimkime užsakymo kortelę, siūlančią atšaukimą. Šablone veiksmas deklaruojamas ant Card komponento patvirtinimo ir atšaukimo mygtukų:

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

Serverio pusėje pridėkite metodą action savo ChatKitServer klasei. Jis gauna giją, veiksmą, valdiklį, kuris jį išsiuntė (sender), ir jūsų kontekstą, o grąžina įvykius, pavyzdžiui, 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(...) : kaip 17 pamokoje

    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 ateina iš naršyklės: iš naujo patikrinkite leidimus
            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)
            # Pėdsakas modeliui, niekada nerodomas naudotojui
            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.")

Iš šio kodo išplaukia trys taisyklės:

  • Payload yra nepatikimas. Jis ateina iš naršyklės, kur bet kas gali jį pakeisti: „OpenAI“ gidas reikalauja laikyti jį nepatvirtintais duomenimis. Prieš atšaukdami serveris patikrina, ar užsakymas priklauso autentifikaciją atlikusiam naudotojui. Kontekste esantis user_id yra tas, kurį jūsų autentifikacijos galinis taškas ten įdeda (21 pamoka).
  • Modelis turi žinoti, kas įvyko. Paspaudimas nėra žinutė: be pėdsako agentas kitame etape ignoruotų tai, kad užsakymas atšauktas. HiddenContextItem prideda šią informaciją į giją jos nerodydamas. SDK automatiškai įrašo tik transliuojamus elementus, o paslėptas elementas niekada neturi būti transliuojamas: turite jį patys pridėti į saugyklą (store).
  • Atsakymas yra įvykių srautas. Čia tai paprasta žinutė; tai galėtų būti atnaujintas valdiklis, transliuojamas naudojant stream_widget, kaip ir ankstesnėje pamokoje.

Jei norite, kad agentas pakomentuotų ką tik įvykusį veiksmą, paleiskite jį iš naujo po veiksmo: async for event in self.respond(thread, None, context): yield event. Jūsų metodas respond iš naujo nuskaitys giją, ras paslėptą elementą ir atsakys atitinkamai.

Formos

Kai įvesties laukai (Input, Textarea, Select, Checkbox, DatePicker…) patalpinami į Form, jų reikšmės pridedamos prie bet kokio veiksmo, išsiųsto iš tos formos, payload, pagal kiekvieno lauko pavadinimą:

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

Pateikus formą, action.payload contient source, order, category ir detail. Taškinis pavadinimas, pavyzdžiui, "client.name", sukuria įdėtą reikšmę: payload["client"]["name"]. Jei lauko pavadinimas sutampa su jau esamu raktu payload’e, lauko reikšmė ignoruojama ir „ChatKit“ išmeta klaidos įvykį: rinkitės unikalius pavadinimus.

Formos validavimas vyksta naršyklės pusėje: required ir pattern blokuoja pateikimą, kol laukas yra neteisingas. Tai naudotojo patogumas, o ne apsauga: iš naujo patikrinkite serveryje, pavyzdžiui, naudodami „Pydantic“ modelį.

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)


# Veiksmo metode
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.")

Sudėtingesniam validavimui su individualiomis klaidų žinutėmis dokumentacija rekomenduoja išeiti už valdiklio ribų: kliento pusės veiksmas atidaro langą jūsų programoje, o rezultatas grąžinamas į „ChatKit“ per sendCustomAction. Taip pat noteikite, kad Card, deklaruotas su "asForm": true, elgiasi kaip forma: jo laukai validuojami ir perduodami jo confirm veiksmui.

Patvirtinimas prieš veiksmą

Atšaukimo kortelė pamokos pradžioje iliustruoja taisyklę, kurią verta taikyti plačiau: negrįžtamas arba jautrus veiksmas reikalauja aiškaus patvirtinimo. Užsakymo atšaukimas, el. laiško siuntimas, pinigų grąžinimas, trynimas: agentas siūlo, naudotojas patvirtina kortelėje, kurioje aiškiai nurodyta, kas nutiks, o vykdo tai jūsų serveris, o ne modelis, dar kartą patikrinęs leidimus. Tam skirti Card mygtukai confirm ir cancel. Jų numatytoji krovinio būsena pilkai nuspalvina visą kortelę apdorojimo metu, taip užkertant kelią dvigubiems paspaudimams.

Veiksmo apdorojimas naršyklėje

Kai kuriems veiksmams serveris nereikalingas: puslapio atidarymas jūsų programoje, nuorodos nukopijavimas, modalinio lango rodymas. Deklaruokite juos šablone su "handler": "client", pavyzdžiui, {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Tuomet jie patenka į sąsajos parinktį widgets.onAction:

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');
          // Informuokite serverį, kuris gali atnaujinti valdiklį
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction išsiunčia veiksmą į jūsų serverį taip, lyg jis būtų atėjęs iš valdiklio. Tai veikia ir už „ChatKit“ ribų: jūsų puslapio mygtukas gali iškviesti chatkit.sendCustomAction({ type: 'cart.empty' }), kad asistentas sureaguotų į tai, kas vyksta kitur programoje.

Krovinio būsenos

loadingBehavior valdo, ką naudotojas mato veiksmo apdorojimo metu:

ReikšmėPoveikis
auto (pagal nutylėjimą)Prisitaiko prie komponento: tik mygtukas Button atveju, nieko Select atveju, visa kortelė Card confirm atveju
selfKrovinio būsena tik tame komponente, kuris turi veiksmą
containerVisas valdiklis išblunka ir tampa neaktyvus
noneJokia krovinio būsena nerodoma

Dokumentacija rekomenduoja palikti auto, nebent turite specifinį poreikį. Pagal nutylėjimą veiksmai valdiklyje taip pat blokuojami, kol transliuojamas atsakymas, siekiant išvengti konfliktų. Nuo SDK 1.6.2 versijos veiksmas, deklaruotas su "streaming": false, apeina šį blokavimą: jį apdoroja serverio metodas sync_action, skirtas veiksmams, kurie tik atnaujina savo valdiklį arba veikia už gijos ribų.

Svarbiausi punktai

  • Veiksmas yra objektas {type, payload, handler, loadingBehavior}, prijungtas prie valdiklio komponento; jis inicijuoja apdorojimą be naudotojo žinutės
  • Serveryje ChatKitServer metodas action jį gauna ir grąžina įvykius: žinutę, atnaujintą valdiklį arba naują agento atsakymą per respond
  • Payload ateina iš naršyklės: iš naujo patikrinkite leidimus ir duomenis serveryje („Pydantic“), net jei forma jau validavo required ir pattern
  • HiddenContextItem, rankiniu būdu pridėtas į saugyklą (store), informuoja modelį apie naudotojo atliktus veiksmus
  • Jautrūs veiksmai eina per patvirtinimo kortelę; gryni lokaliniai veiksmai apdorojami naršyklėje (handler: "client", widgets.onAction, sendCustomAction)