Salt la conținutul principal
Română— Alege o limbă
Meniu

Acțiuni ale utilizatorului

Lecția 20 din 25 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Ce este o acțiune?
  2. Procesarea unei acțiuni pe server
  3. Formulare
  4. Confirmare înainte de acțiune
  5. Procesarea unei acțiuni în browser
  6. Stări de încărcare
  7. Puncte cheie

Lecție rescrisă la 3 noiembrie 2026. Versiunea anterioară gestiona clicurile în componente React personalizate și inventa „acțiuni de sugestie“. În ChatKit, o acțiune este un obiect atașat unei componente widget (buton, rând de listă, formular). Implicit, aceasta este procesată pe serverul dumneavoastră în metoda action a clasei ChatKitServer, sau în browser dacă specificați altfel. Această lecție urmează ghidul Actions in ChatKit și SDK-ul openai-chatkit versiunea 1.6.5. Serverul, șabloanele și formularul au fost rulate local; codul React a fost verificat prin compilare. Surse: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Ce este o acțiune?

Un widget care afișează doar conținut este doar un răspuns estetic. Acțiunile îl fac util: făcând clic pe „Anulează comanda“, selectând un rând într-o listă sau trimițând un formular, declanșați o procesare fără ca utilizatorul să fie nevoit să tasteze un mesaj. ChatKit trimite acțiunea către serverul dumneavoastră, care poate acționa asupra sistemelor dumneavoastră, poate actualiza widget-ul, poate adăuga un răspuns în firul de conversație sau poate reporni agentul.

Declarați o acțiune în șablonul widget-ului pe o componentă care acceptă una (onClickAction pentru un Button sau ListViewItem, onChangeAction pentru un Select, onSubmitAction pentru un Form, confirm și cancel pentru un Card). Este un mic obiect JSON:

CâmpRol
typeNumele acțiunii pe care codul dumneavoastră o testează: "order.cancel"
payloadDate utile: {"number": "C-42"}
handler"server" (implicit) sau "client" pentru a o procesa în browser
loadingBehaviorStarea de încărcare afișată în timpul procesării (vezi mai jos)

Procesarea unei acțiuni pe server

