Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Darbības, ko veic lietotājs

Nodarbība 20 no 25 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Kas ir darbība?
  2. Darbības apstrāde serverī
  3. Veidlapas
  4. Apstiprināšana pirms darbības
  5. Darbības apstrāde pārlūkprogrammā
  6. Ielādes stāvokļi
  7. Galvenās atziņas

Nodarbība pārrakstīta 2026. gada 3. novembrī. Iepriekšējā versija apstrādāja klikšķus pielāgotajos React komponentos un izgudroja „ieteikumu darbības”. ChatKit vidē darbība ir objekts, kas pievienots logrīka komponentam (poga, saraksta rinda, veidlapa). Pēc noklusējuma tā tiek apstrādāta tavo serverī, izmantojot action metodi klasē ChatKitServer, vai pārlūkprogrammā, ja norādi citādi. Šī nodarbība seko rokasgrāmatai Actions in ChatKit un openai-chatkit SDK 1.6.5. versijai. Serveris, veidnes un veidlapas tika palaistas lokāli; React kods tika pārbaudīts, kompilējot. Avoti: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Kas ir darbība?

Logrīks, kas tikai attēlo saturu, ir tikai skaista atbilde. Darbības padara to noderīgu: noklikšķinot uz „Atcelt pasūtījumu”, izvēloties rindu sarakstā vai iesniedzot veidlapu, tiek uzsākta apstrāde, nelietotājam neko nerakstot. ChatKit nosūta darbību tavam serverim, kas var veikt darbības tavās sistēmās, atjaunināt logrīku, pievienot atbildi pavedienam vai restartēt aģentu.

Tu deklarē darbību logrīka veidnē komponentam, kas to pieņem (onClickAction priekš Button vai ListViewItem, onChangeAction priekš Select, onSubmitAction priekš Form, confirm un cancel priekš Card). Tas ir neliels JSON objekts:

LauksLoma
typeDarbības nosaukums, ko pārbauda tavs kods: "order.cancel"
payloadNoderīgi dati: {"number": "C-42"}
handler"server" (pēc noklusējuma) vai "client", lai apstrādātu to pārlūkprogrammā
loadingBehaviorIelādes stāvoklis, kas tiek rādīts apstrādes laikā (skatīt zemāk)

Darbības apstrāde serverī

Paņemsim pasūtījuma karti, kas piedāvā atcelšanu. Veidnē darbība tiek deklarēta kartes Card apstiprināšanas un atcelšanas pogām:

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

Servera pusē pievieno action metodi savai ChatKitServer klasei. Tā saņem pavedienu, darbību, logrīku, kas to ģenerēja (sender), un tavu kontekstu, un atgriež notikumus, piemēram, 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(...) : kā 17. nodarbībā

    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 nāk no pārlūka: atkārtoti pārbaudi atļaujas
            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)
            # Izsekojamība modelim, nekad nerādīta lietotājam
            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.")

No šī koda izriet trīs likumi:

  • Payload nav uzticams. Tas nonāk no pārlūka, kur jebkurš to var modificēt: OpenAI rokasgrāmata pieprasa uzskatīt to par nepārbaudītiem datiem. Pirms atcelšanas serveris pārbauda, vai pasūtījums pieder autentificētajam lietotājam. user_id kontekstā ir tas, ko tavs autentificētais galapunkts tur ievieto (21. nodarbība).
  • Modelim ir jāzina, kas noticis. Klikšķis nav ziņojums: bez izsekojamības aģents nākamajā solī ignorētu, ka pasūtījums ir atcelts. HiddenContextItem pievieno šo informāciju pavedienam, to nerādot. SDK automātiski ieraksta tikai apraidē esošos elementus, un slēptam elementam nekad nevajadzētu būt apraidē: tev tas pašam ir jāpievieno store.
  • Atbilde ir notikumu straume. Šeit vienkāršs ziņojums; tā varētu būt atjaunināts logrīks, kas tiek pārraidīts ar stream_widget, kā iepriekšējā nodarbībā.

Lai aģents komentētu tikko notikušo, restartē to pēc darbības: async for event in self.respond(thread, None, context): yield event. Tava respond metode atkārtoti nolasa pavedienu, atrod slēpto elementu un atbilstoši reaģē.

Veidlapas

Kad ievades lauki (Input, Textarea, Select, Checkbox, DatePicker…) tiek izvietoti Form ietvaros, to vērtības tiek pievienotas jebkuras no šīs veidlapas ģenerētas darbības payload zem katra lauka nosaukuma:

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

