Skip to main content
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

KeyTypeRequiredDescription
agentstringYesThe agent ID
messagestringYesThe message you want to send
thread_idstringNoAn arbitrary string identifying a persistent conversation thread
messagesarrayNoCaller-managed conversation history. Each item: ['role' => 'user' | 'assistant' | 'system', 'content' => string].
image_urlsstring[]NoHTTPS image URLs attached to the current message for multimodal inputs
userstringNoOpaque caller identifier surfaced in User Tracking
metadataarrayNoFlat 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

OptionDefaultDescription
api_keyFETCH_HIVE_API_KEY env varBearer token from the dashboard
base_urlhttps://api.fetchhive.com/v1Override the API base URL
timeout120Request 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.

​
Next steps