Să luăm un card de comandă care oferă opțiunea de anulare. Șablonul declară acțiunea pe butoanele de confirmare și anulare ale 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 }}}}}
}
"""

Pe partea de server, adăugați o metodă action în ChatKitServer. Aceasta primește firul de conversație (thread), acțiunea, widget-ul care a emis-o (sender) și contextul dumneavoastră, și returnează evenimente precum 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(...) : ca în lecția 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-ul vine din browser: reverificați permisiunile
            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)
            # O urmă pentru model, niciodată afișată utilizatorului
            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.")

Din acest cod reies trei reguli:

  • Payload-ul nu este de încredere. Acesta provine din browser, unde oricine îl poate modifica: ghidul OpenAI cere tratarea sa ca date neverificate. Înainte de anulare, serverul verifică dacă comanda aparține utilizatorului autentificat. user_id din context este cel pe care endpoint-ul dumneavoastră autentificat îl plasează acolo (lecția 21).
  • Modelul trebuie să știe ce s-a întâmplat. Un clic nu este un mesaj: fără o urmă, agentul ar ignora la următorul tur faptul că comanda a fost anulată. Un HiddenContextItem adaugă această informație în firul de conversație fără a-l afișa. SDK înregistrează automat doar elementele difuzate, iar un element ascuns nu trebuie niciodată difuzat: trebuie să îl adăugați dumneavoastră în store.
  • Răspunsul este un flux de evenimente. Aici un mesaj simplu; ar putea fi un widget actualizat, difuzat cu stream_widget ca în lecția anterioară.

Pentru ca agentul să comenteze ceea ce tocmai s-a întâmplat, reporniți-l după acțiune: async for event in self.respond(thread, None, context): yield event. Metoda dumneavoastră respond recitește firul de conversație, găsește elementul ascuns și răspunde în consecință.

Formulare

Când câmpurile de intrare (Input, Textarea, Select, Checkbox, DatePicker…) sunt plasate în interiorul unui Form, valorile lor sunt adăugate la payload-ul oricărei acțiuni emise din acel formular, sub numele fiecărui câmp:

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

La submit, action.payload conține source, order, category și detail. Un nume punctat, "client.name", produce o valoare imbricată: payload["client"]["name"]. Dacă un nume de câmp intră în conflict cu o cheie deja prezentă în payload, valoarea câmpului este ignorată și ChatKit emite un eveniment de eroare: alegeți nume distincte.

Validarea formularului se face în browser: required și pattern blochează trimiterea cât timp un câmp este invalid. Aceasta este o comoditate pentru utilizator, nu o protecție: revalidați pe server, de exemplu cu un model Pydantic.

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)


# În metoda 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.")

Pentru o validare mai bogată, cu mesaje de eroare personalizate, documentația sfătuiește să ieșiți din widget: o acțiune lato-client deschide o fereastră în aplicația dumneavoastră, iar rezultatul se întoarce la ChatKit prin sendCustomAction. Rețineți, de asemenea, că un Card declarat cu "asForm": true se comportă ca un formular: câmpurile sale sunt validate și transmise acțiunii sale confirm.

Confirmare înainte de acțiune

Cardul de anulare de la început ilustrează o regulă de generalizat: o acțiune ireversibilă sau sensibilă necesită o confirmare explicită. Anularea unei comenzi, trimiterea unui e-mail, rambursarea, ștergerea: agentul propune, utilizatorul validează pe un card care indică clar ce se va întâmpla, iar serverul dumneavoastră, nu modelul, execută după reverificarea permisiunilor. Butoanele confirm și cancel ale unui Card sunt făcute pentru acest scop. Starea lor implicită de încărcare grișează întregul card în timpul procesării, ceea ce previne dublele clicuri.

Procesarea unei acțiuni în browser

Unele acțiuni nu au nimic de făcut pe server: deschiderea unei pagini în aplicația dumneavoastră, copierea unui link, afișarea unui modal. Declarați-le cu "handler": "client" în șablon, de exemplu {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Acestea ajung apoi în opțiunea widgets.onAction a interfeței:

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');
          // Notifică serverul, care poate actualiza widget-ul
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction trimite o acțiune către serverul dumneavoastră ca și cum ar veni de la un widget. Funcționează și în afara ChatKit: un buton de pe pagina dumneavoastră poate apela chatkit.sendCustomAction({ type: 'cart.empty' }) astfel încât asistentul să reacționeze la ceea ce se întâmplă în altă parte în aplicație.

Stări de încărcare

loadingBehavior controlează ceea ce vede utilizatorul în timp ce o acțiune este procesată:

ValoareEfect
auto (implicit)Se adaptează la componentă: doar butonul pentru un Button, nimic pentru un Select, întregul card pentru confirm al unui Card
selfStare de încărcare pe singura componentă care deține acțiunea
containerÎntregul widget devine estompat și inactiv
noneNicio stare de încărcare

Documentația recomandă păstrarea lui auto,除非 aveți o nevoie specifică. Implicit, acțiunile asupra unui widget sunt, de asemenea, blocate în timp ce un răspuns este transmis în flux, pentru a evita conflictele. Începând cu versiunea SDK 1.6.2, o acțiune declarată cu "streaming": false ocolește acest blocaj: aceasta este procesată de metoda sync_action a serverului, rezervată acțiunilor care își actualizează doar propriul widget sau acționează în afara firului de conversație.

Puncte cheie

  • O acțiune este un obiect {type, payload, handler, loadingBehavior} atașat unei componente widget; declanșează o procesare fără un mesaj al utilizatorului
  • Pe server, metoda action a ChatKitServer o primește și returnează evenimente: mesaj, widget actualizat sau nou răspuns al agentului prin respond
  • Payload-ul vine din browser: reverificați permisiunile și datele pe server (Pydantic), chiar și atunci când formularul validează deja required și pattern
  • Un HiddenContextItem, adăugat manual în store, informează modelul despre ceea ce a făcut utilizatorul
  • Acțiunile sensibile trec printr-un card de confirmare; acțiunile pur locale sunt procesate în browser (handler: "client", widgets.onAction, sendCustomAction)