Iesniedzot, action.payload satur source, order, category un detail. Punktotais nosaukums, "client.name", ģenerē ligzdotu vērtību: payload["client"]["name"]. Ja lauka nosaukums sakrīt ar atslēgu, kas jau eksistē payload, lauka vērtība tiek ignorēta un ChatKit ģenerē kļūdas notikumu: izvēlies unikālus nosaukumus.

Veidlapas validācija notiek pārlūkprogrammā: required un pattern bloķē iesniegšanu, kamēr lauks ir nederīgs. Tas ir lietotāja ērtībām, nevis aizsardzībai: atkārtoti validē serverī, piemēram, izmantojot Pydantic modeli.

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)


# action metodē
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.")

Bagātīgākai validācijai ar pielāgotiem kļūdu ziņojumiem dokumentācija iesaka pāriet ārpus logrīka: klienta puses darbība atver logu tavā lietotnē, un rezultāts atgriežas ChatKit, izmantojot sendCustomAction. Ņem vērā arī to, ka Card, kas deklarēts ar "asForm": true, uzvedas kā veidlapa: tās lauki tiek validēti un nodoti tās confirm darbībai.

Apstiprināšana pirms darbības

Atcelšanas karte sākumā ilustrē noteikumu, ko vispārināt: neatgriezeniska vai sensitīva darbība prasa skaidru apstiprinājumu. Pasūtījuma atcelšana, e-pasta sūtīšana, naudas atmaksāšana, dzēšana: aģents ierosina, lietotājs apstiprina kartē, kas skaidri norāda, kas notiks, un tavs serveris, nevis modelis, to izpilda pēc atļauju atkārtotas pārbaudes. Card pogas confirm un cancel ir paredzētas tieši tam. To noklusējuma ielādes stāvoklis pelēko visu karti apstrādes laikā, kas novērš dubultklikšķus.

Darbības apstrāde pārlūkprogrammā

Dažām darbībām serverī nav ko darīt: lapas atvēršana tavā lietotnē, saites kopēšana, modālā loga rādīšana. Deklarē tās ar "handler": "client" veidnē, piemēram, {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Tad tās nonāk saskarnes opcijā 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');
          // Paziņo serverim, kas var atjaunināt logrīku
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction nosūta darbību tavam serverim tā, it kā tā nāktu no logrīka. Tā darbojas arī ārpus ChatKit: tava lapas poga var izsaukt chatkit.sendCustomAction({ type: 'cart.empty' }), lai asistents reaģētu uz notikumiem citur lietotnē.

Ielādes stāvokļi

loadingBehavior kontrolē to, ko lietotājs redz darbības apstrādes laikā:

VērtībaEfekts
auto (pēc noklusējuma)Pielāgojas komponentam: tikai poga priekš Button, nekas priekš Select, visa karte priekš Card confirm
selfIelādes stāvoklis tikai vienam komponentam, kam pieder darbība
containerViss logrīks izbalē un kļūst neaktīvs
noneNav ielādes stāvokļa

Dokumentācija iesaka saglabāt auto, ja vien tev nav specifiskas vajadzības. Pēc noklusējuma darbības logrīkā tiek bloķētas arī tad, kad tiek straumēta atbilde, lai izvairītos no konfliktiem. Kopš SDK 1.6.2. versijas darbība, kas deklarēta ar "streaming": false, apej šo bloķēšanu: to apstrādā servera sync_action metode, kas paredzēta darbībām, kuras tikai atjaunina savu logrīku vai darbojas ārpus pavediena.

Galvenās atziņas

  • Darbība ir objekts {type, payload, handler, loadingBehavior}, kas pievienots logrīka komponentam; tā uzsāk apstrādi bez lietotāja ziņojuma
  • Serverī ChatKitServer metode action to saņem un atgriež notikumus: ziņojumu, atjauninātu logrīku vai jaunu aģenta atbildi, izmantojot respond
  • Payload nāk no pārlūka: atkārtoti pārbaudi atļaujas un datus serverī (Pydantic), pat ja veidlapa jau validē required un pattern
  • HiddenContextItem, kas manuāli pievienots store, informē modeli par lietotāja darbībām
  • Sensitīvas darbības iziet caur apstiprināšanas karti; tīri lokālas darbības tiek apstrādātas pārlūkprogrammā (handler: "client", widgets.onAction, sendCustomAction)