Atende Direito · Docs

Tema

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: 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 ​

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

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

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

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

Criar uma Function Tool ​

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

    Passo Ferramentas do assistente, com a seção 'Ferramentas do agente' e o botão 'Adicionar ferramenta'.

    Passo Ferramentas do assistente, com a seção 'Ferramentas do agente' e o botão 'Adicionar ferramenta'.

  2. 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.

    Aba Custom HTTP do Catálogo de Ferramentas, ainda sem Function Tools, com os botões Criar ferramenta HTTP e Criar Function Tool.

    Aba Custom HTTP do Catálogo de Ferramentas, ainda sem Function Tools, com os botões Criar ferramenta HTTP e Criar Function Tool.

    Janela Nova Function Tool preenchida com o exemplo consultar_status_processo, com a pré-visualização ao vivo à direita.

    Janela Nova Function Tool preenchida com o exemplo consultar_status_processo, com a pré-visualização ao vivo à direita.

  3. Identidade

    CampoObrigatórioO que colocar
    NomeSimIdentificador curto, sem espaços nem acentos, em snake_case. Ex.: consultar_status_processo. É o nome da função que o modelo vê.
    DescriçãoSimAté 500 caracteres. Quando usar e quais dados enviar. É com base nela que o modelo decide e monta a chamada (veja o aviso abaixo).

  4. Endpoint

    CampoO que colocar
    URLEndereço https:// público do seu endpoint.
    TimeoutEm 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.

  5. 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.

  6. Headers & Segurança

    CampoO que colocar
    HeadersPares 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>.

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

  8. 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.

O que a plataforma envia de verdade ​

Exemplo completo ​

Configuração:

CampoValor
Nomeconsultar_status_processo
DescriçãoConsulta 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).
URLhttps://api.escritorio.com.br/v1/processos/status
Timeout15000
Credencialo 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 ​

ItemRegra
URLPrecisa ser https:// com endereço público. Endereços de rede interna (localhost, 10.x, 192.168.x, 127.x etc.) são recusados.
Portas443 ou acima de 1023. As portas 8080, 8443, 9090, 9200, 5432, 6379 e 11211 são bloqueadas.
TimeoutDe 1 a 120 segundos. Se estourar, a chamada falha. Não há nova tentativa automática.
Tamanho da respostaSó 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 conversaO 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.
NomeAté 100 caracteres. Use snake_case, sem espaços nem acentos.
DescriçãoAté 500 caracteres.

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.

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.

Permissões ​

AçãoQuem pode
Criar, editar, testar, excluirQuem pode editar agents (Workspace Admin, Manager, Suporte).
Gravar ou trocar a CredencialSó 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 ​