Widgets interactivos
En esta página
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 Pythonopenai-chatkit1.6.5, que construye widgets a partir de plantillas.widget: sus clasesCard,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:
| Contenedor | Uso |
|---|---|
Card | Contenido independiente: un resumen, una confirmación, un formulario. Acepta un estado y botones de confirmación/cancelación debajo del contenido |
ListView | Un conjunto de opciones: restaurantes, archivos, pedidos. Sus hijos son ListViewItem, con funcionalidad integrada de «ver más» (limit) |
Basic | Reservado 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
tojsonconvierte cada valor a JSON válido (una cadena entre comillas, un booleano comotrueofalse) 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
buildfalle, en lugar de producir un widget medio vacío. buildno valida los datos contra eljsonSchema. 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 conWidgetTemplate.from_file(...)y rellénalo conbuild(data); las clasesCard,Text… están obsoletas - Difunde con
stream_widgetdesderespond, o desde una herramienta del agente conctx.context.stream_widget - Un generador asíncrono actualiza el widget en directo; solo
TextyMarkdowncon unidfluyen palabra por palabra