Run with PHP SDK

Invoke an agent from PHP with the fetch-hive/sdk Composer package

Use the official fetch-hive/sdk Composer package when you want to send a message to an agent from PHP. The SDK wraps the public POST /v1/agent/invoke endpoint, handles authentication, exposes streaming responses as a generator, and accepts multimodal inputs.

Installation

composer require fetch-hive/sdk

The SDK requires PHP 8.1+ and uses Guzzle as its HTTP client.

Authentication

Set the FETCH_HIVE_API_KEY environment variable to your workspace API key (the client reads it automatically):

export FETCH_HIVE_API_KEY=fhk_...

<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();

Or pass the key explicitly:

$client = new FetchHive(['api_key' => 'fhk_...']);

See API Keys for how to create and rotate keys.

Basic example

Send a message to an agent and read the final response:

<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();

$reply = $client->invokeAgent([
    'agent'   => 'AGENT_UUID',
    'message' => 'Summarize the latest AI infrastructure trends',
]);

echo $reply['response'];

See the non-streaming response shape.

Method reference

Key	Type	Required	Description
agent	string	Yes	The agent ID
message	string	Yes	The message you want to send
thread_id	string	No	An arbitrary string identifying a persistent conversation thread
messages	array	No	Caller-managed conversation history. Each item: ['role' => 'user' | 'assistant' | 'system', 'content' => string].
image_urls	string[]	No	HTTPS image URLs attached to the current message for multimodal inputs
user	string	No	Opaque caller identifier surfaced in User Tracking
metadata	array	No	Flat caller-defined metadata for audit and log filtering. See Invoke metadata

The SDK injects streaming: false for invokeAgent. To stream, use invokeAgentStream (below).

Handling the response

$reply = $client->invokeAgent([
    'agent'   => 'AGENT_UUID',
    'message' => 'Hello',
]);

echo $reply['response'];        // final text
echo $reply['model'];           // model identifier
print_r($reply['usage']);       // token usage breakdown
echo $reply['request_id'];      // use this to look up the run in Logs
print_r($reply['tool_calls']);  // tool invocations made during the run

Streaming

Use invokeAgentStream to receive Server-Sent Events as they arrive. The method returns a Generator:

foreach ($client->invokeAgentStream([
    'agent'     => 'AGENT_UUID',
    'message'   => 'Summarize the latest AI infrastructure trends',
    'thread_id' => 'user-456-support-session',
]) as $chunk) {
    match ($chunk['type']) {
        'response' => print($chunk['response'] ?? ''),
        'tool'     => print("\nCalling tool: " . ($chunk['tool'] ?? '')),
        'usage'    => print("\n\nUsage: " . json_encode($chunk['usage'])),
        default    => null,
    };
}

The stream yields the same event types documented in Invoke Agent → Response: summary (when auto-summarization fires), reasoning, response, tool, a final usage event, or an error event if the provider fails mid-stream.

Multi-turn conversations

Persistent threads

Pass any string as thread_id and Fetch Hive will create the thread on the first call and resume it on subsequent calls with the same value:

$client->invokeAgent([
    'agent'     => 'AGENT_UUID',
    'message'   => 'What are the main AI infrastructure trends right now?',
    'thread_id' => 'user-456-support-session',
]);

$client->invokeAgent([
    'agent'     => 'AGENT_UUID',
    'message'   => 'Which of those trends have the most enterprise adoption?',
    'thread_id' => 'user-456-support-session',
]);

Stateless history

Manage state yourself by passing the previous turns in messages. Fetch Hive uses the supplied history for context but does not persist it:

$client->invokeAgent([
    'agent'    => 'AGENT_UUID',
    'message'  => 'Which of those trends have the most enterprise adoption?',
    'messages' => [
        ['role' => 'user',      'content' => 'What are the main AI infrastructure trends right now?'],
        ['role' => 'assistant', 'content' => 'Teams are focusing on evals, tool routing, and observability.'],
    ],
]);

Multimodal inputs

Attach images to the current message with image_urls:

$result = $client->invokeAgent([
    'agent'      => 'vision-agent',
    'message'    => 'Describe this image',
    'image_urls' => ['https://example.com/photo.jpg'],
]);
echo $result['response'];

URLs must start with https://.

Configuration

Option	Default	Description
api_key	FETCH_HIVE_API_KEY env var	Bearer token from the dashboard
base_url	https://api.fetchhive.com/v1	Override the API base URL
timeout	120	Request timeout in seconds

$client = new FetchHive([
    'api_key'  => 'fhk_...',
    'base_url' => 'https://api.fetchhive.com/v1',
    'timeout'  => 120.0,
]);

Errors

Non-2xx responses throw FetchHive\Sdk\Exception\ApiException carrying the status code and response body:

use FetchHive\Sdk\Exception\ApiException;

try {
    $reply = $client->invokeAgent([
        'agent'   => 'AGENT_UUID',
        'message' => 'Hello',
    ]);
} catch (ApiException $e) {
    error_log('Fetch Hive error: ' . $e->getMessage());
}

See Errors and Rate Limits for status code meanings.

Links

• Package on Packagist

• Source on GitHub

Next steps

• Run with API - The same flow with cURL

• Run with Python SDK

• Run with Node.js SDK

• Run with Ruby SDK

• Invoke Agent - Full endpoint reference