> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agente de IA externo

> Conecte um agente de IA que já vive fora do Jelou como um nó do seu fluxo.

O nó **Agente de IA externo** conecta ao seu fluxo um agente de IA que já vive fora do Jelou. O Jelou mantém o canal, a segurança e o registro de cada turno; seu agente decide a resposta.

<Info>
  O nó está sendo habilitado gradualmente; se você não o vê no canvas, peça ao seu executivo de conta do Jelou que o ative.
</Info>

## Como adicionar o nó

Os dois tipos de agente de IA são adicionados a partir do mesmo ponto de entrada: o item **AI Agent** na barra de ferramentas do builder. Seu comportamento muda conforme como você o usa:

* **Clique**: adiciona um nó Agente de IA: o agente de IA do Jelou.
* **Passar o cursor (hover)**: abre um seletor de provedores de **agentes de IA externos**. Ao escolher um provedor, o Jelou adiciona um nó **Agente de IA externo** pré-configurado para esse provedor.

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/selector-pt.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=7986e4add93924db5559319482702bd9" alt="Seletor de agentes de IA externos que aparece ao passar o cursor sobre o item AI Agent da barra de ferramentas" width="660" height="908" data-path="assets/images/agentes-ia/agente-de-ia-externo/selector-pt.png" />
</Frame>

<Tip>
  Esse seletor funciona da mesma forma que o de gateway de pagamento no nó **Pagamentos**: você escolhe primeiro o provedor e o nó chega com seus campos já organizados.
</Tip>

Depois de adicionado, o nó Agente de IA externo se conecta ao restante do seu fluxo pelas suas quatro saídas, como qualquer outro nó:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/canvas-flow-pt.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=1986f50b2b9f385df0532b4e0519a48a" alt="Nó Agente de IA externo em um fluxo, conectado por suas quatro saídas a uma mensagem de resposta, uma pergunta, um handoff para um humano e uma mensagem de desculpas" width="1960" height="1120" data-path="assets/images/agentes-ia/agente-de-ia-externo/canvas-flow-pt.png" />
</Frame>

## AI Agent ou agente de IA externo

Escolha conforme onde o agente vive. Para construí-lo dentro do Jelou, use o nó **AI Agent** ([guia geral](/pt/guias/agentes-ia)).

| | AI Agent | Agente de IA externo |
| :- | :- | :- |
| **O agente** | Você o constrói e ajusta no Jelou. | Já existe e está em produção fora do Jelou. |
| **Onde vive a lógica** | No prompt e nas ferramentas do nó. | No seu sistema ou no do seu fornecedor. |
| **Modelo** | Você o escolhe no nó. | Seu agente o define; o nó não o conhece. |
| **Mudanças** | Você as faz no builder. | Você as faz na sua plataforma; no Jelou só atualiza a conexão. |
| **Segurança** | O Jelou revisa as respostas do modelo. | Seu agente aplica a sua; o Jelou também revisa suas respostas. |

## Provedores disponíveis

Cada provedor pede seus próprios campos, retirados diretamente do seu console, e valida enquanto você digita. As credenciais são selecionadas pelo **nome do segredo da organização** que as guarda; o valor do segredo nunca é exibido nem salvo no fluxo.

