External AI agent

The External AI agent node delegates the conversation to an agent you host outside Jelou. With the HTTP (Jelou contract) provider (http_sync), Jelou sends a POST to your agent’s URL on every turn and expects a JSON reply in an exact format. This guide describes that format, with examples you can copy.

The same format applies to an HTTP agent deployed on Amazon Bedrock AgentCore: what your handler returns is what Jelou validates.

What your agent receives

Jelou sends a POST with content-type: application/json, the credential headers you configured and, if enabled, the request signature. The body looks like this:

{
  "turnId": "trn_01J8A7K2M4XQ",
  "inputId": "inp_9f3c2a71",
  "conversation": { "key": "wa:593999999999", "channel": "whatsapp", "locale": "es-EC" },
  "user": { "ref": "usr_8d41c0aa" },
  "input": { "parts": [{ "type": "text", "text": "Hola, quiero saber mi saldo" }] },
  "context": { "variables": { "segmento": "premium" } },
  "deadlineMs": 25000,
  "trace": { "executionId": "exec_5b2e", "workflowId": "64083", "nodeId": "n_agent" },
  "interaction": "single_task"
}

Field	Description
`turnId`	Turn identifier, `trn_` followed by letters or digits.
`inputId`	Identifier of the user’s message (1 to 128 characters).
`conversation`	`key`, `channel` (`whatsapp`, `facebook`, `instagram`, `web`, `email`, `sms`, `other`) and an optional `locale`.
`user`	Pseudonymous `ref` (`usr_...`). `phone`, `name`, `email` and `legalId` arrive only if you allow them in `inputMapping.sendUserFields`.
`input.parts`	1 to 10 parts. A text message is `{"type":"text","text":"..."}`.
`input.inbound`	Only for non-text messages (image, audio, location, Flow reply).
`context.variables`	Only the workflow variables you list in `inputMapping.variables`.
`deadlineMs`	Milliseconds your agent has to answer (1000 to 120000).
`trace`	`executionId` and, optionally, `workflowId` and `nodeId`.
`interaction`	`single_task` or `multi_turn`.

What your agent must reply

Reply with HTTP 200 and JSON. The reply is strict: any field not in this table is rejected.

Field	Required	Description
`status`	Yes	`completed`, `action_required`, `failed`, `timed_out` or `blocked`.
`outputs`	Yes	Array of up to 20 parts. Use `[]` when there is nothing to say.
`signals`	No	Up to 5 signals. Jelou uses `[]` when omitted.
`turnId`	No	When omitted Jelou uses the request’s. When sent it must equal the one received.
`provider`	No	Jelou fills in `provider.kind` for you.
`timing`	No	Jelou measures `timing.latencyMs` for you.
`usage`	No	`inputTokens`, `outputTokens` and `reportedBy: "provider"`.
`error`	Only with `failed` or `timed_out`	`code`, `retryable` and an optional `message` (up to 500 characters). Not allowed with any other `status`.

Rules by status: failed and timed_out require error and outputs: []; blocked requires outputs: []; action_required requires an action_required signal.

The names must be exactly status and outputs. Jelou does not accept aliases such as output, messages, result or turnStatus.

`outputs` parts

`type`	Fields
`text`	`text` required, 1 to 4096 characters. Split longer answers into several text parts.
`choices`	`choices` required, 1 to 10 items with `id` and `label` (label up to 24 characters). Optional `text` up to 1024.
`card`	`title` required (up to 80). Optional: `body` (1024), `imageUrl` (https) and `actions` (up to 3, with `label` and `url` or `choiceId`).
`media`	`url` (https) and `mediaType` (for example `image/png`); optional `caption`.
`data`	`data`, an object.

Signals (`signals`)

`type`	Effect
`handoff_requested`	Hands the conversation to a person. Optional `reason` (up to 500) and `queue`. The node leaves through `agent_handoff`.
`conversation_ended`	Marks the conversation as finished.
`variables_set`	`variables`, an object with 1 to 30 keys stored in the node variable.
`action_required`	`actionId`, `name` and optional `arguments`.
`action_selected`	`name` and optional `data`.

Example replies

Minimal reply

{ "status": "completed", "outputs": [{ "type": "text", "text": "Hola, con gusto te ayudo con tu saldo." }] }

