Custom Tools

Crie ferramentas HTTP personalizadas para integrar APIs externas aos seus agentes

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

Acessar menu de configurações

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.

Informações básicas da ferramenta

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.

Configuração do Endpoint

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

Headers de autenticação

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.

Configurar parâmetros

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

Tratamento de erros

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.

Salvar Custom Tool

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

Acessar configurações do 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

Adicionar Custom Tool ao 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.

Verificar configuração

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

Reutilização de ferramentas

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

Colaboração em equipe

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

API de consulta 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

API 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": "[e-mail]"
    }
  ]
}

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

API de e-commerce

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

Práticas de segurança

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

Otimização de performance

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

Problemas comuns

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!