Calling an agent from your system — Operator manual | AI Agent Builder

Calling an agent from your system

The REST API to converse and trigger automations, the OpenAI-compatible endpoint, A2A, keys and the errors your code has to handle.

7 min read · Updated November 13, 2026

This guide is for whoever writes the integration: the backend of Clínica del Sol's patient portal asking the scheduling agent something, or a system that triggers an agent when something happens. It explains the contracts as they are today, edges included.

There are three ways to call an agent:

WayForResponse
REST APIConversing from your system, or triggering an automationComplete, as JSON
OpenAI-compatibleTools that already speak OpenAI's chat APIStreamed or complete
A2ALetting an agent on another platform call yoursJSON-RPC

Before you start

  1. The tenant has API access enabled (chapter 8). Without it, every call gets a 403.
  2. Create an API key in the agent's tenant, with the permission for the channel you will use: channel:rest, channel:openai_compat or channel:a2a. The key looks like sk_….

Two things to keep in mind about keys:

  • A key only works for its own tenant. A Nortelink key does not reach Clínica del Sol's agents: the key must be created in the clinic's tenant.
  • A key works for every agent in the tenant. If you need to separate access per agent, use separate tenants.

The key goes in the x-api-key header (or Authorization: Bearer sk_…). It is a server secret: do not put it on a web page; that is what the widget and its restricted public key are for.

REST API: conversing

The exact URL is in the agent's Channels tab, on the REST card. It has this shape:

POST {API URL}/api/rest/{tenant}/{agent}

