Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Kasutaja tegevused

Õppetund 20 / 25 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Mis on tegevus?
  2. Tegevuse töötlemine serveris
  3. Vormid
  4. Kinnita enne tegutsemist
  5. Tegevuse töötlemine brauseris
  6. Laadimisolekud
  7. Peamised punktid

Õppetund kirjutati ümber 3. novembril 2026. Eelmine versioon käsitles klõpse kohandatud Reacti komponentides ja leiutas „soovitustegevused“. ChatKitis on tegevus (action) objekt, mis on seotud vidina komponendiga (nupp, loendiread, vorm). Vaikimisi töödeldakse seda sinu serveris ChatKitServer meetodis action või brauseris, kui määrad teisiti. See õppetund järgib juhendit Actions in ChatKit ja SDK openai-chatkit versiooni 1.6.5. Serverit, malle ja vormi käivitati lokaalselt; Reacti koodi kontrolliti kompileerimisega. Allikad: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Mis on tegevus?

Vidin, mis ainult kuvab sisu, on lihtalt ilus vastus. Tegevused muudavad selle kasulikuks: klõpsates „Tühista tellimus“, valides rea loendis või esitades vormi, käivitub töötlemine ilma et kasutaja peaks sõnumit trükkima. ChatKit saadab tegevuse sinu serverisse, mis saab tegutseda sinu süsteemides, uuendada vidinat, lisada vastuse lõimesse või taaskäivitada agenti.

Deklareerid tegevuse vidina mallis komponendil, mis seda aktsepteerib (onClickAction Button või ListViewItem jaoks, onChangeAction Select jaoks, onSubmitAction Form jaoks, confirm ja cancel Card jaoks). See on väike JSON-objekt:

VäliRoll
typeTegevuse nimi, mida sinu kood testib: "order.cancel"
payloadKasulikud andmed: {"number": "C-42"}
handler"server" (vaikimisi) või "client" selle töötlemiseks brauseris
loadingBehaviorLaadimisolek, mida kuvatakse töötlemise ajal (vt allpool)

Tegevuse töötlemine serveris

Võtame näiteks tellimuse kaardi, mis pakub tühistamist. Mall deklareerib tegevuse Card kinnitamise ja tühistamise nuppudel:

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

Serveri poolel lisa oma ChatKitServer klassile meetod action. See saab lõime, tegevuse, seda väljastanud vidina (sender) ja sinu konteksti ning tagastab sündmusi nagu 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(...) : nagu õppetunnis 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 tuleb brauserist: kontrolli õigused uuesti üle
            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)
            # Jälg mudelile, mida kasutajale kunagi ei näidata
            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.")

Sellest koodist tulenevad kolm reeglit:

  • Payload ei ole usaldusväärne. See saabub brauserist, kus igaüks saab seda muuta: OpenAI juhend nõuab selle käsitlemist kontrollimata andmetena. Enne tühistamist kontrollib server, kas tellimus kuulub autentitud kasutajale. Kontekstis olev user_id on see, mille sinu autentitud lõpp-punkt sinna paigutas (õppetund 21).
  • Mudel peab teadma, mis juhtus. Klõps ei ole sõnum: ilma jäljeta eiraks agent järgmises voorus fakti, et tellimus on tühistatud. HiddenContextItem lisab selle info lõimesse, ilma et seda kuvataks. SDK salvestab automaatselt ainult edastatavad elemendid ja peidetud elementi ei tohi kunagi edastada: pead selle ise poodi (store) lisama.
  • Vastus on sündmuste voog. Siin lihtne sõnum; see võiks olla uuendatud vidin, edastatud stream_widget abil nagu eelmises õppetunnis.

Et agent kommenteeriks just juhtunut, taaskäivita see pärast tegevust: async for event in self.respond(thread, None, context): yield event. Sinu respond meetod loeb lõime uuesti, leiab peidetud elemendi ja vastab vastavalt.

Vormid

Kui sisendväljad (Input, Textarea, Select, Checkbox, DatePicker…) asetatakse Form sisse, lisatakse nende väärtused sellest vormist väljuva mis tahes tegevuse payloadisse iga välja nime all:

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

