Cómo añadir un agente de IA a su SaaS mediante las API que ya tiene

Esta guía implementa una integración completa de AgentChat para un SaaS ficticio llamado SupportFlow. SupportFlow ya cuenta con APIs para encontrar facturas vencidas, enviar recordatorios y añadir notas a las cuentas. Aprovisionaremos esas APIs en AgentChat, crearemos un chat con ámbito de usuario, iniciaremos una ejecución asíncrona del agente y mostraremos el resultado a partir de los mensajes persistentes y de la propia base de datos de SupportFlow.

El límite arquitectónico importante es concreto: AgentChat se encarga del razonamiento del modelo, la selección de herramientas, el historial del chat y el control de las ejecuciones. SupportFlow sigue siendo responsable de los clientes, las facturas, la autorización, la validación y los registros empresariales finales. La documentación de la API conecta ambos sistemas.

No añadas todas las funcionalidades del SaaS al entorno de ejecución del agente. Expón un pequeño conjunto de operaciones empresariales esenciales como APIs HTTP y aprovisiona sus contratos en cada chat.

El flujo de solicitudes completado

SupportFlow crea una única clave de API de AgentChat desde el panel de control y la almacena únicamente en su backend.
Su backend registra las operaciones de SupportFlow mediante POST /api/api-documents.
Cuando un usuario abre el asistente, SupportFlow crea una sesión con el UUID del documento, un UUID de configuración del LLM y credenciales de usuario de solo escritura para su host de API.
SupportFlow envía el mensaje del usuario a POST /api/agent/sessions/{id}/chat.
AgentChat lee el contrato adjunto y utiliza su herramienta integrada http_request para llamar a SupportFlow.
SupportFlow consulta periódicamente los mensajes de AgentChat, mientras su interfaz de usuario normal lee las facturas y las notas de la base de datos de SupportFlow.

Paso 1: exponer operaciones empresariales específicas

El agente no necesita acceso a la base de datos ni una única API interna enorme. Para este flujo de trabajo, SupportFlow expone exactamente tres endpoints conscientes del inquilino:

GET /v1/invoices?status=overdue&limit=3
→ { "items": [{ "invoice_id": "inv_72", "account_id": "acct_9", "amount": 480, "currency": "USD", "due_at": "2026-08-01" }] }

POST /v1/reminders
{ "invoice_id": "inv_72", "tone": "friendly" }
→ { "reminder_id": "rem_31", "status": "queued" }

POST /v1/accounts/acct_9/notes
{ "body": "Friendly reminder queued for overdue invoice inv_72." }
→ { "note_id": "note_55", "created_at": "2026-08-23T09:30:00Z" }

Cada endpoint autentica al llamante, obtiene el tenant a partir de la credencial y filtra todas las operaciones de la base de datos. Los ID devueltos por una llamada se convierten en entradas seguras para la siguiente. El modelo nunca recibe una contraseña de la base de datos ni una interfaz de consultas sin restricciones.

Paso 2: crear la configuración del modelo una sola vez

Cada sesión de AgentChat requiere una configuración de LLM propiedad del usuario. SupportFlow puede crear una mediante el panel de control o la API y conservar el UUID devuelto.

POST $AGENTCHAT_SITE_URL/api/llm-config
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "name": "Support production model",
  "api_url": "https://llm-provider.example.com/v1/chat/completions",
  "api_key": "provider_secret",
  "model": "provider-model-name",
  "max_context_length": 128000,
  "max_output_tokens": 8192,
  "temperature": 0.2,
  "disable_reasoning": false
}

La respuesta se presenta como success y data. Guarda data.id como llm_config_id, que se utiliza al crear chats. AgentChat oculta la clave del proveedor al volver a leer las configuraciones.

Paso 3: aprovisionar el documento de la API de SupportFlow

Este es el mecanismo de plugins. El documento contiene instrucciones operativas, entradas exactas, salidas exactas y reglas de secuenciación; no texto de marketing ni un enlace que obligue al agente a adivinar.

POST $AGENTCHAT_SITE_URL/api/api-documents
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "SupportFlow Invoice Actions",
  "description": "Find overdue invoices, queue reminders, and record account notes.",
  "content": "# SupportFlow Invoice Actions\nBase URL: https://support.example.com/v1\n\nGET /invoices?status=overdue&limit=3 returns items with invoice_id, account_id, amount, currency, and due_at. Use only when the user requests invoice lookup.\n\nPOST /reminders body: invoice_id required; tone is friendly or firm. Response: reminder_id and status. Never send more reminders than the user requested.\n\nPOST /accounts/{account_id}/notes body: body required. Call only after the reminder request succeeds. Include the invoice ID and reminder status in the note.\n\nIf any write returns 401 or 403, stop writing and explain that the session credential needs access. Do not retry a permission denial."
}

AgentChat devuelve el nuevo documento en data, incluida su UUID. Guarde esa UUID en la configuración de integración de SupportFlow. Actualizar este documento más adelante cambia las instrucciones utilizadas en los turnos de chat posteriores, porque las sesiones adjuntan el documento en lugar de copiarlo.

Paso 4: crear un chat para el usuario actual de SupportFlow

POST $AGENTCHAT_SITE_URL/api/agent/sessions
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "Invoice assistant for user_42",
  "llm_config_id": "llm_config_uuid",
  "api_document_ids": ["supportflow_document_uuid"],
  "system_prompt": "Act only on the user’s explicit request. Summarize every write with the affected invoice and account IDs.",
  "compact_threshold_percent": 80,
  "max_turns": 12,
  "tool_timeout_seconds": 120,
  "tool_result_max_chars": 10000,
  "host_headers": [
    { "host": "support.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_user_42_token" },
    { "host": "support.example.com", "header_key": "X-Workspace-ID", "header_value": "workspace_7" }
  ]
}

