Ir al contenido principal
Español— Elegir un idioma
Menú

Widgets interactivos

Lección 19 de 25 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. ¿Qué es un widget de ChatKit?
  2. Contenedores y componentes
  3. Diseño del widget en el Widget Builder
  4. Qué contiene una plantilla
  5. Mostrar el widget desde respond
  6. Dejar que el agente decida
  7. Una lista clicable
  8. Actualizar un widget mientras se muestra
  9. ¿Y las clases de Python?
  10. Cuándo usar un widget
  11. Puntos clave

Lección reescrita el 3 de noviembre de 2026. La versión anterior describía los widgets como componentes React escritos por el desarrollador y registrados en la interfaz, utilizando un módulo inexistente @openai/chatkit/react. En ChatKit, un widget es una descripción declarativa que construye tu servidor y que ChatKit renderiza por sí mismo. Esta lección sigue el SDK de Python openai-chatkit 1.6.5, que construye widgets a partir de plantillas .widget: sus clases Card, Text, Badge… están obsoletas. Los ejemplos se ejecutaron en un servidor ChatKit local. Fuentes: Widgets de ChatKit · Widgets (SDK de Python) · Construir respuestas interactivas con widgets · Widget Builder.

¿Qué es un widget de ChatKit?

Una respuesta de texto basta para explicaciones. Pero para presentar un pedido, comparar tres planes o confirmar una cita, el texto se convierte rápidamente en un muro de líneas que el usuario debe releer. Los widgets sustituyen ese texto por una interfaz: una tarjeta, una lista, un formulario o un gráfico, mostrados dentro del flujo de la conversación.

El enfoque es declarativo. Tu servidor no entrega HTML ni un componente React: describe el widget en JSON, utilizando un conjunto cerrado de componentes y propiedades, y lo envía al hilo como un elemento de pleno derecho (un WidgetItem). ChatKit lo dibuja con sus propios componentes, usando los colores del tema de la lección anterior. De ello se derivan dos consecuencias:

  • Solo puedes usar componentes y propiedades que ChatKit conozca. A cambio, el renderizado se mantiene coherente con el resto de la interfaz y ningún HTML o JavaScript arbitrario del servidor llega a la página.
  • El widget forma parte del historial: en turnos posteriores, se convierte en entrada para el modelo, que por tanto «ve» lo que mostró al usuario.

Contenedores y componentes

Todo widget tiene una raíz, elegida entre tres contenedores:

ContenedorUso
CardContenido independiente: un resumen, una confirmación, un formulario. Acepta un estado y botones de confirmación/cancelación debajo del contenido
ListViewUn conjunto de opciones: restaurantes, archivos, pedidos. Sus hijos son ListViewItem, con funcionalidad integrada de «ver más» (limit)
BasicReservado para vistas previas de entidades que se muestran al pasar el cursor sobre una mención

En su interior, ensamblas componentes: texto (Title, Text, Caption, Markdown), etiquetas (Badge), maquetación (Row, Col, Box, Spacer, Divider), multimedia (Image, Icon), comandos (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, que un Form puede agrupar), gráficos (Chart) y animaciones (Transition). La página de Componentes del Widget Builder enumera las propiedades de cada uno, con un editor para probarlos.

Diseño del widget en el Widget Builder

El flujo de trabajo previsto comienza en el Widget Builder de ChatKit Studio. Allí diseñas la maquetación, rellenas el panel de datos con valores de ejemplo para juzgar el renderizado y, a continuación, exportas un archivo .widget. Se trata de un archivo JSON que combina la plantilla, el esquema de los datos esperados (jsonSchema) y los datos de ejemplo. Ponlo bajo control de versiones junto con el código de tu servidor, por ejemplo en una carpeta widgets/.

En el lado del servidor, WidgetTemplate carga el archivo y build lo rellena con datos reales:

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

Una ruta relativa se resuelve desde el archivo Python que llama a from_file, no desde el directorio de lanzamiento. build acepta un diccionario o un modelo Pydantic.

Qué contiene una plantilla

La plantilla es un modelo Jinja que produce el JSON del widget. La plantilla de la tarjeta de pedido tiene este aspecto:

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