Esitamisel sisaldab action.payload välju source, order, category ja detail. Punktierega nimi, näiteks "client.name", tekitab pesastatud väärtuse: payload["client"]["name"]. Kui välja nimi põrkub juba payloadis oleva võtmega, ignoreeritakse välja väärtust ja ChatKit edastab veasündmuse: vali unikaalsed nimed.

Vormi valideerimine toimub brauseri poolel: required ja pattern blokeerivad esitamise, kui väli on vigane. See on kasutaja mugavus, mitte kaitse: valideeri uuesti serveris, näiteks Pydantic mudeliga.

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)


# Tegevuse meetodis
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.")

Rikkalikumaks valideerimiseks koos kohandatud veateadetega soovitab dokumentatsioon liikuda vidinast välja: kliendipoolne tegevus avab akna sinu rakenduses ja tulemus naaseb ChatKiti kaudu sendCustomAction. Pane tähele ka, et "asForm": true deklareeritud Card käitub nagu vorm: selle väljad valideeritakse ja edastatakse selle confirm tegevusele.

Kinnita enne tegutsemist

Alguses olev tühistamiskaart illustreerib üldistatavat reeglit: pööramatu või tundlik tegevus nõuab selget kinnitust. Tellimuse tühistamine, e-kirja saatmine, tagasimakse, kustutamine: agent teeb ettepaneku, kasutaja kinnitab kaardil, mis selgitab üheselt, mis juhtub, ja sinu server, mitte mudel, viib selle täide pärast õiguste uuesti kontrollimist. Card nupud confirm ja cancel on selleks mõeldud. Nende vaikimisi laadimisolek muudab kogu kaardi töötlemise ajaks halliks, mis takistab topeltklõpse.

Tegevuse töötlemine brauseris

Mõnel tegevusel pole serveris midagi teha: lehe avamine sinu rakenduses, lingi kopeerimine, modaali kuvamine. Deklareeri need mallis "handler": "client" abil, näiteks {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Need jõuavad liidese valikusse 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');
          // Teavita serverit, mis saab vidinat uuendada
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction saadab tegevuse sinu serverisse nii, nagu see oleks pärit vidinast. See toimib ka väljaspool ChatKiti: nupp sinu lehel saab kutsuda chatkit.sendCustomAction({ type: 'cart.empty' }), nii et assistent reageerib sellele, mis toimub mujal rakenduses.

Laadimisolekud

loadingBehavior juhib seda, mida kasutaja näeb tegevuse töötlemise ajal:

VäärtusMõju
auto (vaikimisi)Kohandub komponendiga: ainult nupp Button jaoks, mitte midagi Select jaoks, kogu kaart Card kinnitamise jaoks
selfLaadimisolek ainult sellel üksikul komponendil, millel tegevus on
containerKogu vidin tuhmub ja muutub inaktiivseks
noneLaadimisolekut pole

Dokumentatsioon soovitab hoida auto, välja arvatud kui sul on erivajadus. Vaikimisi blokeeritakse vidina tegevused ka vastuse voogedastuse ajal, et vältida konflikte. Alates SDK versioonist 1.6.2 möödub "streaming": false deklareeritud tegevus sellest blokeerimisest: seda töötleb serveri meetod sync_action, mis on reserveeritud tegevustele, mis ainult uuendavad oma vidinat või tegutsevad väljaspool lõimet.

Peamised punktid

  • Tegevus on objekt {type, payload, handler, loadingBehavior}, mis on seotud vidina komponendiga; see käivitab töötlemise ilma kasutaja sõnumita
  • Serveris võtab ChatKitServer meetod action selle vastu ja tagastab sündmusi: sõnum, uuendatud vidin või uus agenti vastus läbi respond
  • Payload tuleb brauserist: kontrolli serveris uuesti üle õigused ja andmed (Pydantic), isegi kui vorm on juba valideerinud required ja pattern
  • HiddenContextItem, mis on käsitsi lisatud poodi (store), teavitab mudelit sellest, mida kasutaja tegi
  • Tundlikud tegevused läbivad kinnitamiskaardi; puhtalt lokaalsed tegevused töödeldakse brauseris (handler: "client", widgets.onAction, sendCustomAction)