> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 PHP SDK 运行

> 使用 fetch-hive/sdk Composer 包从 PHP 调用智能体

# 使用 PHP SDK 运行

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

## 安装

```bash theme={null}
composer require fetch-hive/sdk
```

该 SDK 需要 PHP 8.1+,并使用 Guzzle 作为其 HTTP 客户端。

## 身份验证

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

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```php theme={null}
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive();
```

或显式传入密钥:

```php theme={null}
$client = new FetchHive(['api_key' => 'fhk_...']);
```

请参阅 [API Keys](../workspace/api-keys) 了解如何创建和轮换密钥。

## 基本示例

向智能体发送消息并读取最终响应:

```php theme={null}
<?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'];
```

请参阅[非流式响应结构](../api-reference/agents/invoke#response)。

## 方法参考

| 键           | 类型       | 必填 | 说明                                                                                      |
| ----------- | -------- | -- | --------------------------------------------------------------------------------------- |
| `agent`     | `string` | 是  | 智能体 ID                                                                                  |
| `message`   | `string` | 是  | 你想发送的消息                                                                                 |
| `thread_id` | `string` | 否  | 标识持久会话线程的任意字符串                                                                          |
| `messages`  | `array`  | 否  | 调用方管理的对话历史。每一项格式为:`['role' => 'user' \| 'assistant' \| 'system', 'content' => string]`。 |
| `user`      | `string` | 否  | 在[用户追踪](../user-tracking/overview)中显示的不透明调用方标识符                                         |
| `metadata`  | `array`  | 否  | 由调用方定义的扁平元数据,用于审计和日志筛选。请参阅[调用元数据](../user-tracking/invoke-metadata)                     |

该 SDK 为 `invokeAgent` 注入 `streaming: false`。要进行流式调用,请使用 `invokeAgentStream`(见下文)。

## 处理响应

```php theme={null}
$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`:

```php theme={null}
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](../api-reference/agents/invoke#response) 中记录的相同事件类型:`summary`(在自动摘要触发时)、`reasoning`、`response`、`tool`、最终的 `usage` 事件,或在提供商在流过程中失败时的 `error` 事件。

## 多轮对话

### 持久化线程

将任意字符串作为 `thread_id` 传入,Fetch Hive 会在首次调用时创建该线程,并在每次使用相同值的后续调用中恢复该线程:

```php theme={null}
$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 会将提供的历史用作上下文,但不会持久化:

```php theme={null}
$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.'],
    ],
]);
```

## 多模态输入

使用 `attachments` 在当前消息上附加图像:

```php theme={null}
$result = $client->invokeAgent([
    'agent'      => 'vision-agent',
    'message'    => 'Describe this image',
    'attachments' => ['https://example.com/photo.jpg'],
]);
echo $result['response'];
```

URL 必须以 `https://` 开头。

## 配置

| 选项         | 默认值                            | 说明              |
| ---------- | ------------------------------ | --------------- |
| `api_key`  | `FETCH_HIVE_API_KEY` 环境变量      | 控制台中的 Bearer 令牌 |
| `base_url` | `https://api.fetchhive.com/v1` | 覆盖 API 基础 URL   |
| `timeout`  | `120`                          | 请求超时(秒)         |

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

## 错误

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

```php theme={null}
use FetchHive\Sdk\Exception\ApiException;

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

请参阅[错误和速率限制](../api-reference/errors-and-rate-limits)了解状态码含义。

## 链接

* [Packagist 上的包](https://packagist.org/packages/fetch-hive/sdk)
* [GitHub 上的源代码](https://github.com/Fetch-Hive/php-sdk)

## 下一步

* [通过 API 运行](./run-with-api) - 使用 cURL 的相同流程
* [使用 Python SDK 运行](./run-with-python-sdk)
* [使用 Node.js SDK 运行](./run-with-nodejs-sdk)
* [使用 Ruby SDK 运行](./run-with-ruby-sdk)
* [Invoke Agent](../api-reference/agents/invoke) - 完整端点参考