> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evo-ai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  **Ferramentas HTTP**: Diferente dos servidores MCP, aqui você configura chamadas HTTP diretas para APIs REST.
  Ideal para integrações simples e específicas.
</Note>

## 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

<AccordionGroup>
  <Accordion icon="gear" title="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

    <Info>
      Aqui você criará uma biblioteca de Custom Tools que poderão ser reutilizadas em diferentes agentes.
    </Info>
  </Accordion>

  <Accordion icon="info" title="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"

    <Tip>
      Use nomes descritivos e descrições claras para facilitar a seleção posterior nos agentes.
    </Tip>
  </Accordion>

  <Accordion icon="globe" title="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`
  </Accordion>

  <Accordion icon="key" title="Headers de autenticação">
    Configure headers necessários para autenticação:

    **Headers comuns:**

    ```json theme={null}
    {
      "Authorization": "Bearer seu-token-aqui",
      "Content-Type": "application/json",
      "X-API-Key": "sua-api-key",
      "Accept": "application/json"
    }
    ```

    <Warning>
      Headers de autenticação são armazenados de forma criptografada na plataforma.
    </Warning>
  </Accordion>

  <Accordion icon="gear" title="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
  </Accordion>

  <Accordion icon="shield" title="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

    <Tip>
      Configure timeouts apropriados para evitar travamentos em APIs lentas.
    </Tip>
  </Accordion>

  <Accordion icon="check" title="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

    <Info>
      Após salvar, a Custom Tool estará disponível para ser selecionada em qualquer agente.
    </Info>
  </Accordion>
</AccordionGroup>

### Parte 2: Selecionar Custom Tool no Agente

<AccordionGroup>
  <Accordion icon="robot" title="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
  </Accordion>

  <Accordion icon="plus" title="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

    <Info>
      Você pode selecionar múltiplas Custom Tools para o mesmo agente. Cada agente pode ter um conjunto diferente de ferramentas.
    </Info>
  </Accordion>

  <Accordion icon="check" title="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

    <Tip>
      Teste o agente em uma conversa para verificar se as Custom Tools estão funcionando corretamente.
    </Tip>
  </Accordion>
</AccordionGroup>

## Vantagens do Novo Sistema

<AccordionGroup>
  <Accordion icon="recycle" title="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
  </Accordion>

  <Accordion icon="users" title="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
  </Accordion>
</AccordionGroup>

## Exemplos Práticos

### Ferramenta de Busca de CEP

<AccordionGroup>
  <Accordion icon="map" title="API de consulta de CEP">
    **Configuração completa (no cadastro de Custom Tools):**

    ```json theme={null}
    {
      "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
  </Accordion>
</AccordionGroup>

### Ferramenta de Envio de Email

<AccordionGroup>
  <Accordion icon="envelope" title="API de envio de email">
    **Configuração completa (no cadastro de Custom Tools):**

    ```json theme={null}
    {
      "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
  </Accordion>
</AccordionGroup>

### Ferramenta de Consulta de Produtos

<AccordionGroup>
  <Accordion icon="cart-shopping" title="API de e-commerce">
    **Configuração completa (no cadastro de Custom Tools):**

    ```json theme={null}
    {
      "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
  </Accordion>
</AccordionGroup>

## Boas Práticas

### Segurança e Autenticação

<AccordionGroup>
  <Accordion icon="shield" title="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:**

    ```json theme={null}
    {
      "Authorization": "Bearer token-seguro",
      "X-API-Key": "chave-api-privada",
      "User-Agent": "EvoAI-Agent/1.0"
    }
    ```
  </Accordion>
</AccordionGroup>

### Performance e Confiabilidade

<AccordionGroup>
  <Accordion icon="gauge" title="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

    <Tip>
      Configure timeouts entre 10-30 segundos dependendo da complexidade da API.
    </Tip>
  </Accordion>
</AccordionGroup>

## Solução de Problemas

<AccordionGroup>
  <Accordion icon="triangle-exclamation" title="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
  </Accordion>
</AccordionGroup>

***

🔧 **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!