| Provedor | O que você precisa no Jelou | Onde encontrar no console do provedor |
| :- | :- | :- |
| **Amazon Bedrock (Agents)** | Região da AWS, ID do agente, ID do alias | Bedrock → Agents → seu agente: o ID do agente e o ID do alias aparecem na visão geral; a região é a do seu console da AWS. |
| **Amazon Bedrock AgentCore** | ARN do runtime do agente, protocolo do servidor (HTTP ou A2A) | Bedrock AgentCore → Runtimes → seu runtime: o ARN completo e o `ProtocolConfiguration.serverProtocol` (HTTP ou A2A) aparecem no detalhe. |
| **Microsoft Copilot Studio** | URL regional do Direct Line ou endpoint do token | Copilot Studio → seu agente → Canais → Direct Line: a URL regional está em `regionalchannelsettings`; se você usa troca de token, o endpoint do token vem do canal Direct Line configurado com "Secret" desativado. |
| **Azure AI Foundry** | Endpoint do projeto e o agente (por ID ou por nome, conforme a geração da API) | AI Foundry → seu projeto → Overview: o endpoint do projeto. O agente é identificado por `agentId` (geração clássica, estilo Assistants) ou por `agentName` (geração Foundry, via Responses API), nunca ambos. |
| **Google Vertex AI Agent Runtime** (antes Agent Engine) | Nome do recurso do agente | Vertex AI → Agent Engine → seu agente: o nome completo do recurso (`projects/.../locations/.../reasoningEngines/...`). Agentes implantados com o template A2A usam o provedor A2A em vez deste. |
| **Google Dialogflow CX** | Nome do agente e código de idioma | Dialogflow CX → seu agente → configurações: o nome completo (`projects/.../locations/.../agents/...`). O código de idioma é usado quando a conversa não traz um próprio. |
| **Claude Managed Agents** | ID do agente, ID do ambiente | Console do Claude Managed Agents: o ID do agente (`agent_...`) e o ID do ambiente (`env_...`) do agente que você publicou. |
| **Salesforce Agentforce** | ID do agente (18 caracteres), URL de My Domain da sua org | Setup → Agentforce Agents: o Id do `BotDefinition`. A URL deve ser a de My Domain (`https://suaorg.my.salesforce.com`), nunca a de `lightning.force.com`. Apenas agentes que não sejam do tipo "Agentforce (Default)" são compatíveis. |
| **OpenAI (Responses API)** | ID do prompt (formato `pmpt_...`) | Plataforma da OpenAI → Prompts: o ID do prompt reutilizável que empacota instruções, modelo e ferramentas. Opcionalmente você pode fixar uma versão do prompt. |
| **LangGraph** | URL do deployment e ID do assistente | LangGraph Platform (LangSmith Deployments) → seu deployment: a URL do deployment e o ID do assistente (UUID recomendado, ou o nome do grafo). |
| **Dify** (pré-configurado sobre HTTP personalizado) | URL do workspace e credencial | Dify → seu app → API Access: a URL base e a API key do workspace. O Jelou chama `POST /v1/chat-messages` por você. |
| **n8n** (pré-configurado sobre HTTP personalizado) | URL do webhook | n8n → seu workflow → nó Webhook: a URL de produção do webhook. |
| **A2A (Agent-to-Agent)** | URL do Agent Card | O servidor do seu agente A2A: a URL pública onde ele publica seu Agent Card (`.well-known/agent-card.json` ou a rota que você definir). |
| **HTTP (contrato de turno do Jelou)** | URL do agente | Seu próprio servidor: o endpoint que já implementa o contrato de turno do Jelou (veja a seção abaixo). |
| **HTTP personalizado** | URL do agente, corpo da solicitação e rotas da resposta | Seu próprio servidor: qualquer endpoint que receba JSON, mesmo que não fale o contrato de turno do Jelou. |

## Uma tarefa ou vários turnos

Ao configurar o nó, você escolhe como ele interage com seu agente:

* **Uma tarefa**: o nó envia a tarefa uma vez, recebe a resposta e sai do nó.
* **Vários turnos**: o nó mantém a conversa com o agente, mensagem a mensagem, até que o agente a encerre ou a transfira. Enquanto o agente responde sem encerrar a conversa, o nó não toma nenhuma saída: ele entrega as mensagens ao usuário e espera a próxima mensagem dele para continuar com o agente.

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/panel-multiturn-pt.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=86607d4d4c43bb58d74512fe12fc1585" alt="Configuração do nó Agente de IA externo com a interação Vários turnos selecionada" width="1400" height="2500" data-path="assets/images/agentes-ia/agente-de-ia-externo/panel-multiturn-pt.png" />
</Frame>

