External AI agent

The External AI agent node connects to your flow an AI agent that already lives outside Jelou. Jelou keeps the channel, security and the log of every turn; your agent decides the reply.

The node is being rolled out gradually; if you don’t see it on the canvas, ask your Jelou account executive to turn it on.

How to add the node

Both kinds of AI agent are added from the same entry point: the AI Agent item in the builder’s toolbar. Its behavior changes depending on how you use it:

Click: adds a normal AI Agent node: Jelou’s own AI agent.
Hover: opens a selector of external AI agent providers. Picking a provider adds an External AI agent node preconfigured for that provider.

External AI agent selector that appears when hovering over the AI Agent toolbar item

This selector works the same way as the payment gateway picker in the Payments node: you pick the provider first and the node arrives with its fields already organized.

Once added, the External AI agent node connects to the rest of your flow through its four outputs, same as any other node:

External AI agent node in a flow, connected by its four outputs to an answer message, a question, a handoff to a human and an apology message

AI Agent or external AI agent

Choose based on where the agent lives. To build one inside Jelou, use the AI Agent node (general guide).

	AI Agent	External AI agent
The agent	You build and tune it in Jelou.	Already exists and runs in production outside Jelou.
Where the logic lives	In the node’s prompt and tools.	In your system or your vendor’s.
Model	You choose it in the node.	Your agent defines it; the node doesn’t know it.
Changes	You make them in the builder.	You make them on your platform; in Jelou you only update the connection.
Security	Jelou screens the model’s answers.	Your agent applies its own; Jelou also screens its answers.

Available providers

Each provider asks for its own fields, taken directly from its console, and validates them as you type. Credentials are selected by the name of the organization secret that stores them; the secret’s value is never shown or saved in the flow.

Provider	What you need in Jelou	Where to find it in the provider’s console
Amazon Bedrock (Agents)	AWS region, agent ID, alias ID	Bedrock → Agents → your agent: the agent ID and alias ID appear in the overview; the region is your AWS console’s region.
Amazon Bedrock AgentCore	Agent runtime ARN, server protocol (HTTP or A2A)	Bedrock AgentCore → Runtimes → your runtime: the full ARN and the `ProtocolConfiguration.serverProtocol` (HTTP or A2A) appear in its detail view.
Microsoft Copilot Studio	Regional Direct Line URL or token endpoint	Copilot Studio → your agent → Channels → Direct Line: the regional URL is in `regionalchannelsettings`; if you use token exchange, the token endpoint comes from the Direct Line channel configured with “Secret” turned off.
Azure AI Foundry	Project endpoint and the agent (by ID or by name, depending on the API generation)	AI Foundry → your project → Overview: the project endpoint. The agent is identified by `agentId` (classic generation, Assistants-style) or `agentName` (Foundry generation, via the Responses API), never both.
Google Vertex AI Agent Runtime (formerly Agent Engine)	Agent resource name	Vertex AI → Agent Engine → your agent: the full resource name (`projects/.../locations/.../reasoningEngines/...`). Agents deployed with the A2A template use the A2A provider instead of this one.
Google Dialogflow CX	Agent name and language code	Dialogflow CX → your agent → settings: the full name (`projects/.../locations/.../agents/...`). The language code is used when the conversation carries no locale of its own.
Claude Managed Agents	Agent ID, environment ID	Claude Managed Agents console: the agent ID (`agent_...`) and environment ID (`env_...`) of the agent you published.
Salesforce Agentforce	Agent ID (18 characters), your org’s My Domain URL	Setup → Agentforce Agents: the `BotDefinition` Id. The URL must be your My Domain URL (`https://yourorg.my.salesforce.com`), never the `lightning.force.com` one. Only agents that aren’t of type “Agentforce (Default)” are supported.
OpenAI (Responses API)	Prompt ID (format `pmpt_...`)	OpenAI platform → Prompts: the ID of the reusable prompt that packages instructions, model and tools. You can optionally pin a prompt version.
LangGraph	Deployment URL and assistant ID	LangGraph Platform (LangSmith Deployments) → your deployment: the deployment URL and the assistant ID (UUID recommended, or the graph name).
Dify (preset over custom HTTP)	Workspace URL and credential	Dify → your app → API Access: the base URL and the workspace’s API key. Jelou calls `POST /v1/chat-messages` for you.
n8n (preset over custom HTTP)	Webhook URL	n8n → your workflow → Webhook node: the production webhook URL.
A2A (Agent-to-Agent)	Agent Card URL	Your A2A agent’s server: the public URL where it publishes its Agent Card (`.well-known/agent-card.json` or the path you define).
HTTP (Jelou turn contract)	Agent URL	Your own server: the endpoint that already implements the Jelou turn contract (see the section below).
Custom HTTP	Agent URL, request body and response paths	Your own server: any endpoint that accepts JSON, even if it doesn’t speak the Jelou turn contract.