Rara vez escribirás una plantilla a mano, ya que el Widget Builder la genera. Pero leer una te ahorrará tiempo cuando surja el primer problema. Tres observaciones:

  • El filtro tojson convierte cada valor a JSON válido (una cadena entre comillas, un booleano como true o false) y escapa los caracteres especiales: un apóstrofo o comilla en el nombre de un producto no romperá el JSON.
  • Jinja se ejecuta en modo estricto: la falta de datos hace que build falle, en lugar de producir un widget medio vacío.
  • build no valida los datos contra el jsonSchema. Este esquema documenta los datos; si provienen de una herramienta o una base de datos, valídalos antes, por ejemplo con un modelo Pydantic.

El constructor WidgetTemplate(...) toma el mismo contenido que un archivo .widget ya leído: esto es útil para pruebas o para una plantilla generada por tu propio código.

Mostrar el widget desde respond

Para enviar el widget al hilo, stream_widget produce los eventos correspondientes de ChatKit. Los retransmites desde tu método respond:

from chatkit.server import stream_widget

# En tu clase ChatKitServer
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # tus datos
    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 es el texto que se copia al portapapeles cuando el usuario hace clic en el botón de copiar debajo de la respuesta. El servidor guarda el widget en el store por sí mismo, como cualquier elemento de difusión.

Dejar que el agente decida

Lo más habitual es que no sea tu código quien decida mostrar una tarjeta, sino el agente, cuando la conversación lo requiere. Proporciórale una herramienta que difunda el widget con AgentContext.stream_widget: stream_agent_response, visto en la lección 17, lo transmite a la interfaz en mitad de la respuesta.

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)  # tu acceso a datos
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Añade la herramienta a la lista tools del agente. La cadena devuelta por la herramienta sirve al modelo, que así sabe que la tarjeta está en pantalla y puede comentarla en lugar de repetirla.

Una lista clicable

Para ofrecer una elección, ListView presenta filas clicables. Cada ListViewItem puede llevar una acción, que se activa al hacer clic sin que el usuario tenga que escribir nada; la siguiente lección muestra cómo gestionarlo en el lado del servidor.

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

Más allá del limit, ChatKit muestra un enlace «ver más».

Actualizar un widget mientras se muestra

Un widget puede evolucionar ante los ojos del usuario, por ejemplo para mostrar un borrador que el modelo está escribiendo. Proporciona a stream_widget un generador asíncrono que produzca estados sucesivos del widget: ChatKit calcula las diferencias y envía solo lo que 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})
    # Estado final, una vez completado el texto
    yield draft_template.build({"text": text, "in_progress": False})

Solo los componentes Text y Markdown con un id muestran sus actualizaciones en un flujo, palabra por palabra; para los demás, ChatKit sustituye la parte modificada del widget.

¿Y las clases de Python?

Te encontrarás, incluso en las guías de OpenAI, widgets construidos con clases: Card(children=[Text(value="…")]). Siguen funcionando, pero el SDK openai-chatkit 1.6.5 las declara obsoletas en favor de WidgetTemplate: usarlas emite una advertencia que apunta a los archivos .widget. Para un proyecto nuevo, empieza desde plantillas. Para un proyecto existente, migra a tu ritmo: la advertencia no bloquea nada, pero una clase obsoleta podría desaparecer en una versión futura.

Cuándo usar un widget

La documentación cita usos típicos:

  • recopilar entrada estructurada con un formulario, o presentar un resultado rico (tabla, tarjeta, gráfico) que el texto renderiza mal;
  • ofrecer una elección entre varias opciones;
  • combinar el widget con acciones, para validar una selección, confirmar un paso o lanzar un procesamiento en el servidor;
  • acompañar un texto explicativo breve con un comando interactivo.

Por el contrario, no los coloques en todas partes. Un widget que repite palabra por palabra lo que dice el texto no aporta nada, y una conversación saturada de tarjetas se vuelve tan difícil de leer como un muro de texto.

Puntos clave

  • Un widget de ChatKit es una descripción declarativa (JSON) construida por tu servidor, no un componente React: ChatKit lo renderiza por sí mismo
  • Tres contenedores: Card (contenido independiente), ListView (lista de opciones), Basic (vistas previas de entidades)
  • Diseña en el Widget Builder, exporta un archivo .widget, cárgalo con WidgetTemplate.from_file(...) y rellénalo con build(data); las clases Card, Text… están obsoletas
  • Difunde con stream_widget desde respond, o desde una herramienta del agente con ctx.context.stream_widget
  • Un generador asíncrono actualiza el widget en directo; solo Text y Markdown con un id fluyen palabra por palabra