API

Make HTTP requests to external APIs with support for flexible configuration and safety controls.

This tool allows your agents to interact with REST endpoints, web services, and external data sources using standard HTTP methods.

💡 Core Concepts

The API tool combines static configuration (defined by you) with dynamic parameters (generated by the agent) to construct requests. Used properly, it allows agents to interact with any public API on the internet.

1. Tool Config vs. Agent Payload

• Tool Configuration: Fixed settings defined in your YAML. Best for authentication keys, base URLs, and timeout settings.
• Agent Payload: Dynamic values generated by the LLM at runtime. Best for search queries, dynamic paths, or specific data payloads.

---

⚙️ Configuration Reference

Tool Configuration (config)

These parameters are set in your agent's YAML configuration block.

Field	Type	Default	Description
url	string	Required	The target URL. Can be a full URL or a base URL that the agent appends to.
http_method	string	"get"	The HTTP method to use. Supported: get, post, put, patch, delete, head, options.
headers	map	-	Static headers to send with every request (e.g., Authorization, Content-Type).
params	map	-	Default query parameters to include in every request.
body	map	-	Default body content.
timeout	float	60.0	Request timeout in seconds. Max is 60.0.

Agent Payload (What the LLM Sends)

The agent (LLM) can dynamically provide these fields when calling the tool.

Field	Type	Description
params	map	Dynamic query parameters to append to the URL. (Alias: query)
body	map/any	The request body content. (Alias: payload)
url	string	Optional. Overrides or modifies the configured URL if allowed by your agent logic.

Helper

Need to convert JSON payloads or configs to YAML? Check out our JSON to YAML Conversion Guide.

---

📚 Practical Recipes (Examples)

Recipe 1: Simple GET Request

Use Case: Fetching public data from a known endpoint (e.g., Weather).

create_vertical_agent_network:
  agent-1:
    agent_name: WeatherBot
    LLM_config:
        params:
          model: gpt-5-nano
    tools:
      tool_assigned:
        - name: API
          config:
            url: "https://api.weatherapi.com/v1/current.json"
            http_method: "get"
            params:
              key: "YOUR_API_KEY_HERE" # Static API Key
    agent_function:
      - "Check the weather using the generic API tool."

Recipe 2: POST Request with Authentication

Use Case: Sending data to a secured API endpoint, like posting a message to a Slack webhook or external CRM.

create_vertical_agent_network:
  agent-1:
    agent_name: DataSubmitter
    tools:
      tool_assigned:
        - name: API
          config:
            url: "https://api.example.com/v1/users"
            http_method: "post"
            headers:
              Authorization: "Bearer sk-12345"
              Content-Type: "application/json"
            timeout: 30.0

Recipe 3: Flexible/Dynamic Request

Use Case: Allowing the agent to decide the endpoint or method (Advanced).

create_vertical_agent_network:
  agent-1:
    agent_name: GeneralBrowser
    tools:
      tool_assigned:
        - name: API
          config:
            # Minimal config allows agent max flexibility
            # Warning: ensure you trust the agent with random URL access
            timeout: 15.0

---

🚑 Troubleshooting & Restrictions

• Blocked Requests

  • Private Networks: Requests to local network addresses are strictly blocked.
    • Blocked: localhost, 127.0.0.1, 192.168.x.x, 10.x.x.x, 172.16.x.x (private ranges), and IPv6 loopback/link-local.
    • The tool resolves domains to their IP addresses and blocks connections if they resolve to private IPs.
  • Blocked File Types:
    • The tool checks both the MIME type and content headers.
    • Blocked: application/pdf, application/zip, application/x-tar, application/gzip, application/octet-stream (binaries), and all image/, audio/, video/ types etc.
  • Invalid URLs: URLs must include the scheme (e.g., https:// is required).

• Data Limits & Timeouts

  • Max Download Size: 4MB if the response is a file with text content.
    • Downloads larger than this will be aborted.
  • Response Limit: 20,000 characters.
    • Responses exceeding this limit may be truncated or summarized to fit within LLM context limits.
  • Timeouts:
    • Default/Max Timeout: 60 seconds.
    • Redirect Limit: 5 redirects.

• "Unsupported HTTP method"

  • Check for typos in your http_method config. It must be one of: get, post, put, patch, delete, head, options.