Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Felhasználói műveletek

20. lecke 25 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Mi az a művelet?
  2. Művelet feldolgozása a szerveren
  3. Űrlapok
  4. Megerősítés a cselekvés előtt
  5. Művelet feldolgozása a böngészőben
  6. Betöltési állapotok
  7. Főbb megállapítások

A leckét 2026. november 3-án írtuk át. Az előző verzió egyedi React-komponensek kattintásait kezelte, és kitalált „javaslati műveleteket“ talált ki. A ChatKitben a művelet (action) egy objektum, amelyet egy widget-komponenshez (gomb, listasor, űrlap) csatolunk. Alapértelmezés szerint a szervered dolgozza fel a ChatKitServer osztály action metódusában, hacsak másképp nem rendelkezel. Ez a lecke az Actions in ChatKit útmutatót és az openai-chatkit SDK 1.6.5-ös verzióját követi. A szervert, a sablonokat és az űrlapot helyben futtattuk; a React-kódot fordítással ellenőriztük. Források: Actions in ChatKit · Interaktív válaszok létrehozása widgetekkel · Python SDK 1.6.2 kiadási jegyzetek.

Mi az a művelet?

Egy widget, amely csak tartalmat jelenít meg, csupán egy szép válasz. A műveletek teszik hasznossá: a „Rendelés lemondása“ gombra kattintás, egy sor kiválasztása egy listában vagy egy űrlap beküldése feldolgozást indít el anélkül, hogy a felhasználónak üzenetet kellene gépelnie. A ChatKit elküldi a műveletet a szerverednek, amely aztán beavatkozhat a rendszereidbe, frissítheti a widgetet, választ adhat a beszélgetésfolyamhoz, vagy újraindíthatja az ágenst.

A műveletet a widget sablonjában deklarálod egy olyan komponensen, amely elfogad ilyet (onClickAction egy Button vagy ListViewItem esetén, onChangeAction egy Select esetén, onSubmitAction egy Form esetén, confirm és cancel egy Card esetén). Ez egy kis JSON-objektum:

MezőSzerep
typeA művelet neve, amelyet a kódod tesztel: "order.cancel"
payloadHasznos adatok: {"number": "C-42"}
handler"server" (alapértelmezett) vagy "client" a böngészőben történő feldolgozáshoz
loadingBehaviorA feldolgozás alatt megjelenített betöltési állapot (lásd lentebb)

Művelet feldolgozása a szerveren

Vegyük példának a rendelés lemondását felajánló kártyát. A sablon deklarálja a műveletet a Card megerősítő és lemondó gombjain:

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

A szerveroldalon adj hozzá egy action metódust a ChatKitServer osztályodhoz. Ez megkapja a beszélgetésfolyamot (thread), a műveletet, a kibocsátó widgetet (sender) és a kontextust, majd eseményeket ad vissza, mint például a 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(...) : mint a 17. leckében

    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", ""))
            # A payload a böngészőből érkezik: ellenőrizd újra a jogosultságokat
            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)
            # Napló a modell számára, soha nem jelenik meg a felhasználónak
            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.")

Ebből a kódból három szabály következik:

  • A payload nem megbízható. A böngészőből érkezik, ahol bárki módosíthatja: az OpenAI útmutató előírja, hogy ellenőrizetlen adatként kezeljük. A lemondás előtt a szerver ellenőrzi, hogy a rendelés a hitelesített felhasználóhoz tartozik-e. A kontextusban lévő user_id az, amelyet a hitelesített végpontod helyez el ott (21. lecke).
  • A modellnek tudnia kell, mi történt. Egy kattintás nem üzenet: napló nélkül az ágens a következő körben figyelmen kívül hagyná, hogy a rendelés lemondásra került. Egy HiddenContextItem hozzáadja ezt az információt a beszélgetésfolyamhoz anélkül, hogy megjelenítené. Az SDK automatikusan csak a közvetített (broadcast) elemeket rögzíti, és egy rejtett elemet soha nem szabad közvetíteni: neked kell manuálisan hozzáadnod a tárolóhoz (store).
  • A válasz események folyamata. Itt egy egyszerű üzenet; lehetne ez egy frissített widget is, amelyet a stream_widget segítségével közvetítesz, ahogy az előző leckében láttuk.

Ha azt szeretnéd, hogy az ágens kommentálja az imént történteket, indítsd újra a művelet után: async for event in self.respond(thread, None, context): yield event. A respond metódusod újraolvassa a beszélgetésfolyamot, megtalálja a rejtett elemet, és ennek megfelelően válaszol.

Űrlapok

Amikor beviteli mezőket (Input, Textarea, Select, Checkbox, DatePicker…) helyezel egy Form belsejébe, azok értékei hozzáadódnak bármely, az adott űrlapból kibocsátott művelet payloadjához, minden mező neve alatt:

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

