Guia de ferramentas


As ferramentas customizadas são o que transformam o seu assistente conversacional em um agente de ia. Enquanto o prompt define como o agente fala e o que coleta, as ferramentas definem o que ele faz — enviar arquivos, buscar dados em sistemas externos, disparar ações em outros sistemas, e muito mais.

Este guia explica como cada tipo de ferramenta funciona, quando usar cada um e como configurar corretamente.

O que são ferramentas e como o agente decide usá-las

Quando o agente está numa conversa, ele não executa ferramentas aleatoriamente. A decisão de acionar uma ferramenta vem de dois lugares:

O nome e a descrição da ferramenta — o agente lê o nome e a descrição de cada ferramenta disponível e decide, com base no contexto da conversa, quando faz sentido acionar uma. Por isso, uma descrição clara e objetiva é essencial: ela é literalmente a instrução que a IA usa para decidir se deve ou não chamar aquela ferramenta.

O prompt — você pode reforçar no prompt quando e como usar cada ferramenta. Exemplo: "Quando o cliente pedir o catálogo, use a ferramenta enviar_catalogo."

O agente também pode acionar múltiplas ferramentas numa mesma interação. Por exemplo: buscar um lead no CRM e, com o resultado em mãos, registrar uma observação nesse mesmo lead. Ferramentas podem ser encadeadas naturalmente quando o prompt e as descrições deixam claro o fluxo esperado.

Como criar uma ferramenta

Acesse a aba Habilidades no cadastro do agente e clique em + Criar ferramenta na seção de Ferramentas customizadas.


Um modal vai abrir com as opções de configuração. O primeiro passo é escolher o tipo da ferramenta — cada tipo tem um conjunto de configurações diferente e serve a um propósito específico.


Tipos de ferramenta

Existem três tipos de ferramenta customizada, cada um com uma finalidade diferente.

Enviar Mensagem

Permite que o agente envie conteúdo rico para o cliente durante a conversa — catálogos, vídeos, imagens, áudios, documentos e localização. É o tipo mais simples de configurar e com uso imediato no dia a dia.



Tipos de mensagem disponíveis



💬 Texto

Envia uma mensagem de texto com conteúdo fixo. Útil para avisos, instruções ou respostas padronizadas que você não quer deixar a IA formular livremente.



🖼️ Imagem

Envia uma imagem diretamente no WhatsApp. Ideal para fotos de produtos, banners promocionais ou qualquer visual relevante para a conversa.



🎤 Áudio

Envia um arquivo de áudio. Pode ser usado para mensagens de voz explicativas, instruções em formato de áudio ou apresentações.



📹 Vídeo

Envia um vídeo. Ótimo para demonstrações de produto, tutoriais de uso ou apresentações institucionais.


📄 Arquivo

Envia qualquer arquivo: PDF, planilha, documento. O uso mais comum é envio de catálogos, contratos, manuais técnicos, boletos e fichas de produto.


📍 Localização

Envia um pin de localização no mapa do WhatsApp, com nome e endereço formatados. Muito mais elegante e prático do que enviar um endereço em texto.


Como obter o link da mídia

Para os tipos de mídia (imagem, vídeo, áudio, arquivo), você precisa informar a URL do arquivo. A forma mais simples é fazer upload diretamente na Galeria de Mídias do Omnichannel e copiar o link gerado — sem precisar de hospedagem externa.


Suba o catálogo, vídeo ou imagem na galeria do Omni, copie o link e cole diretamente na configuração da ferramenta. Simples assim.

Como referenciar a ferramenta no prompt

Depois de criar a ferramenta, referencie ela pelo nome no prompt do agente para que ele saiba quando acionar.

Quando o cliente pedir o catálogo de produtos, use a ferramenta enviar_catalogo.
Quando perguntar onde fica a loja, use a ferramenta enviar_localizacao.

Webhook

O tipo mais poderoso. Conecta o agente a qualquer sistema externo via HTTP — CRMs, ERPs, APIs de terceiros, sistemas internos. Se o sistema tem uma API, o agente pode consumir.

Como configurar

A criação é dividida em 4 abas: Configurações, Parâmetros, Webhook e Retorno.

1. Configurações


Nome da ferramenta — use um identificador único e descritivo, sem espaços. Esse nome é usado para referenciar a ferramenta no prompt. Nomeie como verbos: buscar_lead, consultar_pedido, registrar_agendamento.

Descrição da ferramenta — escreva pensando em quando a IA deve usar essa ferramenta, não apenas o que ela faz.

"Busca um lead no CRM" é menos útil que "Use quando o cliente quiser saber informações sobre seu cadastro ou histórico de compras."

