Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Widget interattivi

Lezione 19 di 25 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Cos’è un widget ChatKit?
  2. Contenitori e componenti
  3. Progettare il widget nel Widget Builder
  4. Cosa contiene un template
  5. Visualizzare il widget da respond
  6. Lasciare decidere all’agente
  7. Una lista cliccabile
  8. Aggiornare un widget mentre è visualizzato
  9. E le classi Python?
  10. Quando usare un widget
  11. Punti chiave

Lezione riscritta il 3 novembre 2026. La versione precedente descriveva i widget come componenti React scritti dallo sviluppatore e registrati nell’interfaccia, utilizzando un modulo inesistente @openai/chatkit/react. In ChatKit, un widget è una descrizione dichiarativa che il tuo server costruisce e che ChatKit esegue il rendering autonomamente. Questa lezione segue l’SDK Python openai-chatkit 1.6.5, che costruisce i widget da template .widget: le sue classi Card, Text, Badge… sono deprecate. Gli esempi sono stati eseguiti su un server ChatKit locale. Fonti: Widget ChatKit · Widget (SDK Python) · Costruire risposte interattive con i widget · Widget Builder.

Cos’è un widget ChatKit?

Una risposta testuale è sufficiente per le spiegazioni. Ma per presentare un ordine, confrontare tre piani o confermare un appuntamento, il testo diventa rapidamente un muro di righe che l’utente deve rileggere. I widget sostituiscono quel testo con un’interfaccia: una scheda, una lista, un modulo o un grafico, visualizzati all’interno del flusso della conversazione.

L’approccio è dichiarativo. Il tuo server non fornisce né HTML né un componente React: descrive il widget in JSON, utilizzando un insieme chiuso di componenti e proprietà, e lo invia nel thread come un elemento a tutti gli effetti (un WidgetItem). ChatKit ne esegue il rendering con i propri componenti, utilizzando i colori del tema visti nella lezione precedente. Ne derivano due conseguenze:

  • Puoi usare solo componenti e proprietà che ChatKit conosce. In cambio, il rendering rimane coerente con il resto dell’interfaccia e nessun HTML o JavaScript arbitrario dal server raggiunge la pagina.
  • Il widget fa parte della cronologia: nei turni successivi, viene convertito in input per il modello, che quindi “vede” ciò che ha mostrato all’utente.

Contenitori e componenti

Ogni widget ha una radice, scelta tra tre contenitori:

ContenitoreUtilizzo
CardContenuto autonomo: un riepilogo, una conferma, un modulo. Accetta uno stato e pulsanti di conferma/annullamento sotto il contenuto
ListViewUn insieme di opzioni: ristoranti, file, ordini. I suoi figli sono ListViewItem, con funzionalità integrata “vedi altro” (limit)
BasicRiservato alle anteprime di entità visualizzate quando si passa il mouse su una menzione

All’interno, assembli i componenti: testo (Title, Text, Caption, Markdown), etichette (Badge), layout (Row, Col, Box, Spacer, Divider), media (Image, Icon), comandi (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, che un Form può raggruppare), grafici (Chart) e animazioni (Transition). La pagina Componenti del Widget Builder elenca le proprietà di ciascuno, con un editor per provarli.

Progettare il widget nel Widget Builder

Il flusso di lavoro previsto inizia nel Widget Builder di ChatKit Studio. Progetti il layout lì, riempi il pannello dati con valori di esempio per valutare il rendering, ed esporti poi un file .widget. Questo è un file JSON che combina il template, lo schema dei dati attesi (jsonSchema) e i dati di esempio. Mettilo sotto controllo versione insieme al codice del tuo server, ad esempio in una cartella widgets/.

Lato server, WidgetTemplate carica il file e build lo riempie con dati reali:

from chatkit.widgets import WidgetTemplate

order_template = WidgetTemplate.from_file("widgets/order.widget")

card = order_template.build({
    "number": "C-42",
    "status": "Shipped",
    "color": "success",
    "items": [{"name": "Keyboard", "price": "$49.90"}, {"name": "Mouse", "price": "$10.00"}],
    "total": "$59.90",
})