### Exemplo: uma tarefa

```
Usuário: Quero saber o status do meu pedido EJ-48213
Agente:  Seu pedido EJ-48213 está a caminho e chega amanhã antes das 18h.
```

O nó recebe a resposta, entrega ao usuário e sai por **Respondeu**. Não há uma segunda rodada com o agente: qualquer mensagem posterior do usuário não passa mais por este nó.

### Exemplo: vários turnos

```
Usuário: Quero um reembolso da minha última compra
Agente:  Claro, para verificar sua solicitação de reembolso preciso do
         número do pedido. Você poderia compartilhar?

[o nó entrega a mensagem ao usuário e espera sua resposta]

Usuário: Meu número de pedido é EJ-48213
Agente:  Pronto, encontrei seu pedido EJ-48213. O reembolso de $45,00 foi
         aprovado e será refletido em 3 a 5 dias úteis.
```

O nó permanece ativo entre a primeira e a segunda mensagem: não toma nenhuma saída até que o agente encerre a conversa. Só então ele sai por **Respondeu**.

## Saídas do nó

O nó Agente de IA externo tem quatro saídas:

| Saída | É ativada quando |
| :- | :- |
| **Respondeu** | Em uma tarefa, o agente respondeu. Em vários turnos, o agente encerrou a conversa. |
| **Pede mais informações** | Só em **uma tarefa**: o agente parou para esperar uma ação ou um dado adicional. Em **vários turnos** isso é tratado como uma resposta normal e o nó continua esperando o usuário; não é uma saída nesse modo. |
| **Transferir para um operador** | O agente pediu para passar a conversa para um humano, depois de entregar suas mensagens. |
| **Houve um erro** | O agente falhou, rejeitou a credencial, retornou uma resposta inválida, ou a sessão expirou por tempo limite. |

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/canvas-node-pt.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=b36cbf1fac44dcb9ffecbd6e004cc8fd" alt="Comparação de dois nós Agente de IA externo, um configurado por A2A e outro por Amazon Bedrock Agents, mostrando as mesmas quatro saídas" width="1720" height="1200" data-path="assets/images/agentes-ia/agente-de-ia-externo/canvas-node-pt.png" />
</Frame>

Conecte cada saída ao que deve acontecer no seu fluxo. Um padrão típico:

* **Respondeu** → a mensagem do agente já foi entregue; continue o fluxo ou o encerre.
* **Pede mais informações** → um nó de pergunta que coleta o dado faltante e chama o agente novamente.
* **Transferir para um operador** → seu nó de transferência para o Inbox.
* **Houve um erro** → uma mensagem de desculpas e, se aplicável, uma nova tentativa ou uma transferência para um operador.

## A variável "Salvar a resposta em"

Todo nó Agente de IA externo tem um campo **Salvar a resposta em** (por padrão `agentReply`) onde a resposta do agente é escrita. Você pode referenciá-la em nós posteriores do fluxo com a sintaxe habitual de variáveis, por exemplo `{{$context.agentReply}}` em um nó de mensagem ou em uma condição.

Se o agente também enviar dados estruturados (por exemplo pela rota de dados do HTTP personalizado, ou por um sinal `variables_set`), esses dados são escritos como variáveis individuais do contexto do fluxo, disponíveis para qualquer nó posterior.

## Autenticação e segredos da organização

Cada provedor admite um ou mais esquemas de credencial, conforme o que sua API aceita:

| Esquema | O que o segredo guarda |
| :- | :- |
| `api_key_header` | Um valor enviado em um header com nome configurável. |
| `bearer` | Um token enviado como `Authorization: Bearer ...`. |
| `oauth2_client_credentials` | O client secret; o Jelou troca um token com seu endpoint OAuth2 antes de cada chamada (ou reutiliza um ainda válido). |
| `aws_sigv4_keys` | Um objeto JSON `{accessKeyId, secretAccessKey, sessionToken?}`; o Jelou assina a solicitação com SigV4. |
| `aws_sigv4_role` | Não guarda uma chave: o Jelou assume o papel (role) da AWS que você indicar, usando um external id guardado como segredo. |
| `google_service_account` | A chave JSON completa da conta de serviço. |
| `direct_line_secret` | O segredo de canal Direct Line do Copilot Studio. |
| `mtls` | Combina-se com o certificado mTLS da sua empresa (veja abaixo); é independente dos demais esquemas. |
| `none` | Sem credencial; válido apenas quando seu agente não exige autenticação. |

Em todos os casos, **o nó guarda apenas o nome do segredo da organização**, nunca seu valor. O segredo é resolvido no momento da chamada e nunca é exibido nem salvo no fluxo.

## Opções Enterprise para HTTP personalizado

Quando seu agente usa **HTTP (contrato de turno do Jelou)** ou **HTTP personalizado**, sua empresa pode ter acesso a opções adicionais:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/panel-connection-pt.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=43b0a79e7b6447ced68efc39cb450d06" alt="Aba Conexão do nó Agente de IA externo com a URL do agente, autenticação, certificado mTLS, assinatura HMAC e headers fixos" width="1400" height="2500" data-path="assets/images/agentes-ia/agente-de-ia-externo/panel-connection-pt.png" />
</Frame>

| Opção | Para que serve |
| :- | :- |
| **Assinatura de solicitação (HMAC)** | Assina cada solicitação com um segredo compartilhado, para que seu agente verifique que ela veio do Jelou. |
| **Headers estáticos** | Adiciona headers fixos que seu agente espera em cada chamada. Não são permitidos headers sensíveis como `authorization`, `cookie`, `host` ou `x-jelou-signature`, nem valores com variáveis (`{{...}}`). Máximo de 10 headers. |
| **Scripts prévios e posteriores** | Executa um script antes de enviar a solicitação ou depois de receber a resposta, no mesmo ambiente seguro que o nó API usa. |
| **OAuth** | Autenticação por credenciais de cliente OAuth2. |
| **mTLS** | TLS mútuo com o certificado de cliente da sua empresa, independente da credencial: você pode combinar OAuth e mTLS ao mesmo tempo. |
| **Tentativas** | Até 3 tentativas; só são reenviados tempos limite, limites de uso e erros de servidor, nunca uma solicitação rejeitada. |
| **Tempo limite por turno** | Quanto tempo o nó espera a resposta do agente antes de tomar a saída de erro. Padrão de 25 segundos, até um máximo de 120 segundos. |

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/panel-advanced-pt.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=d941b10aa0c119822c0dcf7adfa53926" alt="Aba Avançado do nó Agente de IA externo com o tempo limite por turno e o número de tentativas" width="1400" height="1640" data-path="assets/images/agentes-ia/agente-de-ia-externo/panel-advanced-pt.png" />
</Frame>

<Note>
  Essas opções estão disponíveis em planos Enterprise. Se você não as vê no seu nó, peça ao seu executivo de conta do Jelou que verifique seu plano.
</Note>

### Assinatura HMAC: o que é assinado e como verificá-la

Ao ativar a assinatura de solicitação, o Jelou calcula um HMAC-SHA256 sobre o corpo exato da solicitação (os mesmos bytes enviados) usando o segredo que você escolher, e o envia em um header:

| Campo | Valor padrão | Notas |
| :- | :- | :- |
| Header | `X-Jelou-Signature` | Configurável. |
| Codificação | Hexadecimal | Também admite Base64. |
| O que é assinado | Só o corpo (`body`) | Também admite `timestamp.body`, que assina `"{timestamp}.{body}"` e adiciona o timestamp Unix em um segundo header que você nomeia. |