On the Synaptic Links installation, {API URL} is https://ai.synapticlinks.com.ar/api, so the path has /api twice. That is correct: copy it as is.

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": "Are there general practice appointments on Tuesday?", "sessionId": "patient-4821", "locale": "en" }'
FieldWhat it does
messageThe user's message. If present, it is a conversation.
sessionIdOptional. An identifier of yours (for example, the patient's) or the sessionId the previous response returned. Messages with the same value form the same conversation.
localeThe conversation language.
scopeVariables for the workflow (variables.* in expressions), for example { "plan": "gold" }.
includedContextEntity context, the same a page sends with the widget. If its payload has customerId or entityKey, it is used for per-entity memory (chapter 10).

The response, with HTTP 200:

{
  "sessionId": "8f0c2a1e-…",
  "message": "Yes, on Tuesday there are slots at 9:30 and 11:30 at Sede Centro.",
  "finishReason": "stop",
  "provider": "openai",
  "model": "gpt-…",
  "latencyMs": 2140,
  "usage": { "promptTokens": 0, "completionTokens": 0, "totalTokens": 912 },
  "stepExecutions": [ … ]
}
  • Field names are camelCase.
  • The response arrives complete: this channel does not stream while it is generated.
  • usage only reports totalTokens.

Always check finishReason. If the run failed —including when the balance is exhausted or a consumption limit is reached— the API still answers 200, with finishReason: "error" and a message that may be empty. Your code must not show an empty message to the user as if it were an answer.

How the conversation is built

Without sessionId, each call starts a new conversation. With sessionId, the platform groups messages with that value for that key. As with messaging channels, after 24 hours without messages a new session starts, and the response carries a different sessionId.

The API does not know who your user is: for the platform, every conversation belongs to the key. So:

  • Use one sessionId per user or per conversation, never a shared one.
  • If the agent uses long-term memory, send the person's identifier in includedContext so memories are not mixed between users.

REST API: triggering an automation

The same URL, without message, triggers the agent with data instead of a message. The whole body, except sessionId and locale, reaches the workflow as trigger.*:

{ "event": "appointment_cancelled", "appointment_id": "T-99812", "location": "Sede Norte" }
  • It is synchronous: the call waits for the workflow to finish.
  • If the workflow has a Respond node, the HTTP response uses the status, headers and body that node defines. If not, it returns the standard body with an empty message.
  • There is no idempotency: if you retry a call that actually ran, the workflow runs twice. If the workflow has side effects, include an identifier of your own and discard duplicates in the workflow or in your system.
  • There is no notification when it finishes. Outbound webhooks (chapter 5) report platform events, not the result of a run.

OpenAI-compatible

For tools that already use the OpenAI SDK:

POST {API URL}/v1/chat/completions
GET  {API URL}/v1/models
  • The key goes as Authorization: Bearer sk_…, with the channel:openai_compat permission.
  • model is the agent key (turnos-clinica). /v1/models lists the tenant's active agents.
  • The last user message is used as the turn. system messages are added to the instructions.
  • stream is true by default.
  • To make several calls one conversation, send extra_metadata.session_id. Without it, each call starts from scratch.

temperature, max_tokens, tools, n and stop are ignored: the agent uses its own configuration. Errors do not come in OpenAI's format but in the platform's (below), and in streaming mode a run error ends as an empty answer.

A2A

For agents on other platforms that speak the A2A protocol:

  • Agent card: GET {API URL}/api/a2a/{tenant}/{agent}/.well-known/agent-card.json.
  • Messages: POST to the same path without the suffix, JSON-RPC, methods SendMessage and SendStreamingMessage.

The card is not public: it requires Authorization: Bearer with a key with the channel:a2a permission. The agent must also have A2A enabled in its Channels tab, with a name and description.

  • Only text parts are accepted, up to 16,000 bytes.
  • To continue a conversation, send the contextId from the previous response.
  • A flow that stops to ask for an approval returns "unsupported operation".

Errors

HTTP errors always have this shape:

{ "code": "ERR_CHAT_CONVERSATION_BUSY", "error": "conversation_already_active",
  "message": "Conversation is already processing a message; …", "reqId": "…" }
HTTPcodeWhat happenedWhat to do
400ERR_CHAT_INVALID_REQUESTInvalid body or empty messageFix the request
401ERR_AUTH_API_KEY_REQUIREDThe key is missing, or invalid, expired, revoked or lacks the channel permissionCheck the key; all those cases return the same error
403ERR_FEATURE_DISABLEDThe tenant has no API accessEnable it
404ERR_AGENT_NOT_FOUNDThe tenant or agent does not existCheck the URL
409ERR_CHAT_CONVERSATION_BUSYThe conversation is still processing a previous messageWait for the previous response and retry with increasing backoff. The message was not queued
429ERR_SYS_RATE_LIMITEDThe per-minute limit was exceededWait for what Retry-After says
500ERR_SYS_INTERNAL_ERRORUnexpected errorRetry with backoff; if it persists, report the reqId

The 409 also appears when the conversation is waiting for an approval: until someone decides it, further messages in that conversation are rejected. For an API integration, the workflow should not ask the user for approvals.

Limits

  • 60 requests per minute per tenant on REST, OpenAI and A2A, unless a super admin changes it. The counter is per server instance.
  • One run at a time per conversation. To parallelise, use separate conversations.
  • Response time. A call that takes more than about 30 seconds may be cut by the delivery network even though the run continues. For long automations, ask whoever operates the installation which URL to use.

Where it stops

  • REST does not stream the response: it arrives complete.
  • There is no end-user identity on REST: the conversation belongs to the key, and separating people depends on the sessionId and the context you send.
  • Automations are synchronous, with no idempotency and no notification when they finish.
  • A run failure on REST returns 200 with finishReason: "error".
  • The OpenAI-compatible endpoint ignores generation parameters and does not return errors in OpenAI's format.
  • Keys are not restricted per agent.
  • There are no attachments on REST.

To check

  • The key is in the agent's tenant, with the channel permission, and lives on the server.
  • Each user or conversation has its own sessionId.
  • The code checks finishReason and handles the 409 by waiting for the previous response.
  • Automations with side effects carry an identifier of their own to discard duplicates.
  • The workflow called through the API does not depend on a user approval.