Agente de IA externo

​

Como adicionar o nó

• 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.

​

AI Agent ou agente de IA externo

​

Provedores disponíveis

​

Comportamento por provedor

• Amazon Bedrock Agents: se o agente pedir uma ação de retorno de controle (return of control), o nó toma Pede mais informações. O resultado dessa ação vai para o agente no próximo turno, junto com o identificador da invocação, e o agente continua. Só uma ação por turno é aceita; se o agente pedir várias ao mesmo tempo, o turno falha.
• Amazon Bedrock AgentCore: em modo A2A, são aceitos Agent Cards 1.0 e 0.3. O qualificador do endpoint vale para o Agent Card e para as chamadas, e o Jelou mantém o mesmo identificador de sessão do runtime durante toda a conversa, para que os turnos cheguem à mesma sessão. Em modo HTTP, se o runtime informar um erro dentro da própria resposta (error, error_type e message), o turno falha com esse motivo.
• Claude Managed Agents: o Jelou lê a sessão por streaming até o agente ficar ocioso. Se o agente parar esperando o resultado de uma ferramenta, o nó toma Pede mais informações. Se o agente esgotar as tentativas, o turno falha e pode ser repetido; se atingir o orçamento ou o modelo se recusar a responder, falha sem nova tentativa; se a sessão for encerrada, falha porque o agente não está mais ativo. Um erro passageiro que o próprio agente está tentando de novo não interrompe o turno. A versão fixada do agente é um número inteiro a partir de 1.
• Salesforce Agentforce: cada mensagem é interpretada pelo seu tipo. Inform é texto para o usuário. Inquire e Confirm também são entregues como texto e, em uma tarefa, o nó toma Pede mais informações. Escalate toma Transferir para um operador, SessionEnded encerra a conversa, e Failure ou Error fazem o turno falhar com o motivo informado pelo Salesforce, sem nova tentativa.
• LangGraph Platform: se o grafo parar em uma interrupção, o nó toma Pede mais informações e a sua resposta retoma o grafo. Quando há várias interrupções pendentes ao mesmo tempo, o Jelou retoma a primeira informando o seu ID. Um erro que o grafo devolve dentro de uma resposta bem-sucedida faz o turno falhar com o seu motivo.
• Microsoft Copilot Studio: o Jelou entrega apenas as atividades do bot e descarta o eco da mensagem do próprio usuário.
• Azure AI Foundry: se a resposta chegar com status de falha, cancelada ou incompleta, ou com um erro mesmo que o HTTP seja 200, o turno falha com o motivo informado pelo Foundry. Uma resposta incompleta pelo filtro de conteúdo é tratada como rejeitada e não é repetida; um erro rate_limit_exceeded ou server_error é repetido. Com a API clássica, o motivo vem do campo last_error da execução.

​

OpenAI Agents (beta)

1. O Jelou cria uma sessão com o agente salvo e envia a mensagem.
2. Consulta o turno até ele terminar, dentro do tempo limite por turno, e entrega o texto da resposta final do agente.
3. Em uma tarefa, a sessão é excluída ao terminar. Em vários turnos, o Jelou mantém a sessão e envia cada mensagem do usuário como uma nova mensagem nela.

• Se o agente chamar uma função do seu lado, em uma tarefa o nó toma Pede mais informações, e o seu resultado volta ao agente como resultado da ferramenta.
• Se o agente pedir uma aprovação de uso do computador ou a reconexão de um ambiente, o turno falha como rejeitado com uma mensagem legível, porque um chat não consegue responder.
• Se o turno não terminar dentro do tempo limite, o nó toma Houve um erro e o Jelou tenta cancelar o turno.
• Os limites de uso, de gasto, de cobrança e as políticas da OpenAI fazem o turno falhar sem nova tentativa; uma sobrecarga ou um limite de frequência são repetidos.

​

Abas do nó

