Integra un agente con el SDK de agentes externos

Tu servidor autentica al usuario y firma una aserción de arranque. El cliente del SDK en el navegador obtiene esa aserción mediante una función de retorno, establece una sesión pública y expone la política vigente del agente para que tu aplicación la consulte. Mantén separadas esas responsabilidades del servidor y del navegador al integrar un agente externo.

El diagrama muestra el navegador, el servidor, el agente, el resultado, la sesión y la ruta de error; los pasos siguientes aplican esos límites a un agente integrado.

Mantén la confianza en el servidor y la interacción en la aplicación

El navegador es donde la persona visitante usa tu aplicación. El servidor es donde la autenticas y proteges la credencial que firma las aserciones. El SDK de agentes externos se conecta al runtime público con una referencia externalAgentRef y una función getBootstrapAssertion. La función devuelve una aserción firmada; no la firma por sí misma.

La guía del SDK documenta esta estructura de cliente:

import { createExternalAgentClient } from '@agentshelf/external-agents-sdk';

const client = createExternalAgentClient({
  externalAgentRef: 'ext_agent_public_12345678',
  getBootstrapAssertion: async () => {
    const response = await fetch('/api/agentshelf/bootstrap-assertion');
    if (!response.ok) {
      throw new Error('No se pudo obtener la aserción de arranque');
    }
    return response.text();
  },
});

La ruta del endpoint es un ejemplo de la guía oficial, no una ruta que cree el SDK. El controlador del servidor debe autenticar a la persona usuaria y emitir la aserción. No incluyas la credencial de firma en el código del navegador ni la devuelvas desde el endpoint. Sigue la guía canónica de primeros pasos para ver la configuración completa del servidor y del cliente.

Completa una integración acotada

Empieza con un solo recorrido, por ejemplo, una persona que inició sesión pregunta al centro de servicio interno por el estado de una solicitud. Define qué identidad verifica el servidor, qué referencia de agente externo configura la aplicación y qué verá la persona si el endpoint de aserción o el runtime no están disponibles.

1. Autentica en el límite de la aplicación. El endpoint del servidor comprueba la sesión habitual de la aplicación antes de emitir una aserción para esa persona.
2. Crea el cliente del SDK. Mantén la referencia pública del agente en la configuración de la aplicación y haz que getBootstrapAssertion llame al endpoint autenticado.
3. Establece la sesión y consulta su política. Llama a ensure() y luego a getEffectivePolicy() antes de mostrar acciones o iniciar una conversación.
4. Muestra solo las acciones admitidas. Usa las capacidades y herramientas de dominio de la política para decidir qué controles aparecen. Un control de interfaz no protege el acceso; el sistema también debe aplicar los permisos.
5. Trata explícitamente el resultado. Muestra el flujo de respuesta en la conversación y distingue un mensaje completado de un error, una interacción pendiente o una solicitud de aprobación.

Comprobación de integración (centro de servicio ficticio)
Solicitud: Una persona empleada que inició sesión pregunta por el estado de SR-204.
Sesión: ensure() crea una sesión o reutiliza una sesión guardada válida y devuelve una referencia pública sessionRef.
Política: El agente ofrece mensajería y conversaciones; la aplicación no muestra controles no admitidos.
Registro consultado: El registro aprobado del sistema de servicio SR-204 tiene el estado «En revisión».
Resultado: El flujo termina con message:complete e indica «En revisión». No se solicita modificar ningún registro.

Este ejemplo supone que el agente está configurado por separado con una forma aprobada de consultar SR-204. El cliente del SDK no crea esa conexión con el sistema de negocio. Si la función depende de archivos, artefactos o una herramienta de dominio, consulta la política pública antes de diseñar la interfaz. Para ver los campos exactos de las capacidades, continúa con políticas y capacidades.

Revisa las sesiones y los errores

Por defecto, el SDK guarda el estado de sesión en memoria, así que se pierde al recargar la página. Un adaptador de persistencia puede conservarla, pero el registro almacenado incluye el token portador de sesión. Elige el almacén según los scripts y usuarios que puedan leerlo, usa una clave storageKey distinta para cada agente integrado y revoca la sesión cuando la persona cierre sesión.

Define lo que verá la persona ante una solicitud denegada, una sesión caducada, un tiempo de espera agotado o una interrupción del flujo. Para diseñar las referencias públicas y la confianza en el servidor, consulta referencias públicas y arranque seguro; para el ciclo de los mensajes, consulta sesiones, conversaciones, streaming, archivos y artefactos.