---
title: Function Tools
description: Como criar uma Function Tool (ferramenta HTTP) para o Agent chamar um sistema seu — campos, parâmetros, credencial, teste, o que é enviado e o que volta.
---

# Function Tools

Uma **Function Tool** é uma ferramenta que você mesmo cria para o Agent chamar **um endpoint HTTP do seu sistema**. Use quando a ação que você precisa não existe no CRM nativo nem no [catálogo de MCP](/guia/agents/mcp-servers): consultar o andamento de um processo no sistema do escritório, gerar um boleto num ERP próprio, registrar um lead numa planilha interna.

Para o Agent, ela é só mais uma ferramenta: tem um nome e uma descrição. Quando a conversa pede, o Agent decide chamá-la, monta os dados e recebe a resposta do seu sistema.

## Como funciona, de ponta a ponta

<Passos>
  <Passo>

O Agent lê o **nome** e a **descrição** da ferramenta e decide que precisa dela (ex.: o cliente perguntou "como está meu processo?").

  </Passo>
  <Passo>

O Agent monta um objeto JSON com os dados e chama a ferramenta.

  </Passo>
  <Passo>

A plataforma faz um `POST` na URL que você cadastrou, com esse objeto no corpo e, se houver, a credencial no cabeçalho `Authorization`.

  </Passo>
  <Passo>

Seu sistema responde. A plataforma entrega o texto da resposta ao Agent, que usa a informação para responder ao cliente.

  </Passo>
</Passos>

## Criar uma Function Tool

<Passos>
  <Passo>

No Agent, abra o passo **Ferramentas** e, na seção **Ferramentas do agente**, clique em **Adicionar ferramenta**. Abre o **Catálogo de Ferramentas**.

<Captura legenda="Passo Ferramentas do assistente, com a seção 'Ferramentas do agente' e o botão 'Adicionar ferramenta'." src="/img/agents-wizard-ferramentas.png" />

  </Passo>
  <Passo>

Na barra lateral do catálogo, escolha **Custom HTTP** e clique em **Criar ferramenta HTTP** (ou **Criar Function Tool**, se a lista estiver vazia). Abre a janela **Nova Function Tool**, com um formulário em quatro seções à esquerda e uma pré-visualização ao vivo à direita.

<Captura legenda="Aba Custom HTTP do Catálogo de Ferramentas, ainda sem Function Tools, com os botões Criar ferramenta HTTP e Criar Function Tool." src="/img/function-tools-catalogo.png" />

<Captura legenda="Janela Nova Function Tool preenchida com o exemplo consultar_status_processo, com a pré-visualização ao vivo à direita." src="/img/function-tool-nova.png" />

  </Passo>
  <Passo>

**Identidade**

| Campo | Obrigatório | O que colocar |
|---|---|---|
| **Nome** | Sim | Identificador curto, sem espaços nem acentos, em `snake_case`. Ex.: `consultar_status_processo`. É o nome da função que o modelo vê. |
| **Descrição** | Sim | Até 500 caracteres. Quando usar e **quais dados enviar**. É com base nela que o modelo decide e monta a chamada (veja o aviso abaixo). |

  </Passo>
  <Passo>

**Endpoint**

| Campo | O que colocar |
|---|---|
| **URL** | Endereço `https://` público do seu endpoint. |
| **Timeout** | Em milissegundos, de 1000 a 120000. Padrão 15000 (15 segundos). |

O seletor de método (GET, POST, PUT, PATCH, DELETE) também está nesta seção. Leia o aviso sobre o método abaixo.

  </Passo>
  <Passo>

**Parâmetros**

Clique em **Adicionar parâmetro** para cada dado. Cada linha tem nome, tipo (Texto, Número, Número inteiro, Verdadeiro/falso, Lista, Objeto), descrição e a opção **obrigatório**. Quem prefere pode clicar em **Editar JSON** e escrever o JSON Schema direto.

  </Passo>
  <Passo>

**Headers & Segurança**

| Campo | O que colocar |
|---|---|
| **Headers** | Pares nome/valor. Veja o aviso abaixo antes de usar. |
| **Credencial (opcional)** | O token da sua API. É guardado criptografado e nunca mais exibido; a tela mostra só uma versão mascarada. É enviado como `Authorization: Bearer <token>`. |

  </Passo>
  <Passo>

Clique em **Criar Function Tool**. A ferramenta aparece na lista e já pode ser adicionada ao Agent.

  </Passo>
  <Passo>

**Adicione ao Agent e publique.** No catálogo, selecione a ferramenta. Ela vira um card em **Ferramentas do agente**, com um botão liga/desliga. Depois, publique o Agent novamente para a mudança valer nas conversas.

  </Passo>
</Passos>

## O que a plataforma envia de verdade

<Cuidado>

**Leia esta seção antes de integrar seu sistema.** Hoje a execução da ferramenta durante a conversa é mais simples do que o formulário sugere:

| No formulário | O que acontece na conversa |
|---|---|
| **Método** (GET, PUT...) | A chamada é **sempre `POST`**, qualquer que seja o método escolhido. |
| **Headers** | **Não são enviados.** Vão só `Content-Type: application/json` e, se houver credencial, `Authorization: Bearer <token>`. |
| **Parâmetros** | O modelo **não recebe** a lista de parâmetros que você montou. Ele vê a ferramenta com um único argumento livre chamado `payload`. |
| Corpo da requisição | `{"payload": { ...o que o modelo montou... }}` |

Na prática, para a ferramenta funcionar bem hoje:

1. Seu endpoint deve aceitar **`POST`** com JSON.
2. Seu endpoint deve ler os dados dentro da chave **`payload`**.
3. A autenticação deve ser por **`Authorization: Bearer`** (use o campo **Credencial**).
4. **Escreva na Descrição os nomes e formatos dos campos** que o modelo deve enviar no `payload`. É a única forma de o modelo saber.

Os campos de método, headers e parâmetros continuam úteis como documentação da ferramenta (e são usados pelo botão **Testar**), mas não mudam a chamada feita durante a conversa.

</Cuidado>

### Exemplo completo

**Configuração:**

| Campo | Valor |
|---|---|
| Nome | `consultar_status_processo` |
| Descrição | Consulta o andamento de um processo no sistema interno do escritório. Use quando o cliente perguntar como está o processo dele. Envie em `payload` o campo `numero_cnj` (texto, formato 0000000-00.0000.0.00.0000) e, opcionalmente, `incluir_movimentacoes` (true/false). |
| URL | `https://api.escritorio.com.br/v1/processos/status` |
| Timeout | `15000` |
| Credencial | o token da API do sistema |

**Parâmetros** (como documentação):

```json
{
  "type": "object",
  "properties": {
    "numero_cnj": { "type": "string", "description": "Número CNJ do processo" },
    "incluir_movimentacoes": { "type": "boolean", "description": "Retornar as últimas movimentações" }
  },
  "required": ["numero_cnj"]
}
```

**Requisição que seu sistema recebe:**

```http
POST /v1/processos/status HTTP/1.1
Host: api.escritorio.com.br
Content-Type: application/json
Authorization: Bearer <token>

{"payload": {"numero_cnj": "1234567-89.2025.8.26.0100", "incluir_movimentacoes": true}}
```

**O que o Agent recebe de volta:** o corpo da sua resposta, como texto, dentro de `{"result": "..."}`. Responda com algo que o modelo entenda fácil, por exemplo:

```json
{"status": "Em andamento", "ultima_movimentacao": "Conclusos para sentença em 02/10/2026"}
```

## Regras e limites

| Item | Regra |
|---|---|
| URL | Precisa ser `https://` com endereço público. Endereços de rede interna (`localhost`, `10.x`, `192.168.x`, `127.x` etc.) são recusados. |
| Portas | 443 ou acima de 1023. As portas 8080, 8443, 9090, 9200, 5432, 6379 e 11211 são bloqueadas. |
| Timeout | De 1 a 120 segundos. Se estourar, a chamada falha. Não há nova tentativa automática. |
| Tamanho da resposta | Só os primeiros **8 KB** chegam ao Agent. O resto é cortado. Responda só o necessário. |
| Resposta com erro (fora de 2xx) | O Agent recebe só o aviso de que a chamada falhou com aquele código, **sem** o corpo da resposta. |
| Dados da conversa | O contato, a conversa e o workspace **não** são enviados automaticamente. Se seu sistema precisa de algum deles, peça ao modelo (na descrição) para incluir no `payload` o que ele souber. |
| Nome | Até 100 caracteres. Use `snake_case`, sem espaços nem acentos. |
| Descrição | Até 500 caracteres. |

<Cuidado>

**Se a ferramenta não puder ser montada, o Agent não responde.** Quando a plataforma prepara o Agent para uma conversa, ela confere cada Function Tool (configuração, credencial e segurança da URL). Se uma delas falhar, por exemplo porque o domínio passou a apontar para um endereço interno, o Agent inteiro falha naquela execução, não só a ferramenta. Se um Agent parou de responder logo depois de mexer numa Function Tool, comece por ela.

</Cuidado>

## Testar

O botão **Testar** aparece quando você **edita** uma ferramenta já salva (e também no ícone **Testar ferramenta** do card). O resultado aparece na pré-visualização: sucesso ou falha, código HTTP, tempo em milissegundos e os primeiros 500 caracteres da resposta.

<Cuidado>

O teste **não reproduz exatamente** a chamada da conversa: ele usa o método e os headers do formulário, **não envia corpo** e **não envia a credencial**. Serve para confirmar que a URL está acessível. Para validar o comportamento real, teste o Agent no [Playground](/guia/agents/playground) e abra a **Trilha de execução** para ver a chamada e a resposta.

</Cuidado>

## Editar, desligar, remover e excluir

- **Desligar** — o botão liga/desliga do card, em **Ferramentas do agente**, tira a ferramenta daquele Agent sem apagar nada.
- **Configurar** — a engrenagem (**Configurar ferramenta**) abre a edição.
- **Remover do Agent** — a lixeira do card (**Remover ferramenta**) desvincula a ferramenta do Agent.
- **Excluir** — no catálogo, **Excluir ferramenta** apaga a ferramenta e a credencial dela, e a remove de todos os Agents. Não dá para desfazer.

Mudanças no vínculo (adicionar, remover, ligar, desligar) só valem depois de [publicar o Agent de novo](/guia/agents/publicacao-e-versoes).

## Permissões

| Ação | Quem pode |
|---|---|
| Criar, editar, testar, excluir | Quem pode **editar agents** (Workspace Admin, Manager, Suporte). |
| Gravar ou trocar a **Credencial** | Só quem pode **gerenciar credenciais** (Workspace Admin e Suporte). Um Manager edita a ferramenta normalmente, mas recebe "Você não tem permissão para gerenciar credenciais de ferramentas" ao preencher o campo Credencial. |

## Saiba mais

- [Ferramentas do Agent](/guia/agents/ferramentas) — visão geral
- [MCP Servers](/guia/agents/mcp-servers) — quando o sistema já tem um servidor MCP pronto
- [Requisição HTTP no Flow Builder](/guia/flow-builder/dados/http) — para chamadas fixas, sem decisão da IA