API

Empower your agents to interact with external services by making configurable HTTP requests.

This tool enables your agents to connect with REST endpoints, web services, and external data sources using standard HTTP methods like GET and POST.

💡 Core Concepts

To configure this tool effectively, it is important to understand how static and dynamic data work together.

1. Tool Config vs. Agent Payload

The API tool combines settings you define in advance (in your YAML file) with data the agent generates on the fly.

• Tool Configuration: These are fixed settings defined in your YAML file. This is best for authentication keys (using Key Vault), base URLs, and timeout settings that shouldn't change.
• Agent Payload: These are dynamic values generated by the agent (LLM) at runtime. This is ideal for search queries, specific data payloads, or dynamic path parameters.

2. Safety & Restrictions

To ensure security and stability, the API tool enforces specific boundaries:

• Private Networks Blocked: Agents cannot access local networks (e.g., localhost, 192.168.x.x).
• Content Filtering: Binary files (images, audio, PDF, ZIP) are blocked to prevent context overflow.
• Limits: Responses are capped at 20,000 characters, and the maximum timeout is 60 seconds.

---

⚙️ 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.
http_method	string	"get"	The HTTP method (e.g., get, post, put, delete).
headers	map	-	Static headers (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: 60.0).

Agent Payload (Dynamic)

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

Field	Type	Description
params	map	Dynamic query parameters to append to the URL.
body	map	The request body content.
url	string	Optional override for the target URL.

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_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.

create_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 Request (Advanced)

Use Case: Allowing the agent to decide the endpoint or method dynamically.

create_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 arbitrary URL access
            timeout: 15.0

---

🚑 Troubleshooting

• Blocked Requests

  • Private IPs: Requests to localhost, 127.0.0.1, or local LAN IPs are strictly blocked for security.
  • Invalid URLs: Ensure the URL includes the scheme (e.g., https://).

• Data Limits & Timeouts

  • Content: Large downloads (>4MB) or binary files (PDFs, Images) will be aborted.
  • Truncation: Responses over 20,000 characters may be summarized to fit the LLM context.
  • Timeout: If the external API takes longer than 60 seconds, the request will fail.

• Unsupported HTTP method

  • Check for typos in your http_method. Supported values: get, post, put, patch, delete, head, options.