São as duas formas principais de integrar lógica própria no seu fluxo. HTTP Request chama uma API externa, enquanto que Code Tool executa um script personalizado no ambiente do Atom. Ambas as ferramentas podem usar campos da conversa como entrada e guardar suas respostas como novos campos.
⚖️ Qual usar? HTTP Request vs. Code Tool
Esta é a primeira decisão arquitetônica que você deve tomar ao integrar sistemas. Escolher a ferramenta errada pode complicar a manutenção ou somar latência desnecessária.
Critério | 🌐 HTTP Request | 💻 Code Tool |
Ponto de conexão | Já existe um endpoint que faz o que se precisa. | A lógica é própria do fluxo e não se aplica a outros sistemas. |
Manutenção | A lógica vive em um sistema mantido por outro time. | A lógica muda frequentemente com as regras do negócio. |
Manipulação de dados | Não é necessária transformação. | É preciso transformar ou filtrar dados antes/depois de uma chamada. |
Persistência | É necessário persistir dados (criar registros, atualizar estados). | Lógica condicional complexa ou cálculos sem persistência externa. |
Exemplos típicos | Consultar o CRM, criar um ticket, ver estoque em um ERP. | Calcular uma cota, regras de elegibilidade, mascarar dados. |
4 perguntas-chave para decidir rápido:
¿Já existe um endpoint que faz isso? Se sim 👉 HTTP Request.
¿A lógica é reutilizável por outros sistemas? Se sim 👉 HTTP Request (a um microsserviço próprio).
¿A lógica muda frequentemente com o negócio? Se sim 👉 Code Tool.
¿É preciso transformar ou combinar dados? Se sim 👉 Code Tool.
⚠️ Anti-padrões frequentes:
Escrever um endpoint dentro de um Code Tool só porque "é mais rápido" duplica lógica que já existe no seu ecossistema e quebra o monitoramento de origem.
Criar um microsserviço inteiro só para um cálculo matemático simples soma infraestrutura e latência de rede sem motivo.
Regra prática: Se a lógica cabe em 30 linhas de código e não precisa guardar dados em um banco externo, use um Code Tool.
🌐 HTTP Request
📍 Onde se configura?
Canvas → Nó Cortex → Painel direito → Aba Ferramentas → HTTP Request.
🗂️ O que se configura
Campo | Descrição |
Método | GET, POST, PUT, PATCH, DELETE. |
URL | Admite parâmetros de rota e de query dinâmicos. |
Headers | Chaves e valores (ambos admitem variáveis). |
Query params | Chaves e valores (ambos admitem variáveis). |
Body | Estrutura JSON (admite variáveis). |
🔗 Usar campos como variáveis
Em qualquer um dos campos anteriores, ao escrever /: se abre a lista de campos de salvamento do nó (o menu é filtrável). As variáveis podem ser usadas sozinhas ou concatenadas diretamente com texto fixo:
[https://api.crm.com/customers//](https://api.crm.com/customers//)[ID Cliente]/vehicles?year=/[Ano Preferido]
Os valores são codificados automaticamente para URL (por exemplo, os espaços viram
%20).Você também pode injetar variáveis de ambiente usando
{{VARIABLE}}(ideal para tokens de autorização e URLs base).
💡 Segurança em Runtime: Se uma variável referenciada não tiver valor no momento de executar a requisição, ela não é disparada. O nó perceberá e pedirá ao cliente o dado faltante antes de continuar.
👁️ Visualização prévia
Antes de testar ou quebrar algo, a "Visualização prévia" mostra como a URL ficará montada e o body final com valores de exemplo. Serve para verificar a construção sem executar nada no seu servidor.
💾 Guardar a resposta
Na configuração avançada você encontrará a seção Como guardar as respostas?.
Clique em Testar API daqui para executar a requisição com valores de exemplo e ver a resposta completa em formato JSON.
Clique sobre qualquer valor do JSON para abrir o formulário de mapeamento.
Para cada valor que você precisar guardar, configurará o seguinte:
Campo | Descrição |
Nome da variável | Identificador interno do mapeamento (para reconhecê-lo visualmente). |
Valor a guardar | O caminho exato dentro do JSON de resposta (ex. |
Selecionar campo | O campo de salvamento de Cortex onde o dado será persistido (você pode criar um novo ali mesmo). |
📝 Exemplo de fluxo
O nó capturou o email do cliente e dispara um GET para:
[https://crm.empresa.com/api/contacts?email=/](https://crm.empresa.com/api/contacts?email=/)[Email do cliente]
A API devolve:
JSON
{ "id": "12345", "tier": "premium", "vehicles": 2 }Você mapeia id ao campo ID Cliente, tier a Tier do Cliente, e vehicles a Veículos anteriores. Na resposta seguinte, a IA pode usar /[Tier do Cliente] para dizer: "Como você é um cliente premium, oferecemos...".
(Os erros de rede e respostas 4xx/5xx são tratados com mensagens configuráveis e ficam registrados na rastreabilidade).
💻 Code Tool
📍 O que é?
É um script escrito em JavaScript que se executa em um ambiente isolado (seguro) dentro do Atom. Não requer autenticação nem whitelisting de IPs, e sua latência é quase nula porque não sai à rede pública.
📥 Parâmetros de entrada
Aqui você define a assinatura do seu script. Para cada parâmetro você configura:
Campo | Descrição |
Nome do parâmetro | O identificador exato com o qual você acessará dentro do código JavaScript. |
Origem do valor | Campo de informação: Você escolhe um campo capturado do nó.
Valor fixo: Você digita um dado literal estático. |
(Nota: Além do mapeamento formal, dentro do código você pode escrever /: para inserir referências rápidas a campos que serão resolvidas logo antes da execução).
📤 Estrutura de saída
Você deve declarar o que seu script vai devolver usando um esquema JSON com chaves e tipos de dado:
JSON
{ "resultado": "string", "monto_calculado": "number", "es_valido": "boolean" }Essa declaração cumpre uma dupla função: ensina ao LLM o que esperar do script e habilita a interface visual para guardar as respostas em campos.
⚙️ Execução e descrição
Guardar o resultado: Funciona exatamente igual a HTTP Request (você testa o script e mapeia o JSON de retorno para seus campos).
Descrição de execução: O Code Tool leva um campo de "descrição". Isso é vital: é o que o LLM lê para saber quando deve executar o código. Sem uma boa descrição, a IA não o invocará.
📝 Exemplo de fluxo
O nó capturou Preço do veículo e Prazo em meses. O Code Tool recebe ambos os parâmetros, faz seu cálculo interno e devolve:
JSON
{ "cuota_mensual": 850.50, "interes_total": 2406.00, "tasa_aplicada": 0.18 }Você mapeia os resultados para seus campos e o prompt responde: "Sua cota mensal seria de $/[Cota Mensal Calculada] com uma taxa de /[Taxa Aplicada]%."
🚨 Tratamento de erros e Segurança
Se o script falhar (por exceção, timeout ou erro de sintaxe), ele é marcado como erro de ferramenta, capturado nos logs sem quebrar o fluxo e dispara sua mensagem de erro configurada.
Regra de ouro de Segurança: Um Code Tool NUNCA deve conter senhas ou credenciais escritas em texto puro. Se você precisa chamar um serviço externo seguro, use um HTTP Request onde as credenciais vivem em variáveis de ambiente cifradas.
🔄 Disponibilidade dos dados capturados
Os campos que escrevem tanto HTTP Request quanto Code Tool ficam imediatamente disponíveis para:
Referenciá-los usando
/nas mensagens seguintes do mesmo nó.Usá-los como variáveis em outras requisições HTTP ou Code Tools.
Passá-los aos nós seguintes da sua arquitetura no Flowbuilder.
Leve a inteligência do seu agente para o próximo nível! 🚀
Integrar HTTP Requests e Code Tools converte sua IA conversacional em um operador transacional capaz de resolver cálculos complexos, conectar-se com seu ecossistema e personalizar cada experiência ao máximo. ✅