README

Official PHP SDK for Fetch Hive — invoke AI prompts, workflows, and agents from your application.

Installation

Requirements: PHP 8.1+ and Composer.

composer require fetch-hive/sdk

Quick start

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

use FetchHive\Sdk\FetchHive;

$client = new FetchHive(apiKey: getenv('FETCH_HIVE_API_KEY'));

Get your API key from the Fetch Hive dashboard.

Invoke a prompt

$result = $client->invokePrompt([
    'deployment' => 'my-prompt',
    'inputs'     => ['name' => 'Alice', 'topic' => 'machine learning'],
    'metadata' => [],
]);
echo $result['response'];

Invoke a prompt (streaming)

foreach ($client->invokePromptStream([
    'deployment' => 'my-prompt',
    'inputs'     => ['name' => 'Alice'],
]) as $chunk) {
    match ($chunk['type']) {
        'response' => print($chunk['response'] ?? ''),
        'usage'    => print("\nUsage: " . json_encode($chunk['usage'])),
        default    => null,
    };
}

Invoke a workflow

$run = $client->invokeWorkflow([
    'deployment' => 'my-workflow',
    'inputs'     => ['customer_id' => '42'],
    'metadata' => [],
]);
echo $run['status'] . PHP_EOL;
print_r($run['output']);

Invoke a workflow (async)

$run = $client->invokeWorkflow([
    'deployment'   => 'my-workflow',
    'inputs'       => ['customer_id' => '42'],
    'async_mode'   => true,
    'callback_url' => 'https://example.com/webhook',
]);
echo 'Queued: ' . $run['run_id'];

Invoke an agent

$reply = $client->invokeAgent([
    'agent'    => 'my-agent',
    'message'  => 'What is the weather in London?',
    'metadata' => [],
]);
echo $reply['response'];

Metadata

Pass optional metadata on prompt, workflow, or agent invokes to attach flat audit fields for log display and filtering. Metadata values must be strings, numbers, booleans, or null.

Invoke an agent (streaming)

foreach ($client->invokeAgentStream([
    'agent'     => 'my-agent',
    'message'   => 'What is the weather in London?',
    'thread_id' => 'session-abc123',  // optional — persist conversation history
]) as $chunk) {
    match ($chunk['type']) {
        'response' => print($chunk['response'] ?? ''),
        'tool'     => print("\nCalling tool: " . $chunk['tool']),
        'usage'    => print("\nUsage: " . json_encode($chunk['usage'])),
        default    => null,
    };
}

Multimodal (image) inputs

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

Authentication

Pass the API key to the constructor or set the environment variable:

export FETCH_HIVE_API_KEY=fhk_...

$client = new FetchHive();  // picks up FETCH_HIVE_API_KEY automatically

Configuration

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

Version

0.2.6

License

MIT — see LICENSE.

fetch-hive / sdk

Maintainers

Package info

Statistics

Security