One task or several turns

When you configure the node, you choose how it interacts with your agent:

One task: the node sends the task once, receives the answer and exits the node.
Several turns: the node keeps the conversation going with the agent, message by message, until the agent ends it or hands it off. While the agent answers without ending the conversation, the node doesn’t take any output: it delivers the messages to the user and waits for their next message to continue with the agent.

External AI agent node configuration with the Several turns interaction selected

Example: one task

User:   I want to know the status of my order EJ-48213
Agent:  Your order EJ-48213 is on its way and arrives tomorrow before 6:00 PM.

The node receives the answer, delivers it to the user and exits through Answered. There’s no second round with the agent: any later message from the user no longer goes through this node.

Example: several turns

User:   I want a refund for my last purchase
Agent:  Sure, to verify your refund request I need the order number.
        Could you share it?

[the node delivers the message to the user and waits for their reply]

User:   My order number is EJ-48213
Agent:  Done, I found your order EJ-48213. The $45.00 refund was approved
        and will show up in 3 to 5 business days.

The node stays active between the first and second messages: it doesn’t take any output until the agent ends the conversation. Only then does it exit through Answered.

Node outputs

The External AI agent node has four outputs:

Output	Fires when
Answered	In one task, the agent answered. In several turns, the agent ended the conversation.
Needs more information	Only in one task: the agent paused to wait for an action or additional input. In several turns this is treated as a normal answer and the node keeps waiting for the user; it’s not an output in that mode.
Hand off to an operator	The agent asked to hand the conversation to a human, after delivering its messages.
Something went wrong	The agent failed, rejected the credential, returned an invalid response, or the session expired from a timeout.

Comparison of two External AI agent nodes, one configured over A2A and one over Amazon Bedrock Agents, showing the same four outputs

Connect each output to whatever should happen in your flow. A typical pattern:

Answered → the agent’s message was already delivered; continue the flow or end it.
Needs more information → a question node that collects the missing piece and calls the agent again.
Hand off to an operator → your handoff node to the Inbox.
Something went wrong → an apology message and, if it applies, a retry or a handoff to an operator.

The “Save the answer in” variable

Every External AI agent node has a Save the answer in field (agentReply by default) where the agent’s answer is written. You can reference it in later nodes of the flow with the usual variable syntax, for example {{$context.agentReply}} in a message node or a condition. If the agent also sends structured data (for example through custom HTTP’s data path, or a variables_set signal), that data is written as individual context variables of the flow, available to any later node.

Authentication and organization secrets

Each provider supports one or more credential schemes, depending on what its API accepts:

Scheme	What the secret holds
`api_key_header`	A value sent in a header with a configurable name.
`bearer`	A token sent as `Authorization: Bearer ...`.
`oauth2_client_credentials`	The client secret; Jelou exchanges a token with your OAuth2 endpoint before each call (or reuses one that’s still valid).
`aws_sigv4_keys`	A JSON object `{accessKeyId, secretAccessKey, sessionToken?}`; Jelou signs the request with SigV4.
`aws_sigv4_role`	Doesn’t hold a key: Jelou assumes the AWS role you point to, using an external id stored as a secret.
`google_service_account`	The service account’s full JSON key.
`direct_line_secret`	Copilot Studio’s Direct Line channel secret.
`mtls`	Combines with your company’s mTLS certificate (see below); it’s independent of the other schemes.
`none`	No credential; only valid when your agent doesn’t require authentication.

In every case, the node only stores the organization secret’s name, never its value. The secret is resolved at call time and is never shown or saved in the flow.

Enterprise options for custom HTTP

When your agent uses HTTP (Jelou turn contract) or custom HTTP, your company may have access to additional options:

Connection tab of the External AI agent node with the agent URL, authentication, mTLS certificate, HMAC signing and fixed headers

