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.
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.
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).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.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.
Exemplo: uma tarefa
Exemplo: vários turnos
Saídas do nó
O nó Agente de IA externo tem quatro saídas:
- 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ãoagentReply) 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:
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:
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.
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:
Seu próprio servidor pode verificar a assinatura assim (Node.js, usando só o corpo):
{{$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:
$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:
$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.).
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.
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.
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.stateouitems[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.
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
Prefixo da assinatura
Alguns agentes esperam a assinatura HMAC com um texto na frente, por exemplosha256= 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:Segunda resposta do agente
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ó.
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:
Se todas as verificações passarem, você vê uma confirmaçã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
O nó sempre sai por 'Houve um erro'
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.
O turno demora muito e termina em erro
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.
A assinatura HMAC não bate no meu servidor
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.'Pede mais informações' não aparece em vários turnos
'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.
Não vejo o nó Agente de IA externo nem o seletor de provedores
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.
Não vejo as opções Enterprise (HMAC, headers estáticos, scripts, mTLS)
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.
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.Nó Agente de IA
Configuração geral do nó Agente de IA.