Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Azioni utente

Lezione 20 di 25 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Cos’è un’azione?
  2. Elaborazione di un’azione sul server
  3. Moduli
  4. Conferma prima di agire
  5. Elaborazione di un’azione nel browser
  6. Stati di caricamento
  7. Punti chiave

Lezione riscritta il 3 novembre 2026. La versione precedente gestiva i clic nei componenti React personalizzati e inventava le “azioni di suggerimento”. In ChatKit, un’azione è un oggetto allegato a un componente widget (pulsante, riga di elenco, modulo). Per impostazione predefinita, viene elaborata sul tuo server nel metodo action di ChatKitServer, oppure nel browser se specifichi diversamente. Questa lezione segue la guida Azioni in ChatKit e l’SDK openai-chatkit 1.6.5. Il server, i template e il modulo sono stati eseguiti localmente; il codice React è stato verificato tramite compilazione. Fonti: Azioni in ChatKit · Costruire risposte interattive con i widget · Note di rilascio Python SDK 1.6.2.

Cos’è un’azione?

Un widget che si limita a visualizzare contenuti è solo una risposta esteticamente gradevole. Le azioni lo rendono utile: cliccare su “Annulla ordine”, selezionare una riga in un elenco o inviare un modulo attiva l’elaborazione senza che l’utente debba digitare un messaggio. ChatKit invia l’azione al tuo server, che può agire sui tuoi sistemi, aggiornare il widget, aggiungere una risposta al thread o riavviare l’agente.

Dichiari un’azione nel template del widget su un componente che ne accetta una (onClickAction per un Button o ListViewItem, onChangeAction per un Select, onSubmitAction per un Form, confirm e cancel per un Card). È un piccolo oggetto JSON:

CampoRuolo
typeIl nome dell’azione che il tuo codice verifica: "order.cancel"
payloadDati utili: {"number": "C-42"}
handler"server" (predefinito) o "client" per elaborarla nel browser
loadingBehaviorLo stato di caricamento visualizzato durante l’elaborazione (vedi sotto)

Elaborazione di un’azione sul server