• Conexão: o tipo de conexão, a URL ou os campos do provedor, os headers fixos, a Instrução enviada ao agente (por padrão {{$message.text}}), os Dados que você envia e a Interação (uma tarefa ou vários turnos).
• Autenticação: o tipo de autenticação, o segredo da organização, o certificado mTLS e a assinatura HMAC.
• Transformar: os scripts prévio e posterior e, conforme o provedor, a forma da solicitação e da resposta.
• Avançado: a variável de resposta, o tempo limite por turno, as tentativas e, em vários turnos, a inatividade da sessão e o comando de reinício.

​

Eventos e condições de avaliação

• Uma tarefa: a conversa é avaliada quando o agente conclui a tarefa.
• Vários turnos: é avaliada quando o agente encerra a conversa, com todos os turnos desde o início.
• Se o turno falhar, nada é avaliado.
• Um nó sem condições ativas se comporta exatamente como antes e não guarda nenhuma conversa para avaliação.

​

Uma tarefa ou vários turnos

• 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.

​

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.

​

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.

​

Saídas do nó

• 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 de resposta

​

Autenticação e segredos da organização

​

Opções avançadas para HTTP personalizado

​

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

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

​

Scripts prévios e posteriores

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

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

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

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

​

Responder depois (confirma e responde depois)

• 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.

​

Quando a conversa termina

• 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.

​

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.

​

Não responda depois do limite de tempo

• Com HTTP personalizado, o script prévio (aba Transformar) recebe agentRequest.turn com turnId, inputId, deadlineMs e expiresAt (horário absoluto em formato ISO). Passe no corpo para o agente ver:

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

$context.set("agentRequest.body", { ...request.body, reply_by: request.turn.expiresAt });

• Com HTTP (contrato de turno do Jelou), a solicitação já traz turnId, inputId e deadlineMs no corpo. deadlineMs são os milissegundos que o nó espera desde o envio da solicitação, não um horário absoluto: calcule o limite somando-os ao horário em que o seu agente recebe a mensagem.

​

Ações: o agente escolhe a saída

• Nome da ação: minúsculas, números e sublinhado, até 32 caracteres, sem repetir.
• Campo com o nome da ação: o caminho na resposta do seu agente que traz o nome. O padrão é action.
• Campo com os dados da ação (opcional): o caminho de um valor que você quer usar na ramificação. É salvo junto ao nome na variável de resposta como actionData.

{ "result": { "action": "executar_emprestimo", "data": { "valor": 1500 } } }

• Um campo vazio ou ausente não é uma ação: o turno segue como sempre.
• Um nome que não está na lista faz o turno falhar e o fluxo segue por Houve um erro.
• Conecte cada ação a um nó: o nó mostra um aviso na tela enquanto faltar. Se você remover uma ação, suas conexões são removidas.
• Quando a ramificação termina e volta ao nó, o nó espera a próxima mensagem do usuário e a encaminha ao agente na mesma execução.

​

Mensagens que não são texto

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

​

Prefixo da assinatura

​

Token OAuth2 por mTLS

​

O contrato de turno do Jelou

{
  "turnId": "trn_01J8A7K2M4XQ",
  "inputId": "inp_9f3c2a71",
  "conversation": { "key": "wa:5511999999999", "channel": "whatsapp", "locale": "pt-BR" },
  "user": { "ref": "usr_8d41c0aa" },
  "input": { "parts": [{ "type": "text", "text": "Quero um reembolso da minha última compra" }] },
  "deadlineMs": 25000,
  "trace": { "executionId": "exec_5b2e", "nodeId": "n_agent" },
  "interaction": "multi_turn"
}

{
  "status": "completed",
  "outputs": [
    { "type": "text", "text": "Claro, para verificar sua solicitação de reembolso preciso do número do pedido. Pode compartilhá-lo?" }
  ]
}

{
  "status": "completed",
  "outputs": [
    { "type": "text", "text": "Pronto, encontrei seu pedido EJ-48213. O reembolso de R$ 45,00 foi aprovado e aparecerá em 3 a 5 dias úteis." }
  ],
  "signals": [{ "type": "conversation_ended" }]
}

​

Testar conexão

​

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

​

Disponibilidade