Option	What it’s for
Request signing (HMAC)	Signs every request with a shared secret, so your agent can verify it came from Jelou.
Static headers	Adds fixed headers your agent expects on every call. Sensitive headers like `authorization`, `cookie`, `host` or `x-jelou-signature` aren’t allowed, nor values with variables (`{{...}}`). Up to 10 headers.
Pre-request and post-response scripts	Runs a script before sending the request or after receiving the response, in the same secure sandbox the API node uses.
OAuth	Authentication via OAuth2 client credentials.
mTLS	Mutual TLS with your company’s client certificate, independent of the credential: you can combine OAuth and mTLS at the same time.
Retries	Up to 3 attempts; only timeouts, rate limits and server errors are retried, never a rejected request.
Turn timeout	How long the node waits for the agent’s answer before taking the error output. Default 25 seconds, up to a maximum of 120 seconds.

Advanced tab of the External AI agent node with the turn timeout and the number of attempts

These options are available on Enterprise plans. If you don’t see them on your node, ask your Jelou account executive to check your plan.

HMAC signing: what’s signed and how to verify it

When you turn on request signing, Jelou computes an HMAC-SHA256 over the exact request body (the same bytes sent) using the secret you choose, and sends it in a header:

Field	Default value	Notes
Header	`X-Jelou-Signature`	Configurable.
Encoding	Hexadecimal	Also supports Base64.
What’s signed	Just the body (`body`)	Also supports `timestamp.body`, which signs `"{timestamp}.{body}"` and adds the Unix timestamp in a second header you name.

Your own server can verify the signature like this (Node.js, body-only variant):

const crypto = require("crypto");