Prendiamo una card ordine che offre la possibilità di annullamento. Il template dichiara l’azione sui pulsanti di conferma e annullamento della 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 }}}}}
}
"""

Lato server, aggiungi un metodo action al tuo ChatKitServer. Riceve il thread, l’azione, il widget che l’ha emessa (sender) e il tuo contesto, e restituisce eventi come 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(...) : come nella lezione 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", ""))
            # Il payload proviene dal browser: verifica nuovamente i permessi
            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)
            # Una traccia per il modello, mai mostrata all'utente
            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.")

Da questo codice emergono tre regole:

  • Il payload non è attendibile. Arriva dal browser, dove chiunque può modificarlo: la guida OpenAI richiede di trattarlo come dati non verificati. Prima di annullare, il server verifica che l’ordine appartenga all’utente autenticato. Lo user_id nel contesto è quello che il tuo endpoint autenticato vi inserisce (lezione 21).
  • Il modello deve sapere cosa è successo. Un clic non è un messaggio: senza una traccia, l’agente ignorerebbe al turno successivo che l’ordine è stato annullato. Un HiddenContextItem aggiunge queste informazioni al thread senza visualizzarle. L’SDK registra automaticamente solo gli elementi trasmessi (broadcast) e un elemento nascosto non deve mai essere trasmesso: devi aggiungerlo tu stesso allo store.
  • La risposta è un flusso di eventi. Qui un semplice messaggio; potrebbe essere un widget aggiornato, trasmesso con stream_widget come nella lezione precedente.

Per far commentare all’agente ciò che è appena accaduto, riavvialo dopo l’azione: async for event in self.respond(thread, None, context): yield event. Il tuo metodo respond rilegge il thread, trova l’elemento nascosto e risponde di conseguenza.

Moduli

Quando i campi di input (Input, Textarea, Select, Checkbox, DatePicker…) sono inseriti all’interno di un Form, i loro valori vengono aggiunti al payload di qualsiasi azione emessa da quel modulo, sotto il nome di ciascun campo:

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

All’invio, action.payload contiene source, order, category e detail. Un nome puntato, "client.name", produce un valore annidato: payload["client"]["name"]. Se il nome di un campo collide con una chiave già presente nel payload, il valore del campo viene ignorato e ChatKit emette un evento di errore: scegli nomi distinti.

La validazione del modulo avviene lato browser: required e pattern bloccano l’invio finché un campo non è valido. Questa è una comodità per l’utente, non una protezione: rivalida sul server, ad esempio con un modello 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)


# Nel metodo 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.")

Per una validazione più ricca, con messaggi di errore personalizzati, la documentazione consiglia di spostarsi fuori dal widget: un’azione lato client apre una finestra nella tua applicazione e il risultato torna a ChatKit tramite sendCustomAction. Nota inoltre che una Card dichiarata con "asForm": true si comporta come un modulo: i suoi campi vengono validati e passati alla sua azione confirm.

Conferma prima di agire

La card di annullamento all’inizio illustra una regola da generalizzare: un’azione irreversibile o sensibile richiede una conferma esplicita. Annullare un ordine, inviare un’email, effettuare un rimborso, eliminare: l’agente propone, l’utente valida su una card che dichiara chiaramente cosa accadrà, ed è il tuo server, non il modello, a eseguire dopo aver nuovamente verificato i permessi. I pulsanti confirm e cancel di una Card sono fatti per questo. Il loro stato di caricamento predefinito disattiva l’intera card durante l’elaborazione, il che previene i doppi clic.

Elaborazione di un’azione nel browser

Alcune azioni non hanno nulla da fare sul server: aprire una pagina nella tua applicazione, copiare un link, visualizzare una modale. Dichiarale con "handler": "client" nel template, ad esempio {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Arrivano quindi nell’opzione widgets.onAction dell’interfaccia:

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');
          // Notifica il server, che può aggiornare il widget
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction invia un’azione al tuo server come se provenisse da un widget. Funziona anche al di fuori di ChatKit: un pulsante sulla tua pagina può chiamare chatkit.sendCustomAction({ type: 'cart.empty' }) affinché l’assistente reagisca a ciò che accade altrove nell’applicazione.

Stati di caricamento

loadingBehavior controlla cosa vede l’utente mentre un’azione è in elaborazione:

ValoreEffetto
auto (predefinito)Si adatta al componente: solo il pulsante per un Button, nulla per un Select, l’intera card per il confirm di una Card
selfStato di caricamento sul singolo componente che contiene l’azione
containerL’intero widget sfuma e diventa inattivo
noneNessuno stato di caricamento

La documentazione consiglia di mantenere auto, a meno che tu non abbia un bisogno specifico. Per impostazione predefinita, le azioni su un widget sono anche bloccate mentre una risposta è in streaming, per evitare conflitti. Dalla versione 1.6.2 dell’SDK, un’azione dichiarata con "streaming": false bypassa questo blocco: viene elaborata dal metodo sync_action del server, riservato alle azioni che aggiornano solo il proprio widget o agiscono al di fuori del thread.

Punti chiave

  • Un’azione è un oggetto {type, payload, handler, loadingBehavior} allegato a un componente widget; attiva l’elaborazione senza un messaggio utente
  • Sul server, il metodo action di ChatKitServer la riceve e restituisce eventi: messaggio, widget aggiornato o nuova risposta dell’agente tramite respond
  • Il payload proviene dal browser: verifica nuovamente permessi e dati sul server (Pydantic), anche quando il modulo ha già validato required e pattern
  • Un HiddenContextItem, aggiunto manualmente allo store, informa il modello di ciò che l’utente ha fatto
  • Le azioni sensibili passano attraverso una card di conferma; le azioni puramente locali sono elaborate nel browser (handler: "client", widgets.onAction, sendCustomAction)