# Guia de ferramentas ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/850c75e2-58df-40b9-b2be-4f3d0660f3d4/capa-tools%20%281%29.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=847f3dcedddd7597dd3d25f11c5da693ac8d5dfbeb5858f2e5ec61fa68ce7567&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =3640x1055") 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. ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/26f0ccd9-f1a5-4aa4-8894-be1cd81f3dc1/Captura%20de%20Tela%202026-04-02%20a%CC%80s%2015.08.40.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=38b3941f42ea6d2d62d5ad1caeec62fef79e6a0ea0cbb2944e917e2bc44e6b88&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =954x655") 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. ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/476aab49-4003-41ca-b15a-b9738df87463/Captura%20de%20Tela%202026-04-02%20a%CC%80s%2015.11.25.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=56b49c15fc11c77820397ee6681f3e22f656f60caede560911513ff603481e1e&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =954x655") --- ## 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. ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/b823801e-48e6-4c5d-ad7f-09ee580383e5/Captura%20de%20Tela%202026-04-02%20a%CC%80s%2015.12.35.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=a60094eb4cd2de400b069a01bc67b2786146be52a8836ea9a9dfc380bad8546f&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =954x655") #### Tipos de mensagem disponíveis --- ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/ca567ea4-5b87-4684-a0e7-f559e951255a/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=5e656361154f59d5f764aaa9c89f263b3cfebb7226dadb6f6e681951ecaeefab&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject "right-50 =420x755") 💬 **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. --- ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/0bb3790b-6a94-4543-971b-be6f7223bb32/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=7c4282dd54497e6cd907d735408f0a989c6c5a48016153f76684161692e54035&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject "right-50 =420x297") 🖼️ **Imagem** Envia uma imagem diretamente no WhatsApp. Ideal para fotos de produtos, banners promocionais ou qualquer visual relevante para a conversa. --- ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/ffd4b7d1-f655-449f-879f-eecb05570c51/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=8f1390860bd96ab2e4029a7d2dfd5186ec5f25d06b331efd06067f79ed7c7e23&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject "right-50 =420x662") 🎤 **Áudio** Envia um arquivo de áudio. Pode ser usado para mensagens de voz explicativas, instruções em formato de áudio ou apresentações. --- ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/ea6bade4-defa-470f-aa69-c1e49fb9290a/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=15aa78d1d6790e92379d0161e2758dfc1fbd9b6c3d514a49cede4bfa6cd7ebed&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject "right-50 =420x276") 📹 **Vídeo** Envia um vídeo. Ótimo para demonstrações de produto, tutoriais de uso ou apresentações institucionais. --- ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/c6af38cd-1f5d-47ad-bf1a-549b43498790/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=43d240fdf405fd38667e7bb33803b7f46728cde932239e4d254a4aff3e6044cc&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject "right-50 =420x268") 📄 **Arquivo** Envia qualquer arquivo: PDF, planilha, documento. O uso mais comum é envio de catálogos, contratos, manuais técnicos, boletos e fichas de produto. --- ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/417e89eb-b48c-4318-a475-e8d002881c91/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=8af560769ca4b35b04bf3cdb15bd76e1f6c24a098b1f10ed1897e3dfa0ca8455&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject "right-50 =420x273") 📍 **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. ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/7fc365e6-9ef5-4db9-bc40-f7165b1e178f/galeria.gif?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=03f7f56d95270e913d50ff00db133d2fc0827d988b0e23dd7a3e0536f0244223&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =850x632") :::tip 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 ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/a51cdc75-7e1d-45a7-8b1f-f2aae298fb07/Captura%20de%20Tela%202026-04-02%20a%CC%80s%2015.54.34.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=2f857d089cb4e91598167bf5d320a8bb7e5571fc2a9fa604b5001fc876a5d3b2&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =963x672") **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. :::tip "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. ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/fc38a034-4149-4797-9585-412f34eaa004/Captura%20de%20Tela%202026-04-02%20a%CC%80s%2015.55.45.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=91733b54be8d4229aa406ab796381f1c02c294b33277504e1cedcbbf68dcd61b&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =963x672") 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}}`. :::tip 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. ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/aeaf64d4-dd30-4ceb-9029-d32580d18745/Captura%20de%20Tela%202026-04-02%20a%CC%80s%2015.57.14.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=6f914d4ddb6778cda41f9c868b16e2f9ce9edd0ee88c2dc833830e01608204fd&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =963x672") **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 ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/662d95a3-6049-44ae-b74e-fbc3f71f40d7/Captura%20de%20Tela%202026-04-02%20a%CC%80s%2016.01.04.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=ee85201d2c0586c25402820a87df11d440c717d9dc45937bd0420c09deef5e5d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =963x725") **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. :::tip 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 ![](https://s3.us-east-2.amazonaws.com/convert-company-outline/uploads/a37daf54-af67-4e24-bdb6-ebce9f5a1da7/6ffcca74-9720-4eed-8e47-d3c39390b4e4/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAWNEQDAE74GWO55AJ%2F20261015%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20261015T203000Z&X-Amz-Expires=86400&X-Amz-Signature=6f44f2417a1030e32b6ff00032c39328b553e16bf9b505edba5f654bf8d3077c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject "right-50 =365x315") É 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.