> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP Request Tool

> Make HTTP requests to external APIs from agents

The AGO HTTP Request Tool enables agents to make HTTP requests to external APIs, allowing integration with third-party services and custom backends.

## Overview

**Tool Name:** `ago_http_request`

This tool provides agents with the ability to call external REST APIs, enabling real-time data retrieval, integrations with external services, and custom workflow automation.

## Key Features

* Support for HTTP methods (GET, POST, PUT, DELETE)
* Custom headers and authentication
* JSON request/response handling
* SSRF protection (blocks internal IP ranges)

***

## Security

### SSRF Protection

The tool includes built-in Server-Side Request Forgery (SSRF) protection:

**Blocked IP Ranges:**

* Private networks: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
* Localhost: `127.0.0.0/8`
* Link-local: `169.254.0.0/16`
* Internal hostnames

> **Warning**: Attempts to access internal networks will be blocked and logged.

### Authentication Security

* API keys stored encrypted in `secret_key` field
* Credentials never exposed to users
* Support for bearer tokens, API keys, basic auth

***

## Configuration

### Create HTTP Tool

To create an HTTP request tool:

1. Navigate to **AI Studio** → **Tools**
2. Click **Create Tool**
3. Select **HTTP Request** as the tool type
4. Configure the basic settings:
   * **Name**: Internal identifier (e.g., "weather\_api")
   * **Display Name**: User-facing name (e.g., "Get Weather")
   * **Description**: What this tool does
   * **Prompt**: When the agent should use this tool
5. Configure the HTTP settings:
   * **Base URL**: The API endpoint (e.g., `https://api.weather.example.com`)
   * **Method**: GET, POST, PUT, or DELETE
   * **Headers**: Any required headers
   * **Secret Key**: API key or token (stored securely)
6. Define the **Input Schema** with parameters the agent can pass
7. Click **Save**
8. Assign the tool to your agent

### Configuration Fields

| Field     | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| base\_url | string | Yes      | Base URL for API requests  |
| method    | string | No       | HTTP method (default: GET) |
| headers   | object | No       | Default headers to include |

### Authentication Options

Put your credential in the **Secret Key** field and reference it from a header value with the `{{secret_key}}` placeholder. At request time, every `{{secret_key}}` in your headers is replaced with the stored secret. This keeps the credential out of the **Headers** JSON, which is not encrypted.

| Auth Type           | Header Name     | Header Value                   | Secret Key Contains        |
| ------------------- | --------------- | ------------------------------ | -------------------------- |
| API Key             | `X-API-Key`     | `{{secret_key}}`               | Your API key               |
| Bearer Token        | `Authorization` | `Bearer {{secret_key}}`        | Your bearer token          |
| Basic Auth          | `Authorization` | `Basic {{secret_key}}`         | Base64-encoded credentials |
| Custom token scheme | `Authorization` | `Token token="{{secret_key}}"` | Your API token             |

<Note>
  The **Secret Key** field is stored encrypted and is never exposed to users or in logs. The `{{secret_key}}` placeholder is replaced in header values only — put it directly in a header, not in the URL or request body.
</Note>

***

## Input Schema

Define parameters that agents can pass to the API. Common parameters include:

| Parameter | Type | Description                            |
| --------- | ---- | -------------------------------------- |
| body      | str  | JSON request body (for POST/PUT)       |
| params    | dict | Query parameters to include in the URL |

Add custom parameters based on what your API requires (e.g., `customer_id`, `search_query`, `filter_status`).

### Parameter Types

| Type   | Description      | Example            |
| ------ | ---------------- | ------------------ |
| str    | String value     | `"user-123"`       |
| int    | Integer value    | `42`               |
| bool   | Boolean value    | `true`             |
| str\[] | Array of strings | `["tag1", "tag2"]` |

***

## Request Building

### URL Construction

The request is sent to the configured `base_url`, with any `params` added as query parameters:

```
{base_url}?{params}
```

Example:

* base\_url: `https://api.example.com/users`
* params: `{"include": "profile", "limit": "10"}`
* Result: `https://api.example.com/users?include=profile&limit=10`

### Request Body

For POST/PUT requests:

1. Set the **Method** to POST or PUT
2. Add the `Content-Type: application/json` header
3. Define input schema parameters that will be sent in the request body

For example, a tool to send messages might have these input parameters:

* `user_email` (str): User's email address
* `message` (str): Message content

The agent will populate these values based on the conversation and send them as JSON in the request body.

***

## Response Handling

### Successful Response

The tool returns the API response to the agent:

```json theme={null}
{
  "status_code": 200,
  "body": {
    "user": {
      "id": "123",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}
```

### Error Response

```json theme={null}
{
  "status_code": 404,
  "error": "Not Found",
  "body": {
    "message": "User not found"
  }
}
```

***

## Examples

### Example 1: GET Request - Fetch Customer Data

| Setting          | Value                                                                               |
| ---------------- | ----------------------------------------------------------------------------------- |
| Name             | get\_customer\_info                                                                 |
| Display Name     | Get Customer Info                                                                   |
| Method           | GET                                                                                 |
| Base URL         | `https://crm.example.com/api/v1`                                                    |
| Headers          | `Authorization: Bearer {{secret_key}}`                                              |
| Input Parameters | `customer_id` (str) - Customer ID to look up                                        |
| Prompt           | "Use this tool to fetch customer details when the user provides their customer ID." |

### Example 2: POST Request - Create Sales Lead

| Setting          | Value                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| Name             | create\_lead                                                                                      |
| Display Name     | Create Sales Lead                                                                                 |
| Method           | POST                                                                                              |
| Base URL         | `https://sales.example.com/api`                                                                   |
| Headers          | `Content-Type: application/json`, `X-API-Key: {{secret_key}}`                                     |
| Input Parameters | `name` (str), `email` (str), `source` (enum: chat, form, referral)                                |
| Prompt           | "Use this tool when a user expresses interest in our product and wants to be contacted by sales." |

***

## Best Practices

### Tool Design

* **Single purpose**: One tool per API operation
* **Clear naming**: Describe what the tool does
* **Minimal inputs**: Only request necessary parameters
* **Default values**: Provide sensible defaults

### Security

* **Never expose credentials**: Use `secret_key` field
* **Limit permissions**: Use least-privilege API keys
* **Validate inputs**: Define strict input schemas
* **Log usage**: Monitor tool call patterns

### Performance

* **Handle errors**: Provide fallback behavior
* **Cache responses**: For frequently accessed data
* **Rate limit**: Respect API limits

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Issue: Request blocked by SSRF protection">
    **Problem**: Tool returns "Request blocked" error.

    **Solutions:**

    1. Verify URL is a public internet address
    2. Check for redirects to internal IPs
    3. Use public DNS names, not IP addresses
  </Accordion>

  <Accordion title="Issue: Authentication failures">
    **Problem**: API returns 401 or 403 errors.

    **Solutions:**

    1. Verify `secret_key` is correct
    2. Check header format (Bearer vs API key)
    3. Confirm API key has necessary permissions
    4. Check for key expiration
  </Accordion>

  <Accordion title="Issue: Invalid response parsing">
    **Problem**: Agent can't interpret API response.

    **Solutions:**

    1. Verify API returns expected JSON format
    2. Check for API version changes
    3. Review tool description to help the agent interpret the response

    ***
  </Accordion>
</AccordionGroup>

## API Reference

See [Public API v1 Reference](../api/public-api-v1) for programmatic tool management.

***

## Related Documentation

* [Tools Description Guide](../guides/tools-description) - Best practices for tool descriptions
* [Tools Overview](../features/tools) - Tool configuration
* [Agents](../agent/agents) - Agent configuration