Seu próprio servidor pode verificar a assinatura assim (Node.js, usando só o corpo):

```js theme={null}
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 deve ser o corpo cru tal como chegou, antes de fazer parse do JSON
const valid = isValidJelouSignature(rawBody, req.headers["x-jelou-signature"], SHARED_SECRET);
```

<Warning>
  Sempre verifique sobre o corpo **cru** da solicitação, antes que seu framework faça parse para JSON. Serializar novamente o JSON já parseado pode mudar a ordem das propriedades ou o espaçamento e fazer a assinatura não bater mesmo que o conteúdo seja o mesmo.
</Warning>

O campo **Tarefa** aceita variáveis. Para enviar ao agente a mensagem do usuário, use `{{$message.text}}`: ela contém o texto da mensagem que chegou ao fluxo. `{{$input.message}}` não é uma variável de mensagem: `$input` guarda apenas os dados que seu fluxo coletou (por exemplo, com um nó Input), então fica vazio quando o nó é executado a partir de uma mensagem de chat.

### Scripts prévios e posteriores

Os scripts rodam no mesmo ambiente seguro (sandbox) que o nó API usa, e só se aplicam a provedores HTTP. São configurados na aba **Transformar** do nó, junto da tarefa que é enviada e da variável onde a resposta é salva:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/panel-transform-pt.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=71ebc97ff2e0a9d89c936ae7ac50549a" alt="Aba Transformar do nó Agente de IA externo com o campo Tarefa, a variável Salvar a resposta em, e o editor de Pre Request / Post Request" width="1400" height="2600" data-path="assets/images/agentes-ia/agente-de-ia-externo/panel-transform-pt.png" />
</Frame>

**Script prévio (pre-request):** `$context.get("agentRequest")` contém `{ task, sessionId, body, headers }`. O script pode modificar `agentRequest.body` ou `agentRequest.headers` antes de o Jelou enviar a solicitação. Por exemplo, para envolver o corpo em um envelope próprio da sua empresa:

```js theme={null}
const request = $context.get("agentRequest");

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

**Script posterior (post-response):** `$context.get("agentResponse")` contém `{ status, body }`. O script deve deixar em `agentResponse.body` o objeto que o mapeamento da resposta depois lê (as rotas `textPath`, `dataPath`, `sessionIdPath`, etc.).

```js theme={null}
const response = $context.get("agentResponse");

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

<Note>
  Um erro lançado pelo script faz o turno falhar pela saída de erro do nó. As mudanças do script nunca tocam as variáveis próprias do fluxo: só modificam o que o Jelou envia ou lê para esta chamada.
</Note>

## Responder depois (confirma e responde depois)

Alguns agentes externos não respondem dentro da mesma chamada: confirmam que receberam a mensagem e enviam a resposta mais tarde, por conta própria. Para esse caso, o nó **Agente de IA externo** tem um modo opcional. Ele vem desativado, então um nó existente se comporta exatamente como antes.

O campo **Como o agente responde** aparece na aba **Conexão** quando o tipo de conexão é **HTTP (contrato de turno do Jelou)** ou **HTTP personalizado** e a interação é **Vários turnos**. Ele tem duas opções:

* **Na mesma resposta** (padrão): o agente responde dentro da mesma chamada, como antes.
* **Confirma e responde depois**: o agente confirma com qualquer resposta 2xx. O Jelou não entrega nada do corpo da confirmação e deixa o nó esperando a próxima mensagem do usuário, com o mesmo tempo de inatividade da sessão. Essa mensagem é reenviada ao agente dentro da mesma execução.

