Ferramentas: conectar o agente aos seus próprios sistemas

Para que serve uma ferramenta

Uma ferramenta é um endereço HTTPS que roda no seu sistema (um endpoint de API). O agente o chama quando necessário durante uma conversa: por exemplo, para ler a disponibilidade de horários, o status de envio ou o saldo de um cliente no seu sistema.

Use uma ferramenta para qualquer sistema sem integração pronta. Abra “Ferramentas” no menu; adicionar, editar, excluir e testar ferramentas exigem a função de proprietário ou administrador.

Adicionar uma nova ferramenta

1. Pressione “Nova ferramenta”.
2. Escreva o “Nome da ferramenta” em minúsculas com sublinhados, por exemplo, check_availability.
3. Em “Quando deve ser usada?”, descreva claramente o que a ferramenta faz e para quais perguntas deve ser chamada. O agente decide quando chamá-la a partir dessa descrição.
4. Informe o método (GET ou POST) e o endereço. O endereço deve começar com https; endereços locais e de rede privada são recusados.
5. Use “Adicionar campo” para definir os campos que a ferramenta espera: nome, tipo, descrição e se é obrigatório. O agente preenche esses campos com a conversa. Os tipos são explicados abaixo.
6. Escolha a “Autenticação”: nenhuma, token Bearer ou um cabeçalho personalizado (com o nome dele). O segredo fica guardado no servidor e nunca mais é mostrado; deixe em branco ao editar para manter o valor salvo.
7. Antes de salvar, teste com valores de exemplo usando “Chamada de teste”; você vê a resposta ou o erro na hora.

Tipos de campo e campos aninhados

Todo campo tem um tipo, e o valor é enviado ao seu endpoint nesse tipo. Por exemplo, um campo “Sim/Não” é enviado como true, não como o texto “true”, e um campo “Número” digitado como 1,234.5 é enviado como 1234.5.

• Texto, Número, Sim/Não: um único valor. Um campo Sim/Não entende yes, no, true, false, 1 e 0.
• Data: você pode escrever 06.10.2026 (dia primeiro) ou 2026-10-06; é enviado como 2026-10-06. Data e hora: por exemplo, 06.10.2026 14:30; é enviado como 2026-10-06T14:30:00.
• Objeto: um grupo com subcampos próprios, por exemplo, um cliente (nome, e-mail). Se você não adicionar subcampos, o valor é enviado como está, em JSON livre.
• Lista: vários valores. Escolha o “Tipo de item”; se o item for um Objeto, defina os campos dele, por exemplo, linhas de pedido (ID do produto, quantidade).

Os campos podem ser aninhados até 5 níveis. Objeto e Lista só podem ser escolhidos em ferramentas POST; uma requisição GET não carrega dados aninhados.

Em ferramentas POST, um “Corpo de exemplo” aparece abaixo dos campos: o formato do corpo JSON que seu endpoint vai receber. Você pode compará-lo com o que seu endpoint espera. Na “Chamada de teste”, cada campo tem uma entrada adequada ao tipo; campos Objeto e Lista abrem preenchidos com o corpo de exemplo.

Se um valor não corresponder ao tipo do campo (por exemplo, “muitos” em um campo Número) ou um campo obrigatório estiver vazio, a requisição não é enviada; o erro diz qual é o campo, por exemplo, items[1].id (o campo id do segundo item).

Ferramentas que alteram dados

Se a ferramenta alterar algo no seu sistema (criar um registro, um cancelamento etc.), marque “Esta ferramenta altera dados”. Essas ferramentas nunca são repetidas com valores diferentes, e toda chamada é registrada. Elas aparecem na lista com o selo “Altera dados”.

Usar uma ferramenta em um agente

• Na aba “Ferramentas” da etapa Assistente de IA, escolha quais ferramentas o agente pode acessar: todas (incluindo as adicionadas depois) ou as selecionadas.
• Uma etapa “Seleção” pode carregar as opções de uma ferramenta; por exemplo, horários livres aparecem como cards.
• Uma etapa “Chamada de ferramenta” chama a ferramenta em um ponto específico do fluxo, sem IA, e salva a resposta em uma variável.

Veja os artigos Etapa Assistente de IA, Etapa Seleção e Etapa Chamada de ferramenta.

Gerenciar a lista

Busque ferramentas por nome ou descrição e filtre por método e tipo de autenticação. Ferramentas com falha têm o selo “Falhando”. Quando você exclui uma ferramenta, o agente para de chamá-la.