Skip to main content

​
Visão Geral

O Custom Tools permite que você crie ferramentas HTTP personalizadas para integrar qualquer API externa aos seus agentes. Esta funcionalidade oferece máxima flexibilidade para:
  • Integrar APIs REST de terceiros
  • Criar ferramentas específicas para seu domínio
  • Configurar autenticação personalizada
  • Definir parâmetros dinâmicos e validações
  • Gerenciar erros e timeouts de forma robusta
Ferramentas HTTP: Diferente dos servidores MCP, aqui você configura chamadas HTTP diretas para APIs REST. Ideal para integrações simples e específicas.

​
Como Configurar Custom Tools

O processo de configuração das Custom Tools foi dividido em duas etapas principais:
  1. Cadastrar a Custom Tool no menu de configurações
  2. Selecionar a Custom Tool nas configurações do agente

​
Parte 1: Cadastrar Custom Tool

  1. No menu principal, vá para “Configurações”
  2. Procure pela seção “Tools & Integrations”
  3. Dentro dela, clique em “Custom Tools”
  4. Clique em “Adicionar Nova Custom Tool” ou “New Custom Tool”
  5. Você será direcionado para o formulário de cadastro
Aqui você criará uma biblioteca de Custom Tools que poderão ser reutilizadas em diferentes agentes.
Configure as informações fundamentais da sua ferramenta:Name (Nome):
  • Nome identificador da ferramenta
  • Usado para referenciar a ferramenta
  • Exemplo: buscar_usuario, enviar_email, consultar_estoque
Description (Descrição):
  • Descrição clara do que a ferramenta faz
  • Ajuda você e outros usuários a entender a funcionalidade
  • Exemplo: “Busca informações detalhadas de um usuário pelo ID”
Use nomes descritivos e descrições claras para facilitar a seleção posterior nos agentes.
Configure o endpoint HTTP da sua ferramenta:Method (Método HTTP):
  • GET - Para buscar dados
  • POST - Para criar novos recursos
  • PUT - Para atualizar recursos completos
  • PATCH - Para atualizações parciais
  • DELETE - Para remover recursos
Endpoint URL:
  • URL completa da API que será chamada
  • Pode incluir variáveis dinâmicas usando {variavel}
  • Exemplo: https://api.exemplo.com/users/{userId}/profile
Configure headers necessários para autenticação:Headers comuns:
{
  "Authorization": "Bearer seu-token-aqui",
  "Content-Type": "application/json",
  "X-API-Key": "sua-api-key",
  "Accept": "application/json"
}
Headers de autenticação são armazenados de forma criptografada na plataforma.
Configure todos os parâmetros necessários:Body Parameters (para POST/PUT/PATCH):
  • Nome, tipo, descrição e se é obrigatório
  • Exemplo: nome (string, required), email (string, required)
Path Parameters:
  • Variáveis que fazem parte da URL
  • Exemplo: {userId} em /users/{userId}
Query Parameters:
  • Parâmetros de consulta na URL
  • Exemplo: ?limit=10&offset=0
Default Values:
  • Valores padrão para qualquer parâmetro
  • Usado quando o parâmetro não for fornecido
Configure como lidar com erros:
  • Timeout: Tempo limite em segundos (recomendado: 10-30)
  • Fallback Error Code: Código de erro padrão
  • Fallback Error Message: Mensagem amigável para erros
Configure timeouts apropriados para evitar travamentos em APIs lentas.
  1. Revise todas as configurações cuidadosamente
  2. Teste a configuração se houver opção de teste
  3. Clique em “Salvar” ou “Save”
  4. A Custom Tool ficará disponível na sua biblioteca
Após salvar, a Custom Tool estará disponível para ser selecionada em qualquer agente.

​
Parte 2: Selecionar Custom Tool no Agente

  1. Vá para a tela de agentes no dashboard
  2. Localize o agente que deseja configurar
  3. Clique no ícone de “Configurações” (⚙️) no card do agente e em seguida em “Editar”
  4. Você será direcionado para a tela de configurações do agente
  1. Na tela de configurações do agente, localize a seção “Custom Tools”
  2. Clique em “Add” para adicionar uma Custom Tool
  3. Uma lista das Custom Tools cadastradas será exibida
  4. Selecione as ferramentas que este agente deve usar
  5. Clique em “Salvar” para aplicar
Você pode selecionar múltiplas Custom Tools para o mesmo agente. Cada agente pode ter um conjunto diferente de ferramentas.
Após salvar:
  • As Custom Tools selecionadas aparecerão na lista do agente
  • O agente poderá usar essas ferramentas durante conversas
  • Você pode adicionar/remover ferramentas a qualquer momento
Teste o agente em uma conversa para verificar se as Custom Tools estão funcionando corretamente.

​
Vantagens do Novo Sistema

Benefícios:
  • 🔄 Reutilizar a mesma Custom Tool em múltiplos agentes
  • 🎯 Especializar agentes com ferramentas específicas
  • 🛠️ Manter configurações centralizadas
  • 📊 Gerenciar todas as ferramentas em um lugar