Beküldéskor az action.payload tartalmazni fogja a source, order, category és detail értékeket. Egy pontozott név, például "client.name", beágyazott értéket hoz létre: payload["client"]["name"]. Ha egy mezőnév ütközik a payloadban már jelen lévő kulccsal, a mező értéke figyelmen kívül marad, és a ChatKit hibaeseményt bocsát ki: válassz egyedi neveket.

Az űrlap validálása böngészőoldalon történik: a required és a pattern blokkolja a beküldést, amíg egy mező érvénytelen. Ez a felhasználói kényelmet szolgálja, nem védelmet nyújt: validáld újra a szerveren, például egy Pydantic modell segítségével.

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)


# Az action metódusban
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.")

Bővebb validáláshoz, egyedi hibaüzenetekkel, a dokumentáció azt javasolja, hogy lépj ki a widget kereteiből: egy kliensoldali művelet ablakot nyit meg az alkalmazásodban, és az eredmény a sendCustomAction segítségével tér vissza a ChatKithez. Vegyed figyelembe azt is, hogy egy "asForm": true attribútummal deklarált Card űrlapként viselkedik: a mezői validálva lesznek, és átadódnak a confirm műveletének.

Megerősítés a cselekvés előtt

A lecke elején szereplő lemondási kártya egy általánosítható szabályt illusztrál: a visszafordíthatatlan vagy érzékeny műveletekhez kifejezett megerősítés szükséges. Rendelés lemondása, e-mail küldése, visszatérítés, törlés: az ágens javaslatot tesz, a felhasználó egy kártyán érvényesíti a döntést, amely egyértelműen közli, mi fog történni, és a szervered – nem a modell – hajtja végre a műveletet a jogosultságok újbóli ellenőrzése után. Erre valók a Card confirm és cancel gombjai. Alapértelmezett betöltési állapotuk a teljes kártyát szürkére váltja a feldolgozás alatt, ami megakadályozza a dupla kattintást.

Művelet feldolgozása a böngészőben

Egyes műveleteknek nincs teendőjük a szerveren: egy oldal megnyitása az alkalmazásodban, egy link másolása, egy modális ablak megjelenítése. Deklaráld őket "handler": "client" értékkel a sablonban, például így: {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Ezek ezután az interfész widgets.onAction opciójában érkeznek meg:

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');
          // Értesítsd a szervert, amely frissítheti a widgetet
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

A sendCustomAction egy műveletet küld a szerverednek, mintha egy widgetből érkezett volna. A ChatKiten kívül is működik: az oldaladon lévő gomb hívhatja a chatkit.sendCustomAction({ type: 'cart.empty' }) függvényt, így az asszisztens reagálhat arra, ami az alkalmazás más részein történik.

Betöltési állapotok

A loadingBehavior vezérli, mit lát a felhasználó egy művelet feldolgozása közben:

ÉrtékHatás
auto (alapértelmezett)A komponenshez igazodik: csak a gomb egy Button esetén, semmi egy Select esetén, a teljes kártya egy Card confirm gombja esetén
selfBetöltési állapot azon az egyetlen komponensen, amelyhez a művelet tartozik
containerA teljes widget elhalványul és inaktívvá válik
noneNincs betöltési állapot

A dokumentáció az auto megtartását javasolja, hacsak nincs konkrét igényed. Alapértelmezés szerint a widgeten lévő műveletek blokkolva vannak válasz streamelése közben is, az ütközések elkerülése érdekében. Az SDK 1.6.2-es verziója óta egy "streaming": false attribútummal deklarált művelet megkerüli ezt a blokkolást: ilyenkor a szerver sync_action metódusa dolgozza fel, amely csak olyan műveletek számára fenntartott, amelyek csak a saját widgetjüket frissítik, vagy a beszélgetésfolyamon kívül hatnak.

Főbb megállapítások

  • A művelet egy {type, payload, handler, loadingBehavior} objektum, amelyet egy widget-komponenshez csatolunk; felhasználói üzenet nélkül indít feldolgozást
  • A szerveren a ChatKitServer action metódusa fogadja, és eseményeket ad vissza: üzenetet, frissített widgetet vagy új ágensválaszt a respond segítségével
  • A payload a böngészőből érkezik: ellenőrizd újra a jogosultságokat és az adatokat a szerveren (Pydantic), még akkor is, ha az űrlap már validálta a required és pattern feltételeket
  • Egy HiddenContextItem, amelyet manuálisan adsz hozzá a tárolóhoz (store), tájékoztatja a modellt a felhasználó cselekedetéről
  • Az érzékeny műveletek megerősítő kártyán keresztül futnak; a tisztán helyi műveleteket a böngésző dolgozza fel (handler: "client", widgets.onAction, sendCustomAction)