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

> Create custom HTTP tools to integrate external APIs with your agents

## Overview

**Custom Tools** allows you to create custom HTTP tools to integrate any external API with your agents. This functionality offers maximum flexibility to:

* **Integrate third-party REST APIs**
* **Create domain-specific tools**
* **Configure custom authentication**
* **Define dynamic parameters** and validations
* **Manage errors** and timeouts robustly

<Note>
  **HTTP Tools**: Unlike MCP servers, here you configure direct HTTP calls to REST APIs.
  Ideal for simple and specific integrations.
</Note>

## How to Configure Custom Tools

The Custom Tools configuration process has been divided into two main steps:

1. **Register the Custom Tool** in the settings menu
2. **Select the Custom Tool** in the agent settings

### Part 1: Register Custom Tool

<AccordionGroup>
  <Accordion icon="gear" title="Access settings menu">
    1. In the main menu, go to **"Settings"**
    2. Look for the **"Tools & Integrations"** section
    3. Within it, click on **"Custom Tools"**
    4. Click on **"Add New Custom Tool"** or **"New Custom Tool"**
    5. You will be directed to the registration form

    <Info>
      Here you will create a library of Custom Tools that can be reused across different agents.
    </Info>
  </Accordion>

  <Accordion icon="info" title="Basic tool information">
    Configure the fundamental information of your tool:

    **Name:**

    * Tool identifier name
    * Used to reference the tool
    * Example: `search_user`, `send_email`, `check_inventory`

    **Description:**

    * Clear description of what the tool does
    * Helps you and other users understand the functionality
    * Example: "Searches detailed user information by ID"

    <Tip>
      Use descriptive names and clear descriptions to facilitate later selection in agents.
    </Tip>
  </Accordion>

  <Accordion icon="globe" title="Endpoint configuration">
    Configure your tool's HTTP endpoint:

    **Method (HTTP Method):**

    * `GET` - To fetch data
    * `POST` - To create new resources
    * `PUT` - To update complete resources
    * `PATCH` - For partial updates
    * `DELETE` - To remove resources

    **Endpoint URL:**

    * Complete API URL that will be called
    * Can include dynamic variables using `{variable}`
    * Example: `https://api.example.com/users/{userId}/profile`
  </Accordion>

  <Accordion icon="key" title="Authentication headers">
    Configure headers necessary for authentication:

    **Common headers:**

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

    <Warning>
      Authentication headers are stored encrypted on the platform.
    </Warning>
  </Accordion>

  <Accordion icon="gear" title="Configure parameters">
    Configure all necessary parameters:

    **Body Parameters** (for POST/PUT/PATCH):

    * Name, type, description and whether it's required
    * Example: `name` (string, required), `email` (string, required)

    **Path Parameters**:

    * Variables that are part of the URL
    * Example: `{userId}` in `/users/{userId}`

    **Query Parameters**:

    * Query parameters in the URL
    * Example: `?limit=10&offset=0`

    **Default Values**:

    * Default values for any parameter
    * Used when the parameter is not provided
  </Accordion>

  <Accordion icon="shield" title="Error handling">
    Configure how to handle errors:

    * **Timeout**: Time limit in seconds (recommended: 10-30)
    * **Fallback Error Code**: Default error code
    * **Fallback Error Message**: User-friendly message for errors

    <Tip>
      Configure appropriate timeouts to avoid freezing on slow APIs.
    </Tip>
  </Accordion>

  <Accordion icon="check" title="Save Custom Tool">
    1. **Review all configurations** carefully
    2. **Test the configuration** if there's a test option
    3. Click **"Save"**
    4. The Custom Tool will be available in your library

    <Info>
      After saving, the Custom Tool will be available to be selected in any agent.
    </Info>
  </Accordion>
</AccordionGroup>

### Part 2: Select Custom Tool in Agent

<AccordionGroup>
  <Accordion icon="robot" title="Access agent settings">
    1. Go to the **agents screen** in the dashboard
    2. Locate the agent you want to configure
    3. Click on the **"Settings"** icon (⚙️) on the agent card and then on **"Edit"**
    4. You will be directed to the agent settings screen
  </Accordion>

  <Accordion icon="plus" title="Add Custom Tool to agent">
    1. In the agent settings screen, locate the **"Custom Tools"** section
    2. Click **"Add"** to add a Custom Tool
    3. A **list of registered Custom Tools** will be displayed
    4. **Select the tools** that this agent should use
    5. Click **"Save"** to apply

    <Info>
      You can select multiple Custom Tools for the same agent. Each agent can have a different set of tools.
    </Info>
  </Accordion>

  <Accordion icon="check" title="Verify configuration">
    **After saving:**

    * Selected Custom Tools will appear in the agent's list
    * The agent will be able to use these tools during conversations
    * You can add/remove tools at any time

    <Tip>
      Test the agent in a conversation to verify that the Custom Tools are working correctly.
    </Tip>
  </Accordion>
</AccordionGroup>

## Advantages of the New System