It is equivalent to sending the full form:

{
  "turnId": "trn_01J8A7K2M4XQ",
  "status": "completed",
  "outputs": [{ "type": "text", "text": "Hola, con gusto te ayudo con tu saldo." }],
  "signals": [],
  "provider": { "kind": "http_sync" },
  "timing": { "latencyMs": 0 }
}

With choices

{
  "status": "completed",
  "outputs": [
    { "type": "choices", "text": "Que necesitas?", "choices": [{ "id": "saldo", "label": "Ver saldo" }, { "id": "asesor", "label": "Hablar con asesor" }] }
  ]
}

Hand off to an agent

{
  "status": "completed",
  "outputs": [{ "type": "text", "text": "Te comunico con un asesor." }],
  "signals": [{ "type": "handoff_requested", "reason": "El cliente pidio hablar con una persona" }]
}

Save variables and end

{
  "status": "completed",
  "outputs": [{ "type": "text", "text": "Listo, registre tu solicitud. Gracias por escribirnos." }],
  "signals": [
    { "type": "variables_set", "variables": { "ticket": "A-1042", "categoria": "reclamo" } },
    { "type": "conversation_ended" }
  ]
}

Error on the agent side

The node leaves through agent_failed.

{
  "status": "failed",
  "outputs": [],
  "error": { "code": "provider_error", "retryable": true, "message": "El sistema de saldos no respondio" }
}

HTTP status codes

If your agent answers with a non-2xx status the turn fails: 401 and 403 as auth, 404 and 410 as not_active, 429 as rate_limited, and 408, 504 or 5xx as provider_error. 429 and 5xx are retried if you configured retries.

What happens when the reply breaks the format

The turn fails with code malformed and the message says what to fix, using field names and paths only (never values). For example:

response does not satisfy AgentTurnResult: missing status; missing outputs; unknown field output (did you mean outputs?); unknown field turnStatus (did you mean status?)

You can read the message in externalAgent.error.message of the node result in the execution or in the test.

Example: HTTP handler on Amazon Bedrock AgentCore (Python)

It reads the user’s message from input.parts and returns a valid reply. The function’s return value is the JSON body of the response.

from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()


def answer_for(text):
    if "asesor" in text.lower():
        return {
            "status": "completed",
            "outputs": [{"type": "text", "text": "Te comunico con un asesor."}],
            "signals": [{"type": "handoff_requested", "reason": "El cliente pidio un asesor"}],
        }
    return {
        "status": "completed",
        "outputs": [{"type": "text", "text": "Recibi tu mensaje: " + text[:500]}],
    }


@app.entrypoint
def invoke(payload, context=None):
    parts = payload.get("input", {}).get("parts", [])
    text = " ".join(p.get("text", "") for p in parts if p.get("type") == "text").strip()
    try:
        result = answer_for(text)
    except Exception:
        return {
            "status": "failed",
            "outputs": [],
            "error": {"code": "provider_error", "retryable": True, "message": "El agente no pudo responder"},
        }
    result["turnId"] = payload["turnId"]
    return result


if __name__ == "__main__":
    app.run()

Getting Started

Developer

Jelou CLI

Outbound Messaging

Inbox

Marketplace

Channels

Configuration

Billing

What your agent receives

What your agent must reply

`outputs` parts

Signals (`signals`)

Example replies

Minimal reply

With choices

Hand off to an agent

Save variables and end

Error on the agent side

HTTP status codes

What happens when the reply breaks the format

Example: HTTP handler on Amazon Bedrock AgentCore (Python)

​What your agent receives

​What your agent must reply

​outputs parts

​Signals (signals)

​Example replies

​Minimal reply

​With choices

​Hand off to an agent

​Save variables and end

​Error on the agent side

​HTTP status codes

​What happens when the reply breaks the format

​Example: HTTP handler on Amazon Bedrock AgentCore (Python)

What your agent receives

What your agent must reply

`outputs` parts

Signals (`signals`)

Example replies

Minimal reply

With choices

Hand off to an agent

Save variables and end

Error on the agent side

HTTP status codes

What happens when the reply breaks the format

Example: HTTP handler on Amazon Bedrock AgentCore (Python)