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

Acciones de usuario

Lección 20 de 25 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. ¿Qué es una acción?
  2. Procesamiento de una acción en el servidor
  3. Formularios
  4. Confirmar antes de actuar
  5. Procesamiento de una acción en el navegador
  6. Estados de carga
  7. Puntos clave

Lección reescrita el 3 de noviembre de 2026. La versión anterior gestionaba clics en componentes React personalizados e inventaba «acciones de sugerencia». En ChatKit, una acción es un objeto adjunto a un componente de widget (botón, fila de lista, formulario). Por defecto, se procesa en tu servidor dentro del método action de ChatKitServer, o en el navegador si lo especificas de otro modo. Esta lección sigue la guía Actions in ChatKit y el SDK openai-chatkit 1.6.5. El servidor, las plantillas y el formulario se ejecutaron localmente; el código React se verificó mediante compilación. Fuentes: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

¿Qué es una acción?

Un widget que solo muestra contenido es simplemente una respuesta bonita. Las acciones lo hacen útil: hacer clic en «Cancelar pedido», seleccionar una fila en una lista o enviar un formulario desencadena un procesamiento sin que el usuario tenga que escribir un mensaje. ChatKit envía la acción a tu servidor, que puede actuar sobre tus sistemas, actualizar el widget, añadir una respuesta al hilo o reiniciar el agente.

Declaras una acción en la plantilla del widget sobre un componente que la acepte (onClickAction para un Button o ListViewItem, onChangeAction para un Select, onSubmitAction para un Form, confirm y cancel para un Card). Es un pequeño objeto JSON:

CampoFunción
typeEl nombre de la acción que prueba tu código: "order.cancel"
payloadDatos útiles: {"number": "C-42"}
handler"server" (por defecto) o "client" para procesarla en el navegador
loadingBehaviorEl estado de carga mostrado durante el procesamiento (ver más abajo)

Procesamiento de una acción en el servidor

Tomemos como ejemplo una tarjeta de pedido que ofrece la opción de cancelación. La plantilla declara la acción en los botones de confirmación y cancelación de la 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 }}}}}
}
"""

En el lado del servidor, añade un método action a tu ChatKitServer. Recibe el hilo, la acción, el widget que la emitió (sender) y tu contexto, y devuelve eventos como 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(...) : como en la lección 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", ""))
            # El payload viene del navegador: vuelve a verificar los permisos
            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)
            # Un rastro para el modelo, nunca mostrado al usuario
            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.")

De este código se desprenden tres reglas:

  • El payload no es de confianza. Llega desde el navegador, donde cualquiera puede modificarlo: la guía de OpenAI exige tratarlo como datos no verificados. Antes de cancelar, el servidor comprueba que el pedido pertenece al usuario autenticado. El user_id en el contexto es el que tu endpoint autenticado coloca allí (lección 21).
  • El modelo debe saber qué ha ocurrido. Un clic no es un mensaje: sin un rastro, el agente ignoraría en el siguiente turno que el pedido ha sido cancelado. Un HiddenContextItem añade esta información al hilo sin mostrarla. El SDK registra automáticamente solo los elementos difundidos (broadcast), y un elemento oculto nunca debe difundirse: debes añadirlo tú mismo al store.
  • La respuesta es un flujo de eventos. Aquí un mensaje simple; podría ser un widget actualizado, difundido con stream_widget como en la lección anterior.

Para que el agente comente lo que acaba de ocurrir, reinícialo tras la acción: async for event in self.respond(thread, None, context): yield event. Tu método respond vuelve a leer el hilo, encuentra el elemento oculto y responde en consecuencia.

Formularios

Cuando los campos de entrada (Input, Textarea, Select, Checkbox, DatePicker…) se colocan dentro de un Form, sus valores se añaden al payload de cualquier acción emitida desde ese formulario, bajo el nombre de cada 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}
     ]}
  ]
}
"""

Al enviar, action.payload contiene source, order, category y detail. Un nombre con puntos, "client.name", produce un valor anidado: payload["client"]["name"]. Si el nombre de un campo colisiona con una clave ya presente en el payload, el valor del campo se ignora y ChatKit emite un evento de error: elige nombres distintos.

La validación del formulario es del lado del navegador: required y pattern bloquean el envío mientras un campo no sea válido. Esto es comodidad para el usuario, no protección: vuelve a validar en el servidor, por ejemplo con un modelo 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)


# En el método de acción
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.")

Para una validación más rica, con mensajes de error personalizados, la documentación aconseja salirse del widget: una acción del lado del cliente abre una ventana en tu aplicación y el resultado vuelve a ChatKit mediante sendCustomAction. Ten en cuenta también que una Card declarada con "asForm": true se comporta como un formulario: sus campos se validan y se pasan a su acción confirm.

Confirmar antes de actuar

La tarjeta de cancelación del principio ilustra una regla que debe generalizarse: una acción irreversible o sensible requiere confirmación explícita. Cancelar un pedido, enviar un correo electrónico, reembolsar, borrar: el agente propone, el usuario valida en una tarjeta que indica claramente qué va a ocurrir, y es tu servidor, no el modelo, el que ejecuta la acción tras volver a verificar los permisos. Los botones confirm y cancel de una Card están hechos para esto. Su estado de carga por defecto pone en gris toda la tarjeta durante el procesamiento, lo que evita los dobles clics.

Procesamiento de una acción en el navegador

Algunas acciones no tienen nada que hacer en el servidor: abrir una página en tu aplicación, copiar un enlace, mostrar un modal. Decláralas con "handler": "client" en la plantilla, por ejemplo {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Luego llegan a la opción widgets.onAction de la interfaz:

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 al servidor, que puede actualizar el widget
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction envía una acción a tu servidor como si viniera de un widget. También funciona fuera de ChatKit: un botón en tu página puede llamar a chatkit.sendCustomAction({ type: 'cart.empty' }) para que el asistente reaccione a lo que ocurre en otra parte de la aplicación.

Estados de carga

loadingBehavior controla lo que ve el usuario mientras se procesa una acción:

ValorEfecto
auto (por defecto)Se adapta al componente: solo el botón para un Button, nada para un Select, toda la tarjeta para el confirm de una Card
selfEstado de carga en el único componente que contiene la acción
containerTodo el widget se desvanece y se vuelve inactivo
noneSin estado de carga

La documentación recomienda mantener auto, a menos que tengas una necesidad específica. Por defecto, las acciones sobre un widget también se bloquean mientras se transmite una respuesta, para evitar conflictos. Desde la versión 1.6.2 del SDK, una acción declarada con "streaming": false omite este bloqueo: es procesada por el método sync_action del servidor, reservado para acciones que solo actualizan su propio widget o actúan fuera del hilo.

Puntos clave

  • Una acción es un objeto {type, payload, handler, loadingBehavior} adjunto a un componente de widget; desencadena un procesamiento sin mensaje del usuario
  • En el servidor, el método action de ChatKitServer la recibe y devuelve eventos: mensaje, widget actualizado o nueva respuesta del agente mediante respond
  • El payload viene del navegador: vuelve a verificar permisos y datos en el servidor (Pydantic), incluso cuando el formulario ya valida required y pattern
  • Un HiddenContextItem, añadido manualmente al store, informa al modelo de lo que ha hecho el usuario
  • Las acciones sensibles pasan por una tarjeta de confirmación; las acciones puramente locales se procesan en el navegador (handler: "client", widgets.onAction, sendCustomAction)