README

adachsoft/http-tool is a PHP library that provides an SPI implementation for adachsoft/ai-tool-call. It exposes an http_tool that allows AI agents to perform controlled HTTP requests (GET, POST, PUT, DELETE) with strict security policies and response size limits.

Features

• Strict URL Policy: Whitelist and blacklist URL prefixes to control where the agent can send requests.
• Response Limiting: Automatically truncates large response bodies to prevent context overflow.
• Error Handling: Returns structured error information (e.g., url_not_allowed, response_too_large, transport_error) instead of throwing exceptions, allowing the agent to react.
• Guzzle Integration: Uses Guzzle for robust HTTP communication.

Installation

composer require adachsoft/http-tool

Configuration

The tool is configured via a ConfigMap passed to the HttpToolFactory.

Configuration Keys

Example

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\HttpTool\Tool\HttpToolFactory;

$config = new ConfigMap([
    'max_body_size' => 4096, // Limit responses to 4KB
    'blocked_url_prefixes' => ['http://localhost', 'http://127.0.0.1'], // Block local access
    'allowed_url_prefixes' => ['https://api.example.com', 'https://public-api.com'], // Whitelist
    'default_headers' => [
        'User-Agent' => 'MyAIApp/1.0',
    ],
]);

$factory = new HttpToolFactory();
$tool = $factory->create($config);

// Register $tool with your ToolRegistry...

Tool Usage (AI Agent)

The agent invokes the tool http_tool with the following parameters:

• method (string, required): GET, POST, PUT, or DELETE.
• url (string, required): Full URL.
• headers (map, optional): Custom headers.
• query (map, optional): Query parameters.
• body (string, optional): Request body.

Response Structure

The tool returns a structured result:

{
  "status_code": 200,
  "reason_phrase": "OK",
  "headers": { ... },
  "body": "{ ... }",
  "body_truncated": false,
  "error_type": null,
  "error_message": null,
  "request_method": "GET",
  "request_url": "https://api.example.com/data"
}

License

MIT