跳转到主要内容

​
使用 PHP SDK 运行

当你想从 PHP 中向智能体发送消息时,请使用官方的 fetch-hive/sdk Composer 包。该 SDK 封装了公开的 POST /v1/agent/invoke 端点,处理身份验证,以生成器(generator)的形式公开流式响应,并接受多模态输入。

​
安装

composer require fetch-hive/sdk
该 SDK 需要 PHP 8.1+,并使用 Guzzle 作为其 HTTP 客户端。

​
身份验证

将 FETCH_HIVE_API_KEY 环境变量设置为你的工作区 API 密钥(客户端会自动读取): 
export FETCH_HIVE_API_KEY=fhk_...

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

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();
或显式传入密钥: 
$client = new FetchHive(['api_key' => 'fhk_...']);
请参阅 API Keys 了解如何创建和轮换密钥。

​
基本示例

向智能体发送消息并读取最终响应: 
<?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'];
请参阅非流式响应结构。

​
方法参考

键类型必填说明
agentstring是智能体 ID
messagestring是你想发送的消息
thread_idstring否标识持久会话线程的任意字符串
messagesarray否调用方管理的对话历史。每一项格式为:['role' => 'user' | 'assistant' | 'system', 'content' => string]。
image_urlsstring[]否用于多模态输入、附加到当前 message 的 HTTPS 图像 URL
userstring否在用户追踪中显示的不透明调用方标识符
metadataarray否由调用方定义的扁平元数据,用于审计和日志筛选。请参阅调用元数据
该 SDK 为 invokeAgent 注入 streaming: false。要进行流式调用,请使用 invokeAgentStream(见下文)。

​
处理响应

$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

​
流式

使用 invokeAgentStream 在事件到达时接收 Server-Sent Events。该方法返回一个 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,
    };
}
该流会产出在 Invoke Agent → Response 中记录的相同事件类型:summary(在自动摘要触发时)、reasoning、response、tool、最终的 usage 事件,或在提供商在流过程中失败时的 error 事件。

​
多轮对话

​
持久化线程

将任意字符串作为 thread_id 传入,Fetch Hive 会在首次调用时创建该线程,并在每次使用相同值的后续调用中恢复该线程: 
$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',
]);

​
无状态历史

自行管理状态,在 messages 中传入先前的回合。Fetch Hive 会将提供的历史用作上下文,但不会持久化: 
$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.'],
    ],
]);

​
多模态输入

使用 image_urls 在当前消息上附加图像: 
$result = $client->invokeAgent([
    'agent'      => 'vision-agent',
    'message'    => 'Describe this image',
    'image_urls' => ['https://example.com/photo.jpg'],
]);
echo $result['response'];
URL 必须以 https:// 开头。

​
配置

选项默认值说明
api_keyFETCH_HIVE_API_KEY 环境变量控制台中的 Bearer 令牌
base_urlhttps://api.fetchhive.com/v1覆盖 API 基础 URL
timeout120请求超时(秒)
$client = new FetchHive([
    'api_key'  => 'fhk_...',
    'base_url' => 'https://api.fetchhive.com/v1',
    'timeout'  => 120.0,
]);

​
错误

非 2xx 响应会抛出 FetchHive\Sdk\Exception\ApiException,携带状态码和响应体: 
use FetchHive\Sdk\Exception\ApiException;

try {
    $reply = $client->invokeAgent([
        'agent'   => 'AGENT_UUID',
        'message' => 'Hello',
    ]);
} catch (ApiException $e) {
    error_log('Fetch Hive error: ' . $e->getMessage());
}
请参阅错误和速率限制了解状态码含义。

​
链接

​
下一步