function isValidJelouSignature(rawBody, signatureHeader, sharedSecret) {
  const expected = crypto
    .createHmac("sha256", sharedSecret)
    .update(rawBody, "utf8")
    .digest("hex");
  const a = Buffer.from(signatureHeader || "", "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody must be the raw body exactly as it arrived, before parsing JSON
const valid = isValidJelouSignature(rawBody, req.headers["x-jelou-signature"], SHARED_SECRET);

Always verify against the request’s raw body, before your framework parses it into JSON. Re-serializing the parsed JSON can change property order or spacing and make the signature not match even though the content is the same.

The Task field accepts variables. To send the user’s message to the agent, use {{$message.text}}: it holds the text of the message that reached the flow. {{$input.message}} is not a message variable: $input only holds the data your flow collected (for example, with an Input node), so it comes out empty when the node runs from a chat message.

Pre-request and post-response scripts

Scripts run in the same secure sandbox the API node uses, and only apply to HTTP providers. They’re configured in the node’s Transform tab, next to the task that’s sent and the variable where the answer is saved:

Transform tab of the External AI agent node with the Task field, the Save the answer in variable, and the Pre Request / Post Request editor

Pre-request script: $context.get("agentRequest") holds { task, sessionId, body, headers }. The script can change agentRequest.body or agentRequest.headers before Jelou sends the request. For example, to wrap the body in your company’s own envelope:

const request = $context.get("agentRequest");

$context.set("agentRequest.body", {
  header: {
    channel: "whatsapp",
    company: "Banco Ejemplo",
  },
  data: request.body,
});

Post-response script: $context.get("agentResponse") holds { status, body }. The script must leave in agentResponse.body the object the response mapping then reads (the textPath, dataPath, sessionIdPath paths, etc.).

const response = $context.get("agentResponse");

$context.set("agentResponse.body", response.body.data);

An error thrown by the script fails the turn through the node’s error output. Script changes never touch the flow’s own variables: they only change what Jelou sends or reads for this call.

Reply later (acknowledges, replies later)

Some external agents don’t answer inside the same call: they acknowledge that they received the message and send their answer later, on their own. For that case, the External AI agent node has an optional mode. It is off by default, so an existing node behaves exactly as before. The How the agent replies field appears on the Connection tab when the connection type is HTTP (Jelou turn contract) or Custom HTTP and the interaction is Several turns. It has two options:

In the same response (default): the agent answers inside the same call, as before.
Acknowledges, replies later: the agent acknowledges with any 2xx response. Jelou delivers nothing from the acknowledgement body and leaves the node waiting for the user’s next message, with the same session inactivity time. That message is forwarded to the agent within the same execution.

Connection tab of the External AI agent node with How the agent replies set to Acknowledges, replies later, the failure output notice, the token over the mTLS certificate switch and the signature prefix

With Custom HTTP, the Reply text path is no longer required in this mode, because no text from the body is delivered.

When the conversation ends

On the Advanced tab, these two optional fields appear only in this mode:

Field that ends the conversation: the path of the field in the acknowledgement body, for example status, data.state or items[0].s (up to 200 characters).
Values that end the conversation: 1 to 20 distinct values, separated by commas. It accepts text, integers and true or false. When the field holds one of them, the conversation ends and the flow continues through the Answered output.

Advanced tab of the External AI agent node with the field that ends the conversation and its values

Outputs you must connect

Always connect the Something went wrong output: it is the one the node takes when the wait expires without the user writing. Without that connection you can’t publish the flow.
Connect the Answered output only if you defined the field that ends the conversation. Without those fields it isn’t used.
The Hand off to an operator output is not required.

The node shows a warning on the canvas while a needed connection is missing.

When the wait expires, the flow continues through Something went wrong and Jelou sends the user no message. Connect that output to a silent End, with no error message.

Non-text messages

When the user sends an image, audio, a document, a WhatsApp Flow response, a button, a list or a location, the agent no longer receives an empty task. The task arrives as [type] caption (or just [type]), and the request includes an input.inbound object with the type, text, caption, file type and message id. Sensitive data is not sent by default. On the Transform tab, the Sensitive non-text message data the agent receives field lets you choose which to add:

File URL
Button or list reply
WhatsApp Flow response
Location

Check only what your agent needs: they can contain personal information. This applies to any connection type. Plain text and titled buttons are sent exactly as before.

Transform tab of the External AI agent node with the sensitive non-text message data the agent receives

Signature prefix

Some agents expect the HMAC signature with text in front of it, for example sha256= followed by the value. Under Sign requests, the Signature prefix (e.g. sha256=) field adds that literal text before the signature value. It accepts 1 to 32 characters: letters, digits and _ = . : / + -; spaces and templates are not allowed. The timestamp header is never prefixed. It applies to HTTP (Jelou turn contract) and Custom HTTP, and on every retry.

OAuth2 token over mTLS

If your agent uses OAuth2 client credentials and requires the client certificate to request the token too, choose an mTLS certificate and turn on Also request the token with the mTLS certificate. The token request goes over the same certificate as the agent call. The token URL must still be https. The switch appears only with that authentication and a chosen certificate; if you remove the certificate, it turns off. When off, the token is requested as usual.

The Jelou turn contract

When you pick HTTP (Jelou turn contract), your server receives and answers with a fixed shape Jelou already knows how to read, with no manual path mapping needed. This is what Jelou actually sent and received in a real test against an agent server, with the HMAC signature redacted:

{
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "accept": "application/json",
    "channel-id": "whatsapp",
    "organization-id": "org-001",
    "x-jelou-signature": "<redacted>"
  },
  "body": {
    "event": "message",
    "endpoint": "agent",
    "text": "I want a refund for my last purchase",
    "session": "",
    "user": "usr_9f3ka2"
  }
}

{
  "data": {
    "reply": "Sure, to verify your refund request I need the order number. Could you share it?",
    "session": "sess_ej3nc9dk2m"
  }
}

On the second round of the same conversation, the agent already knows the order number and the node delivers the conversation as ended:

Agent's second answer

{
  "data": {
    "reply": "Done, I found your order EJ-48213. The $45.00 refund was approved and will show up in 3 to 5 business days.",
    "session": "sess_ej3nc9dk2m"
  }
}

If your agent doesn’t speak exactly this contract, use custom HTTP: there you define the shape of the body that gets sent and the paths where Jelou should read the answer text, the structured data and the session id, in the node’s Transform tab.

Test connection

Before publishing your flow, use the Test connection button on the node’s Connection tab to check that everything is configured correctly, without waiting for a real user to trigger the node. The test runs a chain of checks, stopping at the first one that fails:

Check	What it verifies
Contract	The node’s configuration satisfies the expected schema.
Provider	The chosen provider type is available.
mTLS certificate	If you configured mTLS, that the certificate loads and belongs to your company.
Secret	The referenced organization secret exists and can be read.
Token / access	The credential actually issues access (for example, that the OAuth2 exchange or AWS signing work).
Agent Card (A2A only)	The Agent Card is reachable and declares an HTTPS interface compatible with the configured credential.
Rejects anonymous	The agent refuses a call without the credential (where the scheme applies).
Answers a task	The agent answers a test task within the contract, within the timeout.
Session (several turns only)	The agent issues a session id for the next turn.

If every check passes, you see a confirmation:

Test connection result when every check passes, with the message 'Connection OK'

If one fails, Jelou tells you which one and why, so you can fix the configuration before publishing. For example, when the agent rejects the credential:

Test connection result when a check fails, with the detail of what failed and why

Security

Credentials never leave your organization’s secrets. The node only stores the secret’s name; its value is never shown or saved in the flow.
HTTPS only. Jelou doesn’t call internal or private addresses.
Your agent’s answers go through Jelou’s same security checks as an AI Agent’s answers, before they reach the user: they’re screened like any other outbound message, with nothing extra to configure on the node.

Troubleshooting

The node always exits through 'Something went wrong'

Check Test connection first: it almost always points to whether the problem is the certificate, the secret, the token or the agent itself. The most common causes are an expired or revoked credential, a URL that stopped responding, or an agent answer that isn’t valid JSON or is missing the field expected at the configured path.

The turn takes a long time and ends in an error

The node waits at most the configured turn timeout (25 seconds by default, up to 120 as a maximum). If your agent needs more time, raise the limit in the Advanced tab; if the agent fails intermittently, check retries: they only apply to timeouts, rate limits (HTTP 429) and server errors (5xx), never a request the agent explicitly rejected.

The HMAC signature doesn't match on my server

Always verify against the request’s raw body, before parsing the JSON (see the HMAC signing section above). Also confirm you’re using the same secret, the same encoding (hexadecimal or Base64), and, if you turned on timestamp.body, that you’re signing "{timestamp}.{body}" and not just the body.

'Needs more information' doesn't show up in several turns

That’s expected: that output only exists in one task mode. In several turns, when the agent needs an extra piece of information it simply asks for it as a normal message and the node keeps waiting for the user’s reply, without taking any output.

I don't see the External AI agent node or the provider selector

The node is being rolled out gradually. Ask your Jelou account executive to turn it on for your company.

I don't see the Enterprise options (HMAC, static headers, scripts, mTLS)

These options are available on Enterprise plans. Ask your Jelou account executive to check your plan.

Availability

The External AI agent node is being rolled out gradually. If you don’t see it on your project’s canvas, contact your Jelou account executive to request its activation.

AI Agent node

General configuration of the AI Agent node.

Getting Started

Developer

Jelou CLI

Outbound Messaging

Inbox

Marketplace

Channels

Configuration

Billing

How to add the node

AI Agent or external AI agent

Available providers

One task or several turns

Example: one task

Example: several turns

Node outputs

The “Save the answer in” variable

Authentication and organization secrets

Enterprise options for custom HTTP

HMAC signing: what’s signed and how to verify it

Pre-request and post-response scripts

Reply later (acknowledges, replies later)

When the conversation ends

Outputs you must connect

Non-text messages

Signature prefix

OAuth2 token over mTLS

The Jelou turn contract

Test connection

Security

Troubleshooting

Availability

AI Agent node

​How to add the node

​AI Agent or external AI agent

​Available providers

​One task or several turns

​Example: one task

​Example: several turns

​Node outputs

​The “Save the answer in” variable

​Authentication and organization secrets

​Enterprise options for custom HTTP

​HMAC signing: what’s signed and how to verify it

​Pre-request and post-response scripts

​Reply later (acknowledges, replies later)

​When the conversation ends

​Outputs you must connect

​Non-text messages

​Signature prefix

​OAuth2 token over mTLS

​The Jelou turn contract

​Test connection

​Security

​Troubleshooting

​Availability

AI Agent node

How to add the node

AI Agent or external AI agent

Available providers

One task or several turns

Example: one task

Example: several turns

Node outputs

The “Save the answer in” variable

Authentication and organization secrets

Enterprise options for custom HTTP

HMAC signing: what’s signed and how to verify it

Pre-request and post-response scripts

Reply later (acknowledges, replies later)

When the conversation ends

Outputs you must connect

Non-text messages

Signature prefix

OAuth2 token over mTLS

The Jelou turn contract

Test connection

Security

Troubleshooting

Availability