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

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.

---

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:

{
  "status_code": 200,
  "body": {
    "user": {
      "id": "123",
      "name": "John Doe",
      "email": "[e-mail]"
    }
  }
}

Error Response

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

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

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

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

---

API Reference

See Public API v1 Reference for programmatic tool management.

---

Related Documentation

• Tools Description Guide - Best practices for tool descriptions
• Tools Overview - Tool configuration
• Agents - Agent configuration