<Frame>
  <img src="https://mintcdn.com/jelouai/rXl0gajV6cghfzcz/assets/images/agentes-ia/agente-de-ia-externo/ack-connection-pt.png?fit=max&auto=format&n=rXl0gajV6cghfzcz&q=85&s=ae4a1bd0734faf6d8840334b4856c427" alt="Aba Conexão do nó Agente de IA externo com Como o agente responde em Confirma e responde depois, o aviso da saída de falha, o interruptor do token com o certificado mTLS e o prefixo da assinatura" width="384" height="2200" data-path="assets/images/agentes-ia/agente-de-ia-externo/ack-connection-pt.png" />
</Frame>

Com **HTTP personalizado**, neste modo o **Caminho do texto da resposta** deixa de ser obrigatório, porque nenhum texto do corpo é entregue.

### Quando a conversa termina

Na aba **Avançado**, estes dois campos opcionais aparecem somente neste modo:

* **Campo que encerra a conversa**: o caminho do campo no corpo da confirmação, por exemplo `status`, `data.state` ou `items[0].s` (máximo de 200 caracteres).
* **Valores que encerram a conversa**: de 1 a 20 valores distintos, separados por vírgulas. Aceita texto, números inteiros e verdadeiro ou falso. Quando o campo traz um deles, a conversa termina e o fluxo segue pela saída **Respondeu**.

<Frame>
  <img src="https://mintcdn.com/jelouai/rXl0gajV6cghfzcz/assets/images/agentes-ia/agente-de-ia-externo/ack-advanced-pt.png?fit=max&auto=format&n=rXl0gajV6cghfzcz&q=85&s=c13302628449830307b8869327d44cb6" alt="Aba Avançado do nó Agente de IA externo com o campo que encerra a conversa e seus valores" width="384" height="2200" data-path="assets/images/agentes-ia/agente-de-ia-externo/ack-advanced-pt.png" />
</Frame>

### Saídas que você deve conectar

* Conecte sempre a saída **Houve um erro**: é a que o nó usa quando a espera vence sem o usuário escrever. Sem essa conexão você não poderá publicar o fluxo.
* Conecte a saída **Respondeu** somente se você definiu o campo que encerra a conversa. Sem esses campos ela não é usada.
* A saída **Transferir para um operador** não é obrigatória.

O nó mostra um aviso no canvas enquanto faltar uma das conexões necessárias.

<Warning>
  Quando a espera vence, o fluxo segue por **Houve um erro** e o Jelou não envia nenhuma mensagem ao usuário. Conecte essa saída a um **Fim** silencioso, sem mensagem de erro.
</Warning>

## Mensagens que não são texto

Quando o usuário envia uma imagem, um áudio, um documento, uma resposta de WhatsApp Flow, um botão, uma lista ou uma localização, o agente deixa de receber uma tarefa vazia. A tarefa chega como `[tipo] legenda` (ou só `[tipo]`), e a solicitação inclui um objeto `input.inbound` com o tipo, o texto, a legenda, o tipo de arquivo e o id da mensagem.

Os dados sensíveis não são enviados por padrão. Na aba **Transformar**, o campo **Dados sensíveis de mensagens não texto que o agente recebe** permite escolher quais adicionar:

* **URL do arquivo**
* **Resposta de botão ou lista**
* **Resposta de WhatsApp Flow**
* **Localização**

Marque apenas o que seu agente precisa: eles podem conter informações pessoais. Isso vale para qualquer tipo de conexão. Texto simples e botões com título são enviados como antes.

<Frame>
  <img src="https://mintcdn.com/jelouai/rXl0gajV6cghfzcz/assets/images/agentes-ia/agente-de-ia-externo/ack-transform-pt.png?fit=max&auto=format&n=rXl0gajV6cghfzcz&q=85&s=c1fc5344f719ec05cf1703fc91293140" alt="Aba Transformar do nó Agente de IA externo com os dados sensíveis de mensagens não texto que o agente recebe" width="384" height="2200" data-path="assets/images/agentes-ia/agente-de-ia-externo/ack-transform-pt.png" />
</Frame>

## Prefixo da assinatura

