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:
| Forma | Para qué | Respuesta |
|---|---|---|
| API REST | Conversar desde tu sistema, o disparar una automatización | Completa, en JSON |
| Compatible con OpenAI | Herramientas que ya hablan la API de chat de OpenAI | En streaming o completa |
| A2A | Que un agente de otra plataforma llame al tuyo | JSON-RPC |
Antes de empezar
- El tenant tiene habilitado el acceso por API (capítulo 8). Sin eso, toda llamada recibe 403.
- Creás una clave de API en el tenant del agente, con el permiso del canal que vas a usar:
channel:rest,channel:openai_compatochannel:a2a. La clave tiene la formask_….
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" }'
| Campo | Qué hace |
|---|---|
message | El mensaje del usuario. Si está, es una conversación. |
sessionId | Opcional. 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. |
locale | Idioma de la conversación. |
scope | Variables para el workflow (variables.* en las expresiones), por ejemplo { "plan": "gold" }. |
includedContext | Contexto 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.
usagesolo informatotalTokens.
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
sessionIdpor usuario o por conversación, nunca uno compartido. - Si el agente usa memoria de largo plazo, mandá el identificador de la persona en
includedContextpara 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
messagevací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 permisochannel:openai_compat. modeles la clave del agente (turnos-clinica)./v1/modelslista los agentes activos del tenant.- Se usa el último mensaje
usercomo turno. Los mensajessystemse agregan a las instrucciones. streames 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:
POSTa la misma ruta sin el sufijo, JSON-RPC, métodosSendMessageySendStreamingMessage.
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
contextIdde 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": "…" }
| HTTP | code | Qué pasó | Qué hacer |
|---|---|---|---|
| 400 | ERR_CHAT_INVALID_REQUEST | Cuerpo inválido o mensaje vacío | Corregir el pedido |
| 401 | ERR_AUTH_API_KEY_REQUIRED | Falta la clave, o es inválida, vencida, revocada o sin el permiso del canal | Revisar la clave; todos esos casos dan el mismo error |
| 403 | ERR_FEATURE_DISABLED | El tenant no tiene acceso por API | Habilitarlo |
| 404 | ERR_AGENT_NOT_FOUND | El tenant o el agente no existen | Revisar la URL |
| 409 | ERR_CHAT_CONVERSATION_BUSY | La conversación todavía está procesando un mensaje anterior | Esperar la respuesta anterior y reintentar con espera creciente. El mensaje no quedó en cola |
| 429 | ERR_SYS_RATE_LIMITED | Se superó el límite por minuto | Esperar lo que indica Retry-After |
| 500 | ERR_SYS_INTERNAL_ERROR | Error inesperado | Reintentar 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
sessionIdy 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
finishReasony 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.