Llamar a un agente desde tu sistema — Manual del operador | AI Agent Builder

Llamar a un agente desde tu sistema

La API REST para conversar y disparar automatizaciones, el endpoint compatible con OpenAI, A2A, las claves y los errores que tu código tiene que manejar.

8 min de lectura · Actualizado 13 de noviembre de 2026

Esta guía es para quien programa la integración: el backend del portal de pacientes de Clínica del Sol que le pregunta al agente de turnos, o un sistema que dispara un agente cuando pasa algo. Explica los contratos tal como están hoy, incluidos sus bordes.

Hay tres formas de llamar a un agente:

FormaPara quéRespuesta
API RESTConversar desde tu sistema, o disparar una automatizaciónCompleta, en JSON
Compatible con OpenAIHerramientas que ya hablan la API de chat de OpenAIEn streaming o completa
A2AQue un agente de otra plataforma llame al tuyoJSON-RPC

Antes de empezar

  1. El tenant tiene habilitado el acceso por API (capítulo 8). Sin eso, toda llamada recibe 403.
  2. Creás una clave de API en el tenant del agente, con el permiso del canal que vas a usar: channel:rest, channel:openai_compat o channel:a2a. La clave tiene la forma sk_….

Dos cosas a tener en cuenta sobre las claves:

  • Una clave sirve solo para su tenant. Una clave de Nortelink no llega a los agentes de Clínica del Sol: la clave tiene que crearse en el tenant de la clínica.
  • Una clave sirve para todos los agentes del tenant. Si necesitás separar accesos por agente, usá tenants distintos.

La clave va en el encabezado x-api-key (o Authorization: Bearer sk_…). Es un secreto de servidor: no la pongas en una página web; para eso está el widget, con su clave pública restringida.

API REST: conversar

La URL exacta está en la pestaña Canales del agente, en la tarjeta REST. Tiene esta forma:

POST {URL de la API}/api/rest/{tenant}/{agente}

En la instalación de Synaptic Links, {URL de la API} es https://ai.synapticlinks.com.ar/api, así que la ruta lleva /api dos veces. Es correcto: copiala tal cual.

curl -X POST "https://ai.synapticlinks.com.ar/api/api/rest/clinica-del-sol/turnos-clinica" \
  -H "x-api-key: $AICHAT_API_KEY" -H "content-type: application/json" \
  -d '{ "message": "¿Hay turnos de clínica médica el martes?", "sessionId": "paciente-4821", "locale": "es" }'
CampoQué hace
messageEl mensaje del usuario. Si está, es una conversación.
sessionIdOpcional. Un identificador tuyo (por ejemplo, el del paciente) o el sessionId que devolvió la respuesta anterior. Los mensajes con el mismo valor forman la misma conversación.
localeIdioma de la conversación.
scopeVariables para el workflow (variables.* en las expresiones), por ejemplo { "plan": "gold" }.
includedContextContexto de la entidad, igual que el que manda una página con el widget. Si su payload trae customerId o entityKey, se usa para la memoria por entidad (capítulo 10).

La respuesta, con HTTP 200:

{
  "sessionId": "8f0c2a1e-…",
  "message": "Sí, el martes hay turnos a las 9:30 y a las 11:30 en Sede Centro.",
  "finishReason": "stop",
  "provider": "openai",
  "model": "gpt-…",
  "latencyMs": 2140,
  "usage": { "promptTokens": 0, "completionTokens": 0, "totalTokens": 912 },
  "stepExecutions": [ … ]
}
  • Los nombres de los campos van en camelCase.
  • La respuesta llega completa: este canal no transmite mientras se genera.
  • usage solo informa totalTokens.

Revisá siempre finishReason. Si la ejecución falló —incluido el caso de saldo agotado o límite de consumo alcanzado— la API igual responde 200, con finishReason: "error" y un message que puede venir vacío. Tu código no debe mostrarle al usuario un mensaje vacío como si fuera una respuesta.

Cómo se arma la conversación

Sin sessionId, cada llamada empieza una conversación nueva. Con sessionId, la plataforma junta los mensajes con ese valor para esa clave. Como en los canales de mensajería, después de 24 horas sin mensajes empieza una sesión nueva, y la respuesta trae un sessionId distinto.

La API no sabe quién es tu usuario: para la plataforma, todas las conversaciones son de la clave. Por eso:

  • Usá un sessionId por usuario o por conversación, nunca uno compartido.
  • Si el agente usa memoria de largo plazo, mandá el identificador de la persona en includedContext para que los recuerdos no se mezclen entre usuarios.

API REST: disparar una automatización

La misma URL, sin message, dispara el agente con datos en lugar de un mensaje. Todo el cuerpo, salvo sessionId y locale, llega al workflow como trigger.*:

{ "evento": "turno_cancelado", "turno_id": "T-99812", "sede": "Sede Norte" }
  • Es sincrónico: la llamada espera a que el workflow termine.
  • Si el workflow tiene un nodo Responder, la respuesta HTTP usa el estado, los encabezados y el cuerpo que ese nodo define. Si no, devuelve el cuerpo estándar con message vacío.
  • No hay idempotencia: si reintentás una llamada que en realidad se ejecutó, el workflow corre dos veces. Si el workflow tiene efectos, incluí un identificador propio y descartá duplicados en el workflow o en tu sistema.
  • No hay aviso al terminar. Los webhooks salientes (capítulo 5) informan eventos de la plataforma, no el resultado de una ejecución.

Compatible con OpenAI

Para herramientas que ya usan el SDK de OpenAI:

POST {URL de la API}/v1/chat/completions
GET  {URL de la API}/v1/models
  • La clave va como Authorization: Bearer sk_…, con permiso channel:openai_compat.
  • model es la clave del agente (turnos-clinica). /v1/models lista los agentes activos del tenant.
  • Se usa el último mensaje user como turno. Los mensajes system se agregan a las instrucciones.
  • stream es verdadero por defecto.
  • Para que varias llamadas sean una misma conversación, mandá extra_metadata.session_id. Sin eso, cada llamada empieza de cero.

Se ignoran temperature, max_tokens, tools, n y stop: el agente usa su propia configuración. Los errores no vienen con el formato de OpenAI sino con el de la plataforma (más abajo), y en modo streaming un error de ejecución termina como una respuesta vacía.

A2A

Para agentes de otras plataformas que hablan el protocolo A2A:

  • Tarjeta del agente: GET {URL de la API}/api/a2a/{tenant}/{agente}/.well-known/agent-card.json.
  • Mensajes: POST a la misma ruta sin el sufijo, JSON-RPC, métodos SendMessage y SendStreamingMessage.

La tarjeta no es pública: pide Authorization: Bearer con una clave con permiso channel:a2a. Además, el agente tiene que tener A2A habilitado en su pestaña Canales, con nombre y descripción.

  • Solo se aceptan partes de texto, hasta 16.000 bytes.
  • Para seguir una conversación, mandá el contextId de la respuesta anterior.
  • Un flujo que se detiene a pedir una aprobación devuelve "operación no soportada".

Errores

Los errores HTTP tienen siempre esta forma:

{ "code": "ERR_CHAT_CONVERSATION_BUSY", "error": "conversation_already_active",
  "message": "Conversation is already processing a message; …", "reqId": "…" }
HTTPcodeQué pasóQué hacer
400ERR_CHAT_INVALID_REQUESTCuerpo inválido o mensaje vacíoCorregir el pedido
401ERR_AUTH_API_KEY_REQUIREDFalta la clave, o es inválida, vencida, revocada o sin el permiso del canalRevisar la clave; todos esos casos dan el mismo error
403ERR_FEATURE_DISABLEDEl tenant no tiene acceso por APIHabilitarlo
404ERR_AGENT_NOT_FOUNDEl tenant o el agente no existenRevisar la URL
409ERR_CHAT_CONVERSATION_BUSYLa conversación todavía está procesando un mensaje anteriorEsperar la respuesta anterior y reintentar con espera creciente. El mensaje no quedó en cola
429ERR_SYS_RATE_LIMITEDSe superó el límite por minutoEsperar lo que indica Retry-After
500ERR_SYS_INTERNAL_ERRORError inesperadoReintentar con espera; si persiste, informar el reqId

El 409 aparece también cuando la conversación espera una aprobación: mientras nadie la decida, los mensajes siguientes en esa conversación se rechazan. Para una integración por API, conviene que el workflow no le pida aprobaciones al usuario.

Límites

  • 60 pedidos por minuto por tenant en REST, OpenAI y A2A, salvo que un super admin lo ajuste. El contador es por instancia del servidor.
  • Una ejecución a la vez por conversación. Para paralelizar, usá conversaciones distintas.
  • Tiempo de respuesta. Una llamada que tarda más de unos 30 segundos puede cortarse en la red de entrega aunque la ejecución siga. Para automatizaciones largas, consultá con quien opera la instalación qué URL usar.

Dónde termina

  • REST no transmite la respuesta: llega completa.
  • No hay identidad de usuario final en REST: la conversación es de la clave, y la separación entre personas depende del sessionId y del contexto que mandes.
  • Las automatizaciones son sincrónicas, sin idempotencia y sin aviso al terminar.
  • Una falla de ejecución en REST devuelve 200 con finishReason: "error".
  • El endpoint compatible con OpenAI ignora los parámetros de generación y no devuelve errores con el formato de OpenAI.
  • Las claves no se restringen por agente.
  • No hay adjuntos en REST.

Para revisar

  • La clave está en el tenant del agente, con el permiso del canal, y vive en el servidor.
  • Cada usuario o conversación tiene su propio sessionId.
  • El código revisa finishReason y maneja el 409 esperando la respuesta anterior.
  • Las automatizaciones con efectos llevan un identificador propio para descartar duplicados.
  • El workflow que se llama por API no depende de una aprobación del usuario.