Modo de execução — define o que acontece com o retorno da ferramenta:

  • Reprocessar resultado com IA — o retorno volta para o agente como contexto adicional. O agente lê o resultado e formula uma resposta natural para o cliente. Use na maioria dos casos.

  • Enviar resultado como resposta — o retorno vai diretamente para o cliente como mensagem, sem passar pela IA. Use quando os dados são sensíveis e você não quer que a IA reformule — como saldo bancário, dados financeiros ou informações médicas.

2. Parâmetros

Parâmetros são os dados que o agente coleta durante a conversa e passa para a ferramenta na hora de executar.


Cada parâmetro tem tipo (String, Number, Boolean), um identificador único, uma descrição que orienta a IA sobre o que coletar, e se é obrigatório ou não. O agente só executa a ferramenta quando tiver todos os parâmetros obrigatórios preenchidos.

Os parâmetros são referenciados na URL e no corpo da requisição via $tool.{{parametro}}.

A descrição do parâmetro é tão importante quanto a da ferramenta. É ela que diz para a IA de onde vem esse dado — se deve perguntar ao cliente, se já está na conversa, ou se é um valor fixo.

3. Webhook (configurar request)

Aqui você configura a requisição HTTP que será feita quando a ferramenta for acionada.


Método — GET, POST, PUT, PATCH ou DELETE, conforme a API que você está integrando.

URL do endpoint — a URL da API. Use $tool.{{parametro}} para inserir valores dos parâmetros diretamente na URL. Também suporta variáveis do flowbuilder como $contact_id, $phone, entre outras.

Headers (JSON) — passe os headers de autenticação e configuração da requisição, como token de acesso e content-type.

4. Retorno

Aqui você define o que fazer com a resposta da API. Não é obrigatório configurar, pois é utilizado em casos de uso mais específicos


Mapear retorno — extrai valores do JSON de resposta e armazena em variáveis. Use $.propriedade para valores diretos, $.objeto.propriedade para valores aninhados e $.array[0].campo para arrays. As variáveis mapeadas podem ser salvas em campos customizados do atendimento ou do contato.

Saída da ferramenta — define exatamente o que será enviado para a IA (ou para o cliente, no modo "Enviar como resposta"). Você monta um texto usando as variáveis mapeadas. Se deixar em branco, o JSON completo de retorno é enviado para a IA processar.

Use sempre a saída customizada. Ao invés de mandar o JSON inteiro para a IA, filtre apenas o que ela precisa saber. Isso melhora a precisão da resposta e reduz o risco de alucinação.

Exemplo — buscar e atualizar lead no CRM

Um padrão comum é usar ferramentas em sequência. O agente busca o lead e, com o resultado em mãos, atualiza o status, tudo na mesma conversa.

buscar_lead — busca o cadastro pelo email. Retorna nome, ID e status atual do lead. O agente usa essas informações para continuar a conversa com contexto.

atualizar_status_lead — recebe o ID retornado pela ferramenta anterior e um novo status, e atualiza o registro no CRM.

No prompt:

Ao iniciar, use buscar_lead com o email do contato.
Após qualificar o lead, use atualizar_status_lead com o ID retornado
e o status identificado (quente, morno ou frio).

Gerar uma saída


É um tipo mais avançado. Ao invés de continuar a conversa, ele interrompe a execução do agente e devolve o controle para o Flow Builder com dados estruturados que o fluxo pode usar para tomar decisões.


Mais indicado para automações que exigem multiplas etapas

Quando usar

Use quando o agente precisa ser um ponto de decisão dentro de um fluxo maior:

  • O agente qualifica o lead e retorna o tipo de interesse para o fluxo rotear para o vendedor favorito do cliente

  • O agente identifica o tipo de demanda e retorna o departamento correto para o fluxo transferir

  • O agente coleta dados (como CPF ou código de pedido) e os devolve para o fluxo usar nas etapas seguintes

Como funciona

Quando o agente aciona essa ferramenta, ele encerra sua execução e o bloco de agente no Flow Builder gera uma ramificação de saída. Cada saída configurada vira um caminho diferente que o fluxo pode seguir. As variáveis retornadas ficam disponíveis como $tool.nome_variavel nas etapas seguintes.

Boas práticas gerais

Nomeie ferramentas como verbos. buscar_pedido, enviar_catalogo, registrar_lead deixam claro o que a ferramenta faz. Evite nomes vagos como ferramenta1 ou webhook_crm.

A descrição é a instrução da IA. Escreva pensando em quando acionar a ferramenta, não apenas o que ela faz.

Referencie no prompt. Mesmo com uma boa descrição, reforce no prompt quando e como usar cada ferramenta. Isso garante consistência.

Dados sensíveis — use "Enviar como resposta". Para dados financeiros, médicos ou críticos, use o modo que envia o resultado diretamente ao cliente sem passar pela IA.

Encadeamento de ferramentas. Quando o fluxo exige múltiplas ações, configure a sequência no prompt e certifique-se de que a segunda ferramenta usa como parâmetro o retorno da primeira.