Agente de IA externo

El nodo Agente de IA externo delega la conversación a un agente que tú alojas fuera de Jelou. Con el proveedor HTTP (contrato de Jelou) (http_sync), Jelou hace un POST a la URL de tu agente en cada turno y espera una respuesta JSON con un formato exacto. Esta guía describe ese formato, con ejemplos que puedes copiar.

Este formato también aplica a un agente HTTP desplegado en Amazon Bedrock AgentCore: lo que tu handler devuelve es lo que Jelou valida.

Qué recibe tu agente

Jelou envía un POST con content-type: application/json, las cabeceras de la credencial que configuraste y, si lo activaste, la firma de la solicitud. El cuerpo es este:

{
  "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"
}

Campo	Descripción
`turnId`	Identificador del turno, `trn_` seguido de letras o números.
`inputId`	Identificador del mensaje del usuario (1 a 128 caracteres).
`conversation`	`key`, `channel` (`whatsapp`, `facebook`, `instagram`, `web`, `email`, `sms`, `other`) y `locale` opcional.
`user`	`ref` seudónimo (`usr_...`). `phone`, `name`, `email` y `legalId` llegan solo si los permites en `inputMapping.sendUserFields`.
`input.parts`	De 1 a 10 partes. Un mensaje de texto es `{"type":"text","text":"..."}`.
`input.inbound`	Solo en mensajes que no son texto (imagen, audio, ubicación, respuesta de Flow).
`context.variables`	Solo las variables del flujo que listes en `inputMapping.variables`.
`deadlineMs`	Milisegundos que tiene tu agente para responder (1000 a 120000).
`trace`	`executionId` y, opcionalmente, `workflowId` y `nodeId`.
`interaction`	`single_task` o `multi_turn`.

Qué debe responder tu agente

Responde con HTTP 200 y un JSON. La respuesta es estricta: cualquier campo que no esté en esta tabla se rechaza.

Campo	Obligatorio	Descripción
`status`	Sí	`completed`, `action_required`, `failed`, `timed_out` o `blocked`.
`outputs`	Sí	Arreglo de hasta 20 partes. Usa `[]` si no hay nada que decir.
`signals`	No	Hasta 5 señales. Si lo omites, Jelou usa `[]`.
`turnId`	No	Si lo omites, Jelou usa el del request. Si lo envías, debe ser idéntico al recibido.
`provider`	No	Jelou completa `provider.kind` por ti.
`timing`	No	Jelou mide `timing.latencyMs` por ti.
`usage`	No	`inputTokens`, `outputTokens` y `reportedBy: "provider"`.
`error`	Solo con `failed` o `timed_out`	`code`, `retryable` y `message` opcional (hasta 500 caracteres). No se permite con otro `status`.

Reglas por estado: failed y timed_out exigen error y outputs: []; blocked exige outputs: []; action_required exige una señal action_required.

Los nombres deben ser exactamente status y outputs. Jelou no acepta alias como output, messages, result o turnStatus.

Partes de `outputs`

`type`	Campos
`text`	`text` obligatorio, de 1 a 4096 caracteres. Divide respuestas más largas en varias partes de texto.
`choices`	`choices` obligatorio, de 1 a 10 elementos `id` y `label` (la etiqueta admite hasta 24 caracteres). `text` opcional hasta 1024.
`card`	`title` obligatorio (hasta 80). Opcionales: `body` (1024), `imageUrl` (https) y `actions` (hasta 3, con `label` y `url` o `choiceId`).
`media`	`url` (https) y `mediaType` (por ejemplo `image/png`); `caption` opcional.
`data`	`data`, un objeto.

Señales (`signals`)

`type`	Efecto
`handoff_requested`	Pasa la conversación a una persona. Campos opcionales: `reason` (hasta 500) y `queue`. El nodo sale por `agent_handoff`.
`conversation_ended`	Indica que la conversación terminó.
`variables_set`	`variables`, un objeto de 1 a 30 claves que se guarda en la variable del nodo.
`action_required`	`actionId`, `name` y `arguments` opcional.
`action_selected`	`name` y `data` opcional.

Respuestas de ejemplo

Respuesta mínima

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

Es equivalente a enviar la forma completa:

{
  "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 }
}

Con botones de elección

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

Pasar a un asesor

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

Guardar variables y terminar

{
  "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 del lado del agente

El nodo sale por agent_failed.

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

Códigos HTTP

Si tu agente responde con un código distinto de 2xx, el turno falla: 401 y 403 como auth, 404 y 410 como not_active, 429 como rate_limited y 408, 504 o 5xx como provider_error. 429 y 5xx se reintentan si configuraste reintentos.

Qué pasa si la respuesta no cumple el formato

El turno falla con el código malformed y el mensaje indica qué corregir, solo con nombres de campos y rutas (nunca con valores). Por ejemplo:

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

Puedes ver el mensaje en externalAgent.error.message del resultado del nodo en la ejecución o en la prueba.

Ejemplo: handler HTTP en Amazon Bedrock AgentCore (Python)

Lee el mensaje del usuario desde input.parts y devuelve una respuesta válida. El resultado de la función es el cuerpo JSON de la respuesta.

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()

Empezando

Desarrollador

Jelou CLI

Mensajería Outbound

Bandeja de entrada

Marketplace

Canales

Configuración

Facturación

Qué recibe tu agente

Qué debe responder tu agente

Partes de `outputs`

Señales (`signals`)

Respuestas de ejemplo

Respuesta mínima

Con botones de elección

Pasar a un asesor

Guardar variables y terminar

Error del lado del agente

Códigos HTTP

Qué pasa si la respuesta no cumple el formato

Ejemplo: handler HTTP en Amazon Bedrock AgentCore (Python)

​Qué recibe tu agente

​Qué debe responder tu agente

​Partes de outputs

​Señales (signals)

​Respuestas de ejemplo

​Respuesta mínima

​Con botones de elección

​Pasar a un asesor

​Guardar variables y terminar

​Error del lado del agente

​Códigos HTTP

​Qué pasa si la respuesta no cumple el formato

​Ejemplo: handler HTTP en Amazon Bedrock AgentCore (Python)

Qué recibe tu agente

Qué debe responder tu agente

Partes de `outputs`

Señales (`signals`)

Respuestas de ejemplo

Respuesta mínima

Con botones de elección

Pasar a un asesor

Guardar variables y terminar

Error del lado del agente

Códigos HTTP

Qué pasa si la respuesta no cumple el formato

Ejemplo: handler HTTP en Amazon Bedrock AgentCore (Python)