adachsoft/http-tool

AI Tool for making HTTP requests with strict URL policies and response limits.

v0.1.0 2026-02-04 06:05 UTC

Requires

• php: ^8.2
• adachsoft/ai-tool-call: ^2.0.1
• guzzlehttp/guzzle: ^7.10

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4
• rector/rector: ^2.3.3

MIT

• Arkadiusz Adach

• http
• Guzzle
• tool
• Agent
• ai
• llm

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

Key	Type	Required	Description
max_body_size	int	Yes	Maximum response body size in bytes. Larger bodies are truncated.
blocked_url_prefixes	string[]	No	List of URL prefixes that are strictly forbidden.
allowed_url_prefixes	string[] | null	No	List of allowed URL prefixes. If null (or omitted), all URLs are allowed (except blocked ones).
default_headers	map<string, string>	No	Default HTTP headers added to every request (can be overridden by the agent).

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