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

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

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

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

Here you will create a library of Custom Tools that can be reused across different agents.

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”

Use descriptive names and clear descriptions to facilitate later selection in agents.

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

Authentication headers

Configure headers necessary for authentication:

Common headers:

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

Authentication headers are stored encrypted on the platform.

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

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

Configure appropriate timeouts to avoid freezing on slow APIs.

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

After saving, the Custom Tool will be available to be selected in any agent.

Part 2: Select Custom Tool in Agent

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

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

You can select multiple Custom Tools for the same agent. Each agent can have a different set of tools.

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

Test the agent in a conversation to verify that the Custom Tools are working correctly.

Advantages of the New System

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

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

Practical Examples

ZIP Code Search Tool

ZIP code query API

Complete configuration (in Custom Tools registration):

{
  "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

Email Sending Tool

Email sending API

Complete configuration (in Custom Tools registration):

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

Usage in agent:

1. Tool registered centrally
2. Selected in agent settings
3. Available for immediate use

Product Search Tool

E-commerce API

Complete configuration (in Custom Tools registration):

{
  "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

Best Practices

Security and Authentication

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:

{
  "Authorization": "Bearer secure-token",
  "X-API-Key": "private-api-key",
  "User-Agent": "EvoAI-Agent/1.0"
}

Performance and Reliability

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

Configure timeouts between 10-30 seconds depending on API complexity.

Troubleshooting

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

---

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