<AccordionGroup>
  <Accordion icon="recycle" title="Tool reusability">
    **Benefits:**

    * 🔄 **Reuse** the same Custom Tool across multiple agents
    * 🎯 **Specialize** agents with specific tools
    * 🛠️ **Maintain** centralized configurations
    * 📊 **Manage** all tools in one place
  </Accordion>

  <Accordion icon="users" title="Team collaboration">
    **Facilitates teamwork:**

    * 👥 **Share** Custom Tools among team members
    * 📚 **Centralized library** of organizational tools
    * 🔧 **Simplified maintenance** of integrations
    * 📈 **Tool evolution** without impact on agents
  </Accordion>
</AccordionGroup>

## Practical Examples

### ZIP Code Search Tool

<AccordionGroup>
  <Accordion icon="map" title="ZIP code query API">
    **Complete configuration (in Custom Tools registration):**

    ```json theme={null}
    {
      "name": "search_zipcode",
      "description": "Searches address information by ZIP code",
      "method": "GET",
      "endpoint": "https://viacep.com.br/ws/{cep}/json/",
      "path_parameters": [
        {
          "name": "cep",
          "description": "ZIP code in format 12345678",
          "required": true
        }
      ],
      "headers": [
        {
          "name": "Accept",
          "value": "application/json"
        }
      ],
      "error_handling": {
        "timeout": 10,
        "fallback_error_code": "zipcode_not_found",
        "fallback_error_message": "ZIP code not found or invalid"
      }
    }
    ```

    **Usage in agent:**

    1. Access agent settings
    2. Go to Custom Tools
    3. Select "search\_zipcode" from the list
    4. Save the configuration
  </Accordion>
</AccordionGroup>

### Email Sending Tool

<AccordionGroup>
  <Accordion icon="envelope" title="Email sending API">
    **Complete configuration (in Custom Tools registration):**

    ```json theme={null}
    {
      "name": "send_email",
      "description": "Sends email through the email API",
      "method": "POST",
      "endpoint": "https://api.emailservice.com/send",
      "headers": [
        {
          "name": "Authorization",
          "value": "Bearer your-api-key"
        },
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "body_parameters": [
        {
          "name": "to",
          "type": "string",
          "description": "Recipient's email",
          "required": true
        },
        {
          "name": "subject",
          "type": "string",
          "description": "Email subject",
          "required": true
        },
        {
          "name": "message",
          "type": "string",
          "description": "Email content",
          "required": true
        }
      ],
      "default_values": [
        {
          "name": "from",
          "value": "noreply@company.com"
        }
      ]
    }
    ```

    **Usage in agent:**

    1. Tool registered centrally
    2. Selected in agent settings
    3. Available for immediate use
  </Accordion>
</AccordionGroup>

### Product Search Tool

<AccordionGroup>
  <Accordion icon="cart-shopping" title="E-commerce API">
    **Complete configuration (in Custom Tools registration):**

    ```json theme={null}
    {
      "name": "search_products",
      "description": "Searches products in the store catalog",
      "method": "GET",
      "endpoint": "https://api.store.com/products",
      "headers": [
        {
          "name": "X-API-Key",
          "value": "your-api-key"
        }
      ],
      "query_parameters": [
        {
          "name": "search",
          "description": "Search term",
          "required": false
        },
        {
          "name": "category",
          "description": "Filter by category",
          "required": false
        },
        {
          "name": "limit",
          "description": "Maximum number of results",
          "required": false
        }
      ],
      "default_values": [
        {
          "name": "limit",
          "value": "20"
        }
      ]
    }
    ```

    **Usage in agent:**

    1. Configure once in Custom Tools menu
    2. Reuse in as many agents as needed
    3. Centralized and simplified maintenance
  </Accordion>
</AccordionGroup>

## Best Practices

### Security and Authentication

<AccordionGroup>
  <Accordion icon="shield" title="Security practices">
    **Important recommendations:**

    * 🔐 **Use HTTPS** whenever possible
    * 🔑 **Store API keys** in headers, not in the URL
    * ⏱️ **Configure adequate timeouts** (10-30 seconds)
    * 🛡️ **Validate required parameters**
    * 📝 **Document each parameter** well

    **Recommended security headers:**

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

### Performance and Reliability

<AccordionGroup>
  <Accordion icon="gauge" title="Performance optimization">
    **Optimization strategies:**

    * ⚡ **Appropriate timeouts** - Not too long nor too short
    * 🎯 **Specific parameters** - Avoid fetching unnecessary data
    * 💰 **Consider costs** - APIs may have usage limits
    * 🔄 **Implement retry** when appropriate
    * 📊 **Monitor performance** of calls

    <Tip>
      Configure timeouts between 10-30 seconds depending on API complexity.
    </Tip>
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion icon="triangle-exclamation" title="Common problems">
    **Authentication error (401/403):**

    * Check if the API key is correct
    * Confirm the Authorization header format
    * Test the API directly first
    * Check if the key hasn't expired

    **Request timeout:**

    * Increase the timeout value
    * Check if the API is responding
    * Consider optimizing query parameters
    * Test API speed externally

    **Parameters not working:**

    * Check the syntax of variables `{name}`
    * Confirm names match exactly
    * Test with fixed values first
    * Validate the format expected by the API

    **Response format error:**

    * Check if the API returns valid JSON
    * Confirm appropriate Accept headers
    * Test the API response directly
    * Check external API documentation
  </Accordion>
</AccordionGroup>

***

🔧 **Custom Tool configured!** Now you can integrate any REST API with your agents with complete configuration of parameters, authentication, and error handling!