Alguns agentes esperam a assinatura HMAC com um texto na frente, por exemplo `sha256=` seguido do valor. Em **Assinar as requisições**, o campo **Prefixo da assinatura (ex. sha256=)** adiciona esse texto literal antes do valor da assinatura. Aceita de 1 a 32 caracteres: letras, números e `_ = . : / + -`; não admite espaços nem modelos. O header do timestamp nunca recebe prefixo. Vale para **HTTP (contrato de turno do Jelou)** e **HTTP personalizado**, e em cada nova tentativa.

## Token OAuth2 por mTLS

Se seu agente usa **Credenciais de cliente OAuth2** e exige o certificado de cliente também para pedir o token, escolha um **Certificado mTLS** e ative **Pedir o token também com o certificado mTLS**. O pedido do token passa pelo mesmo certificado da chamada ao agente. A URL do token continua sendo https. O interruptor só aparece com essa autenticação e com um certificado escolhido; se você remover o certificado, ele é desativado. Desativado, o token é pedido como sempre.

## O contrato de turno do Jelou

Ao escolher **HTTP (contrato de turno do Jelou)**, seu servidor recebe e responde com uma forma fixa que o Jelou já sabe interpretar, sem precisar mapear rotas manualmente. Isto é o que o Jelou realmente enviou e recebeu em um teste real contra um servidor de agente, com a assinatura HMAC redigida:

<CodeGroup>
  ```json Solicitação que o Jelou envia theme={null}
  {
    "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": "Quero um reembolso da minha última compra",
      "session": "",
      "user": "usr_9f3ka2"
    }
  }
  ```

  ```json Resposta que o agente devolve theme={null}
  {
    "data": {
      "reply": "Claro, para verificar sua solicitação de reembolso preciso do número do pedido. Você poderia compartilhar?",
      "session": "sess_ej3nc9dk2m"
    }
  }
  ```
</CodeGroup>

Na segunda rodada da mesma conversa, o agente já conhece o número do pedido e o nó entrega a conversa como encerrada:

```json Segunda resposta do agente theme={null}
{
  "data": {
    "reply": "Pronto, encontrei seu pedido EJ-48213. O reembolso de $45,00 foi aprovado e será refletido em 3 a 5 dias úteis.",
    "session": "sess_ej3nc9dk2m"
  }
}
```

<Note>
  Se seu agente não fala exatamente esse contrato, use **HTTP personalizado**: ali você define o formato do corpo que é enviado e as rotas onde o Jelou deve ler o texto da resposta, os dados estruturados e o identificador de sessão, na aba **Transformar** do nó.
</Note>

## Testar conexão

Antes de publicar seu fluxo, use o botão **Testar conexão** na aba Conexão do nó para verificar que tudo está bem configurado, sem esperar que um usuário real acione o nó. O teste executa uma série de verificações encadeadas, parando na primeira que falhar:

| Verificação | O que comprova |
| :- | :- |
| Contrato | A configuração do nó cumpre o esquema esperado. |
| Provedor | O tipo de provedor escolhido está disponível. |
| Certificado mTLS | Se você configurou mTLS, que o certificado carrega e pertence à sua empresa. |
| Segredo | O segredo da organização referenciado existe e pode ser lido. |
| Token / acesso | A credencial de fato emite acesso (por exemplo, que a troca OAuth2 ou a assinatura AWS funcionem). |
| Agent Card (somente A2A) | O Agent Card é alcançável e declara uma interface HTTPS compatível com a credencial configurada. |
| Rejeita anônimo | O agente rejeita uma chamada sem a credencial (quando aplicável ao esquema). |
| Responde a uma tarefa | O agente responde a uma tarefa de teste dentro do contrato, dentro do tempo limite. |
| Sessão (somente vários turnos) | O agente emite um identificador de sessão para o próximo turno. |