Los valores de las cabeceras son de solo escritura. AgentChat los almacena para esta sesión, los inyecta únicamente cuando http_request tiene como destino el host correspondiente y no expone sus valores al modelo ni en las respuestas de la API. Un segundo usuario de SupportFlow obtiene una sesión diferente con la misma UUID del documento, pero con cabeceras distintas.

Paso 5: iniciar la ejecución asíncrona

POST $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/chat
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{ "message": "Find my three most overdue invoices, send each a friendly reminder, and add a note to each account." }

→ { "success": true, "data": { "session_id": "session_uuid", "state": "processing" } }

AgentChat retorna inmediatamente y continúa la ejecución en segundo plano. El agente recibe el documento de SupportFlow adjunto junto con exactamente cuatro herramientas integradas: get_api_document, http_request, sleep y view_image. Las capacidades de SupportFlow no están compiladas en esas herramientas; se aprenden a partir del contrato de API proporcionado y se ejecutan mediante http_request.

Lo que hace el agente durante esta solicitud

Llamar al endpoint documentado de facturas vencidas mediante http_request.
Leer los elementos estructurados y seleccionar como máximo las tres facturas solicitadas por el usuario.
Poner los recordatorios en cola. Las llamadas independientes generadas por una respuesta del modelo pueden ejecutarse de forma concurrente.
Una vez disponibles los resultados satisfactorios de los recordatorios, llamar al endpoint de notas de cuenta con cada factura y el ID de cuenta devueltos.
Generar un mensaje final del asistente que enumere las operaciones completadas y cualquier fallo por factura.

Por eso es importante diseñar bien las respuestas. Un resultado ambiguo como «éxito» no le proporciona al agente nada fiable con lo que enlazar la siguiente acción. Los identificadores y estados estructurados permiten al ciclo de razonamiento combinar varias API convencionales para lograr un único resultado para el usuario.

Paso 6: consultar mensajes persistentes, no un flujo de un LLM

GET $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/messages?after_id=&after_revision=0
Authorization: Bearer ac_live_AGENTCHAT_KEY

→ {
  "success": true,
  "data": {
    "messages": [{ "id": "message_uuid", "role": "assistant", "content": "...", "stream_status": "streaming", "revision": 4 }],
    "last_id": "message_uuid",
    "last_revision": 4,
    "is_processing": true,
    "total_tokens": 2840
  }
}

SupportFlow consulta una vez por segundo desde su backend o desde un cliente intermediario, combina las filas por ID de mensaje y sustituye el contenido solo cuando aumenta la revisión. La base de datos de AgentChat es la fuente de verdad de la salida de la conversación. La base de datos de SupportFlow sigue siendo la fuente de verdad de las facturas, los recordatorios y las notas.

Cuando is_processing pasa a ser false, SupportFlow puede actualizar sus consultas de facturas y cuentas. La interfaz normal del producto muestra entonces los recordatorios y las notas creados mediante sus propias API; no necesita analizar la prosa del asistente para reconstruir el estado del negocio.

Control de la ejecución y recuperación ante fallos

GET  /api/agent/sessions/session_uuid/state
POST /api/agent/sessions/session_uuid/stop
POST /api/agent/sessions/session_uuid/continue

El endpoint de estado informa de si el procesamiento está activo y de si la siguiente acción es «continue». Las solicitudes de detención cancelan una ejecución activa. Si un fallo recuperable o el límite máximo de turnos pausa el trabajo, «continue» inicia otra ejecución con un nuevo presupuesto de turnos y el mismo contexto de conversación persistente.

Qué aprovisionar y qué no aprovisionar

Aprovisione API que representen capacidades empresariales estables: buscar, crear, actualizar, validar, publicar o consultar el estado de los trabajos.
Documente los campos obligatorios, las restricciones, los objetos de respuesta, el significado de los errores, los efectos secundarios y los requisitos de orden.
Adjunte únicamente los documentos necesarios para la experiencia de chat, en lugar de todos los endpoints internos.
Mantenga las credenciales en encabezados de sesión específicos del host, nunca en prompts ni en el contenido de la documentación de la API.
No exponga SQL sin procesar, acceso irrestricto a archivos ni un proxy interno genérico solo para hacer que el agente sea flexible.
Haga que su propia autorización y validación se ejecuten en cada solicitud de herramienta exactamente igual que para los demás clientes.

Por qué el alcance de capacidades puede crecer sin ampliar el conjunto de herramientas principal

Un producto RAG puede aprovisionar endpoints de búsqueda y citación. Un producto de historias puede aprovisionar endpoints para capítulos, generación de imágenes y publicación. Un producto de programación puede aprovisionar endpoints para archivos del espacio de trabajo, comprobaciones y despliegues. AgentChat sigue utilizando las mismas cuatro herramientas principales. Las operaciones específicas de la aplicación llegan como documentos de API, por lo que añadir una capacidad es un cambio de aprovisionamiento y no una nueva versión del entorno de ejecución del agente.

Ese es el patrón central de AgentChat: crear documentos de API, crear una sesión de chat con un ámbito definido, dejar que el agente componga tus operaciones HTTP, consumir mensajes persistentes y mostrar los registros resultantes desde la base de datos de tu propia aplicación.