Facilita trabalho em equipe:
  • 👥 Compartilhar Custom Tools entre membros da equipe
  • 📚 Biblioteca centralizada de ferramentas organizacionais
  • 🔧 Manutenção simplificada de integrações
  • 📈 Evolução das ferramentas sem impacto nos agentes

​
Exemplos Práticos

​
Ferramenta de Busca de CEP

Configuração completa (no cadastro de Custom Tools):
{
  "name": "buscar_cep",
  "description": "Busca informações de endereço pelo CEP",
  "method": "GET",
  "endpoint": "https://viacep.com.br/ws/{cep}/json/",
  "path_parameters": [
    {
      "name": "cep",
      "description": "CEP no formato 12345678",
      "required": true
    }
  ],
  "headers": [
    {
      "name": "Accept",
      "value": "application/json"
    }
  ],
  "error_handling": {
    "timeout": 10,
    "fallback_error_code": "cep_not_found",
    "fallback_error_message": "CEP não encontrado ou inválido"
  }
}
Uso no agente:
  1. Acesse configurações do agente
  2. Vá para Custom Tools
  3. Selecione “buscar_cep” da lista
  4. Salve a configuração

​
Ferramenta de Envio de Email

Configuração completa (no cadastro de Custom Tools):
{
  "name": "enviar_email",
  "description": "Envia email através da API de email",
  "method": "POST",
  "endpoint": "https://api.emailservice.com/send",
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer sua-api-key"
    },
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ],
  "body_parameters": [
    {
      "name": "to",
      "type": "string",
      "description": "Email do destinatário",
      "required": true
    },
    {
      "name": "subject",
      "type": "string",
      "description": "Assunto do email",
      "required": true
    },
    {
      "name": "message",
      "type": "string",
      "description": "Conteúdo do email",
      "required": true
    }
  ],
  "default_values": [
    {
      "name": "from",
      "value": "noreply@empresa.com"
    }
  ]
}
Uso no agente:
  1. Ferramenta cadastrada centralmente
  2. Selecionada nas configurações do agente
  3. Disponível para uso imediato

​
Ferramenta de Consulta de Produtos

Configuração completa (no cadastro de Custom Tools):
{
  "name": "buscar_produtos",
  "description": "Busca produtos no catálogo da loja",
  "method": "GET",
  "endpoint": "https://api.loja.com/produtos",
  "headers": [
    {
      "name": "X-API-Key",
      "value": "sua-chave-api"
    }
  ],
  "query_parameters": [
    {
      "name": "search",
      "description": "Termo de busca",
      "required": false
    },
    {
      "name": "categoria",
      "description": "Filtrar por categoria",
      "required": false
    },
    {
      "name": "limit",
      "description": "Número máximo de resultados",
      "required": false
    }
  ],
  "default_values": [
    {
      "name": "limit",
      "value": "20"
    }
  ]
}
Uso no agente:
  1. Configure uma vez no menu de Custom Tools
  2. Reutilize em quantos agentes precisar
  3. Manutenção centralizada e simplificada

​
Boas Práticas

​
Segurança e Autenticação

Recomendações importantes:
  • 🔐 Use HTTPS sempre que possível
  • 🔑 Armazene API keys nos headers, não na URL
  • ⏱️ Configure timeouts adequados (10-30 segundos)
  • 🛡️ Valide parâmetros obrigatórios
  • 📝 Documente bem cada parâmetro
Headers de segurança recomendados:
{
  "Authorization": "Bearer token-seguro",
  "X-API-Key": "chave-api-privada",
  "User-Agent": "EvoAI-Agent/1.0"
}

​
Performance e Confiabilidade

Estratégias de otimização:
  • ⚡ Timeouts apropriados - Não muito longos nem muito curtos
  • 🎯 Parâmetros específicos - Evite buscar dados desnecessários
  • 💰 Considere custos - APIs podem ter limites de uso
  • 🔄 Implemente retry quando apropriado
  • 📊 Monitore performance das chamadas
Configure timeouts entre 10-30 segundos dependendo da complexidade da API.

​
Solução de Problemas

Erro de autenticação (401/403):
  • Verifique se a API key está correta
  • Confirme o formato do header Authorization
  • Teste a API diretamente primeiro
  • Verifique se a chave não expirou
Timeout da requisição:
  • Aumente o valor do timeout
  • Verifique se a API está respondendo
  • Considere otimizar os parâmetros da consulta
  • Teste a velocidade da API externamente
Parâmetros não funcionam:
  • Verifique a sintaxe das variáveis {nome}
  • Confirme se os nomes coincidem exatamente
  • Teste com valores fixos primeiro
  • Valide o formato esperado pela API
Erro de formato de resposta:
  • Verifique se a API retorna JSON válido
  • Confirme os headers Accept apropriados
  • Teste a resposta da API diretamente
  • Verifique documentação da API externa
🔧 Custom Tool configurada! Agora você pode integrar qualquer API REST aos seus agentes com configuração completa de parâmetros, autenticação e tratamento de erros!
⌘I