Se todas as verificações passarem, você vê uma confirmação:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/test-connection-passed-pt.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=89e9bb116450362e7739b002bf23f3f3" alt="Resultado de Testar conexão quando todas as verificações passam, com a mensagem 'Conexão OK'" width="1400" height="2900" data-path="assets/images/agentes-ia/agente-de-ia-externo/test-connection-passed-pt.png" />
</Frame>

Se alguma falhar, o Jelou diz qual foi e por quê, para você corrigir a configuração antes de publicar. Por exemplo, quando o agente rejeita a credencial:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/test-connection-failed-pt.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=e332330b09f8a926c29be7a59964a1b8" alt="Resultado de Testar conexão quando uma verificação falha, com o detalhe do que falhou e por quê" width="1400" height="2500" data-path="assets/images/agentes-ia/agente-de-ia-externo/test-connection-failed-pt.png" />
</Frame>

## Segurança

* **As credenciais nunca saem dos segredos da sua organização.** O nó guarda apenas o nome do segredo; seu valor nunca é exibido nem salvo no fluxo.
* **Somente HTTPS.** O Jelou não chama endereços internos nem privados.
* **As respostas do seu agente passam pelos mesmos controles de segurança do Jelou** que as respostas de um Agente de IA, antes de chegar ao usuário: são filtradas como qualquer mensagem de saída, sem que você precise configurar nada adicional no nó.

## Solução de problemas

<AccordionGroup>
  <Accordion title="O nó sempre sai por 'Houve um erro'">
    Verifique primeiro **Testar conexão**: quase sempre indica se o problema é o certificado, o segredo, o token ou o próprio agente. As causas mais comuns são uma credencial que expirou ou foi revogada, uma URL que parou de responder, ou uma resposta do agente que não é um JSON válido ou não traz o campo esperado na rota configurada.
  </Accordion>

  <Accordion title="O turno demora muito e termina em erro">
    O nó espera no máximo o **tempo limite por turno** configurado (25 segundos por padrão, até 120 como máximo). Se seu agente precisa de mais tempo, aumente o limite na aba Avançado; se o agente falha de forma intermitente, verifique as **tentativas**: elas só se aplicam a tempos limite, limites de uso (HTTP 429) e erros de servidor (5xx), nunca a uma solicitação que o agente rejeitou explicitamente.
  </Accordion>

  <Accordion title="A assinatura HMAC não bate no meu servidor">
    Sempre verifique sobre o corpo cru da solicitação, antes de fazer parse do JSON (veja a seção de assinatura HMAC acima). Confirme também que você está usando o mesmo segredo, a mesma codificação (hexadecimal ou Base64) e, se ativou `timestamp.body`, que está assinando `"{timestamp}.{body}"` e não só o corpo.
  </Accordion>

  <Accordion title="'Pede mais informações' não aparece em vários turnos">
    É esperado: essa saída só existe no modo **uma tarefa**. Em **vários turnos**, quando o agente precisa de um dado adicional ele simplesmente o pede como uma mensagem normal e o nó continua esperando a resposta do usuário, sem tomar nenhuma saída.
  </Accordion>

  <Accordion title="Não vejo o nó Agente de IA externo nem o seletor de provedores">
    O nó está sendo habilitado gradualmente. Peça ao seu executivo de conta do Jelou que o ative para sua empresa.
  </Accordion>

  <Accordion title="Não vejo as opções Enterprise (HMAC, headers estáticos, scripts, mTLS)">
    Essas opções estão disponíveis em planos Enterprise. Peça ao seu executivo de conta do Jelou que verifique seu plano.
  </Accordion>
</AccordionGroup>

## Disponibilidade

O nó Agente de IA externo está sendo habilitado gradualmente. Se você não o vê no canvas do seu projeto, contate seu executivo de conta do Jelou para solicitar sua ativação.

<Card title="Nó Agente de IA" icon="robot" href="/pt/guias/nodos/ai-agent">
  Configuração geral do nó Agente de IA.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.