Un percorso relativo viene risolto dal file Python che chiama from_file, non dalla directory di avvio. build accetta un dizionario o un modello Pydantic.

Cosa contiene un template

Il template è un modello Jinja che produce il JSON del widget. Il template della scheda ordine appare così:

ORDER_TEMPLATE = """
{
  "type": "Card",
  "children": [
    {"type": "Row", "justify": "between", "align": "center", "children": [
      {"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
      {"type": "Badge", "label": {{ status | tojson }}, "color": {{ color | tojson }}}
    ]},
    {"type": "Divider"},
    {"type": "Col", "gap": 2, "children": [
      {%- for item in items %}
      {"type": "Row", "justify": "between", "children": [
        {"type": "Text", "value": {{ item.name | tojson }}},
        {"type": "Text", "value": {{ item.price | tojson }}}
      ]}{% if not loop.last %},{% endif %}
      {%- endfor %}
    ]},
    {"type": "Divider"},
    {"type": "Row", "justify": "between", "children": [
      {"type": "Text", "value": "Total", "weight": "semibold"},
      {"type": "Text", "value": {{ total | tojson }}, "weight": "semibold"}
    ]}
  ]
}
"""

order_template = WidgetTemplate({"version": "1.0", "name": "order", "template": ORDER_TEMPLATE})

Raramente scriverai un template a mano, dato che il Widget Builder lo genera. Ma leggerne uno ti farà risparmiare tempo quando sorgerà il primo problema. Tre osservazioni:

  • Il filtro tojson converte ogni valore in JSON valido (una stringa tra virgolette, un booleano come true o false) ed esegue l’escape dei caratteri speciali: un apostrofo o una virgoletta nel nome di un prodotto non romperà il JSON.
  • Jinja gira in modalità strict: dati mancanti causano il fallimento di build, invece di produrre un widget mezzo vuoto.
  • build non valida i dati rispetto allo jsonSchema. Questo schema documenta i dati; se provengono da uno strumento o da un database, validali prima, ad esempio con un modello Pydantic.

Il costruttore WidgetTemplate(...) accetta lo stesso contenuto di un file .widget già letto: è utile per i test o per un template generato dal tuo stesso codice.

Visualizzare il widget da respond

Per inviare il widget nel thread, stream_widget produce gli eventi ChatKit corrispondenti. Li inoltri dal tuo metodo respond:

from chatkit.server import stream_widget

# Nella tua classe ChatKitServer
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # i tuoi dati
    async for event in stream_widget(
        thread,
        card,
        copy_text="Order C-42: shipped, $59.90",
        generate_id=lambda item_type: self.store.generate_item_id(item_type, thread, context),
    ):
        yield event

copy_text è il testo copiato negli appunti quando l’utente clicca sul pulsante di copia sotto la risposta. Il server salva il widget nello store stesso, come qualsiasi elemento broadcast.

Lasciare decidere all’agente

Molto spesso, non è il tuo codice a decidere di visualizzare una scheda, ma l’agente, quando la conversazione lo richiede. Dagli uno strumento che trasmette il widget con AgentContext.stream_widget: stream_agent_response, visto nella lezione 17, lo trasmette all’interfaccia nel mezzo della risposta.

from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext


@function_tool(description_override="Displays order details as a card.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
    data = await get_order_data(number)  # il tuo accesso ai dati
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Aggiungi lo strumento alla lista tools dell’agente. La stringa restituita dallo strumento serve al modello, che così sa che la scheda è sullo schermo e può commentarla invece di ripeterla.

Una lista cliccabile

Per offrire una scelta, ListView presenta righe cliccabili. Ogni ListViewItem può trasportare un’azione, attivata al click senza che l’utente debba digitare nulla; la prossima lezione mostra come gestirla lato server.

LIST_TEMPLATE = """
{
  "type": "ListView",
  "limit": 5,
  "children": [
    {%- for o in orders %}
    {
      "type": "ListViewItem",
      "key": {{ o.number | tojson }},
      "onClickAction": {"type": "order.open", "payload": {"number": {{ o.number | tojson }}}},
      "children": [
        {"type": "Col", "children": [
          {"type": "Text", "value": {{ ("Order " ~ o.number) | tojson }},
          {"type": "Caption", "value": {{ o.date | tojson }}}
        ]}
      ]
    }{% if not loop.last %},{% endif %}
    {%- endfor %}
  ]
}
"""

order_list_template = WidgetTemplate({"version": "1.0", "name": "order_list", "template": LIST_TEMPLATE})
list_widget = order_list_template.build({"orders": [{"number": "C-42", "date": "November 2"}, {"number": "C-41", "date": "October 28"}]})

Oltre il limit, ChatKit visualizza un link “vedi altro”.

Aggiornare un widget mentre è visualizzato

Un widget può evolversi sotto gli occhi dell’utente, ad esempio per mostrare una bozza che il modello sta scrivendo. Dai a stream_widget un generatore asincrono che produce stati successivi del widget: ChatKit calcola le differenze e invia solo ciò che cambia.

from collections.abc import AsyncGenerator

from chatkit.widgets import DynamicWidgetRoot, WidgetTemplate

draft_template = WidgetTemplate({
    "version": "1.0",
    "name": "draft",
    "template": """{"type": "Card", "children": [
        {"type": "Title", "value": "Draft"},
        {"type": "Text", "id": "body", "value": {{ text | tojson }}, "streaming": {{ in_progress | tojson }}}
    ]}""",
})


async def streaming_draft(chunks: AsyncGenerator[str, None]) -> AsyncGenerator[DynamicWidgetRoot, None]:
    text = ""
    async for chunk in chunks:
        text += chunk
        yield draft_template.build({"text": text, "in_progress": True})
    # Stato finale, una volta completato il testo
    yield draft_template.build({"text": text, "in_progress": False})

Solo i componenti Text e Markdown con un id visualizzano i loro aggiornamenti in uno stream, parola per parola; per gli altri, ChatKit sostituisce la parte modificata del widget.

E le classi Python?

Incontrerai, anche nelle guide OpenAI, widget costruiti con classi: Card(children=[Text(value="…")]). Funzionano ancora, ma l’SDK openai-chatkit 1.6.5 le dichiara deprecate a favore di WidgetTemplate: usarle emette un avviso che punta ai file .widget. Per un nuovo progetto, parti dai template. Per un progetto esistente, migra al tuo ritmo: l’avviso non blocca nulla, ma una classe deprecata potrebbe scomparire in una versione futura.

Quando usare un widget

La documentazione cita usi tipici:

  • raccogliere input strutturati con un modulo, o presentare un risultato ricco (tabella, scheda, grafico) che il testo rende male;
  • offrire una scelta tra diverse opzioni;
  • combinare il widget con azioni, per validare una selezione, confermare un passaggio o avviare un’elaborazione lato server;
  • accompagnare un breve testo esplicativo con un comando interattivo.

Al contrario, non metterli ovunque. Un widget che ripete parola per parola ciò che dice il testo non aggiunge nulla, e una conversazione satura di schede diventa difficile da leggere quanto un muro di testo.

Punti chiave

  • Un widget ChatKit è una descrizione dichiarativa (JSON) costruita dal tuo server, non un componente React: ChatKit ne esegue il rendering autonomamente
  • Tre contenitori: Card (contenuto autonomo), ListView (lista di opzioni), Basic (anteprime di entità)
  • Progetta nel Widget Builder, esporta un file .widget, caricalo con WidgetTemplate.from_file(...) e riempilo con build(data); le classi Card, Text… sono deprecate
  • Trasmetti con stream_widget da respond, o da uno strumento dell’agente con ctx.context.stream_widget
  • Un generatore asincrono aggiorna il widget in tempo reale; solo Text e Markdown con un id fanno lo stream parola per parola