> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/streaming.md).

# 流式传输

让用户在响应文本和界面块到达时立即看到，而不是盲目等待完整响应。

<figure><img src="https://99736354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGHx4l2LknIex7vFIUg1R%2Fuploads%2Fgit-blob-81daaa38ae7b2c87f2c759b32da89aaec04af465%2Fgenerative-ui.gif?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
使用 **`/neuron-streaming`** 用于教你的编码代理如何将代理响应流式传输到 UI。

[AI 辅助开发](https://docs.neuron-ai.dev/neuron-v3-zh/gai-lan/agentic-development.md)
{% endhint %}

要流式传输 AI 响应，你应使用 `stream()` 方法，而不是 `chat()`。此方法会准备代理工作流以使用 `StreamingNode` 而不是 `ChatNode`.

调用 `events()` 在返回的代理处理器上的方法，你将获得一个 PHP 生成器，可将流式内容作为可迭代对象来消费。

```php
use App\Neuron\MyAgent;
use NeuronAI\Chat\Messages\UserMessage;

$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->stream(new UserMessage('How are you?'));

// 逐块实时打印响应
foreach ($stream as $chunk) {
    echo $chunk->content;
}

// 我很好，谢谢！今天我能帮你什么？
```

### 流式块

当你处理代理的流式响应时，可以预期接收三种类型的块对象：

* `TextChunk`：表示一段文本
* `ReasoningChunk`：包含模型推理摘要的块（仅适用于推理模型）
* `ToolCallChunk`：表示 LLM 请求执行一个工具
* `ToolResultChunk`：包含工具执行结果

这些对象是代理内部完成任务时消息流与客户端侧所需数据之间的一层抽象，帮助你随时了解幕后发生了什么。

流的组成取决于你的代理实现。如果代理没有附加任何工具，就不可能收到一个 `ToolCallChunk` 或 `ToolResultChunk` 实例，因此你可以遍历输出流，并且只期待文本和推理块。

### 流式传输与工具

Neuron 支持将工具和函数调用与流式响应结合使用。你可以自由为代理提供工具，它们会在流的中途被自动处理，以继续生成最终响应。

当代理从 LLM 收到工具调用请求时，它会流式输出两种类型的块： `ToolCallChunk`, `ToolResultChunk`.

这些类包含被 LLM 调用的工具实例，因此你可以向客户端展示有关代理正在做什么以回答用户提示的详细输出。

下面是一个处理此场景的示例：

```php
use App\Neuron\MyAgent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Tools\Tool;

$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->addTool(
        Tool::make(
            'get_server_configuration',
            'retrieve the server network configuration'
        )->addProperty(...)->setCallable(...)
    )
    ->stream(
        new UserMessage("What's the IP address of the server?")
    );

// 遍历块
foreach ($stream as $chunk) {
    if ($chunk instanceof ToolCallChunk) {
        // 输出正在进行的工具调用
        echo "\n- 正在调用工具：".$chunk->tool->getName();
        echo "\n- 输入：".json_encode($chunk->tool->getInputs());
        continue;
    }
    
    if ($chunk instanceof ToolResultChunk) {
        echo "\n- 工具 ".$chunk->tool->getName()." 已完成";
        echo "\n- 结果：".$chunk->tool->getResult();
        continue;
    }
    
    // 处理 TextChunk 和 ReasoningChunk
    echo $chunk->content;
}

// 让我来获取服务器配置。 
// - 正在调用工具：get_server_configuration
// - 工具 get_server_configuration 已完成
// 服务器的 IP 地址是：192.168.0.10
```

### 获取最终结果

当模型完成流式输出后，你可以获取最终的 `AssistantMessage` 实例，使用 `getMessage()` 工作流处理器上的方法：

```php
$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->stream(...);

// 遍历块
foreach ($stream as $chunk) {
    // ...
}

$message = $stream->getResult()->getMessage(); // 获取最终消息实例
echo $message->getContent();
```

### 监控与调试

你使用 Neuron 构建的许多应用都会包含多个步骤以及多次 LLM 调用。随着这些应用变得越来越复杂，能够检查你的代理系统内部究竟发生了什么变得至关重要。做到这一点的最佳方式是使用 [Inspector](https://inspector.dev/)

{% embed url="<https://docs.inspector.dev/guides/neuron-ai>" %}

## 流式适配器

Neuron 的流式适配器系统提供了一种灵活、与协议无关的方式，帮助你轻松地将由 Neuron 驱动的代理与前端技术栈集成。

流式适配器会将 Neuron 的内部流式事件（文本块、工具调用、推理步骤）转换为特定前端协议的事件，例如 AG-UI。

这种架构使你无需修改核心代理逻辑，就能将 Neuron 代理与各种前端框架无缝集成。适配器负责处理协议相关的问题，例如消息生命周期事件、事件格式化和 ID 跟踪，同时在所有提供商（Anthropic、OpenAI、Gemini、Ollama 等）之间保持一致的流式行为。该系统具有高度可扩展性，你可以通过扩展 `SSEAdapter` 来实现流式数据转换，或者直接实现 `StreamAdapterInterface` 以满足自定义需求。

<figure><img src="https://99736354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGHx4l2LknIex7vFIUg1R%2Fuploads%2F0Vv4CSAloxu40vUoZddx%2Fstreaming-adapter.png?alt=media&amp;token=eb8846c3-eef5-415a-bb2e-108f1ecd0cf2" alt=""><figcaption></figcaption></figure>

你只需向以下方法提供一个适配器实例： `stream()` 代理中用于流式传输 LLM 响应的方法。

### Vercel AI SDK 适配器

用于 Vercel AI SDK 数据流协议的适配器： <https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol>

```php
use NeuronAI\Chat\Messages\Stream\Adapters\VercelAIAdapter;

// 指示代理
$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->setStreamAdapter(new VercelAIAdapter())
    ->stream(
        new UserMessage('What is the square root of 144?')
    );

// 处理响应
foreach ($stream as $line) {
    echo $line;
}
```

### AG-UI 适配器

实现了 AG-UI 协议定义的基于流式事件的协议，用于实时代理与前端交互。支持文本消息、工具调用、推理以及生命周期事件。

更多信息请访问： <https://docs.ag-ui.com/concepts/events>

```php
use NeuronAI\Chat\Messages\Stream\Adapters\AGUIAdapter;

// 指示代理
$stream = MyAgent::make()
    ->setThreadId('chat_id')
    ->setStreamAdapter(new AGUIAdapter('chat_id'))
    ->stream(
        new UserMessage('What is the square root of 144?')
    );

// 处理响应
foreach ($stream as $line) {
    echo $line;
}
```

#### 连接 AG-UI 前端

AG-UI 客户端（如 CopilotKit）并不只是打开一个连接。它会发送一个名为 `RunAgentInput`的 JSON 请求体，其中包含对话内容和当前运行的标识符：

```json
{
  "threadId": "thread_123",
  "runId": "run_456",
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "content": "144 的平方根是多少？"
    }
  ],
  "tools": [],
  "state": {},
  "context": [],
  "forwardedProps": {}
}
```

你的端点应读取此负载，将消息映射为 Neuron 消息对象，并传递 `threadId` 和 `runId` 给适配器构造函数。适配器会在 `RUN_STARTED` 和 `RUN_FINISHED` 事件中回传，因此客户端可以将流与其请求的运行关联起来。如果你省略它们，适配器会生成自己的标识符（这对测试很有用，但真正的 AG-UI 前端期望返回它自己的 ID）。

适配器还会通过以下方法提供 SSE 传输所需的 HTTP 标头： `getHeaders()` 方法。记得发送这些标头，并在每一行之后刷新输出，否则流可能会卡在 PHP 输出缓冲或代理中。

下面是一个完整的端点示例：

```php
use NeuronAI\Chat\Messages\Stream\Adapters\AGUIAdapter;
use NeuronAI\Chat\Messages\UserMessage;

// 解析 AG-UI RunAgentInput 负载
$input = json_decode(file_get_contents('php://input'), true);

$messages = [];
foreach ($input['messages'] as $message) {
    if ($message['role'] === 'user') {
        $messages[] = new UserMessage($message['content']);
    }
}

// 将客户端的 thread 和 run 标识符回传到流中
$adapter = new AGUIAdapter(
    threadId: $input['threadId'],
    runId: $input['runId'],
);

// 发送协议所需的 SSE 标头
foreach ($adapter->getHeaders() as $name => $value) {
    header("{$name}: {$value}");
}

$stream = MyAgent::make()
    ->setStreamAdapter($adapter)
    ->stream($messages);

foreach ($stream as $line) {
    echo $line;
    flush();
}
```

适配器会将 Neuron 的流式块转换为以下 AG-UI 事件：

附加到 Neuron 代理的工具会在服务器上执行。客户端会通过以下内容获知正在进行的执行： `TOOL_CALL_*` 事件，并在 `TOOL_CALL_RESULT` 事件中接收工具输出，随后收到代理的最终文本消息。 `tools` 字段中的 `RunAgentInput` （由客户端执行的工具）不会由适配器处理。

适配器不会发出 AG-UI 共享状态事件（`STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT`），因此 AG-UI 客户端的状态同步功能无法通过此适配器使用。

### 自定义事件

这两种适配器都支持可移植的 step、activity 和自定义事件。AG-UI 使用其原生的 `STEP_STARTED`, `STEP_FINISHED`, `ACTIVITY_SNAPSHOT`、以及 `CUSTOM` 事件。Vercel 会发出临时的 `data-*` 片段，因此中间信息可供 UI 使用，而不会被添加到助手消息历史中。

当领域代码需要保持与 Neuron 的可移植事件对象独立时，可按其精确类来映射应用事件：

```php
use NeuronAI\Chat\Messages\Stream\Adapters\Events\ActivityStreamEvent;
use NeuronAI\Chat\Messages\Stream\Adapters\VercelAIAdapter;

$adapter = (new AGUIAdapter())->mapEvent(
    IndexingProgress::class,
    static fn (IndexingProgress $event): ActivityStreamEvent =>
        new ActivityStreamEvent(
            id: $event->jobId,
            type: 'indexing',
            data: [
                'processed' => $event->processed,
                'total' => $event->total,
            ],
        ),
);
```

回调会返回一个可移植事件，而不是 SSE、JSON 或特定协议数组。返回 `null` 即可抑制显式映射的事件。映射是精确的类匹配，因此父类映射不会悄然捕获子类。

### 自定义适配器

该 `stream()` 代理处理器的方法接受一个 `StreamAdapterInterface`的实例。因此你可以自由地使用自定义实现来实现此接口，并将其传给处理器。接口如下：

```php
interface StreamAdapterInterface
{
    /**
     * 开始一个运行片段。Workflow 会在每个
     * 片段上在 start() 之前调用它，因此一个实例可以服务于暂停及其续接
     * 在同一进程中：丢弃前一个片段的流状态，保留
     * 已初始化的协议标识和快照。
     */
    public function reset(): void;
    
    /**
     * 将 Neuron 块转换为协议事件。
     *
     * @param object $chunk Neuron 块（TextChunk、ToolCallChunk 等）或自定义对象
     * @return iterable<ProtocolEvent> 零个或多个事件
     */
    public function transform(object $chunk): iterable;

    /**
     * 协议初始化序列（可选）。
     *
     * @return iterable<ProtocolEvent>
     */
    public function start(): iterable;

    /**
     * 协议终止序列（可选）。
     *
     * @return iterable<ProtocolEvent>
     */
    public function end(): iterable;

    /**
     * 协议暂停序列，在运行
     * 因外部输入而暂停时，会代替 end() 被消费。
     *
     * 适配器会编码活动请求，以便客户端了解运行正在
     * 等待什么，包括任何终止帧。如果协议无法表达暂停，请返回空的
     * iterable。
     *
     * @param array<int, InterruptRequest> $requests 活动请求，以 interrupt ID 为键。
     * @return iterable<ProtocolEvent>
     */
    public function interrupt(array $requests): iterable;

    /**
     * 协议失败序列，在流式传输失败时代替 end() 被消费。
     *
     * 适配器会为其协议编码原始错误，包括任何
     * 终止帧。如果不需要失败输出，请返回空的 iterable。
     *
     * @return iterable<ProtocolEvent>
     */
    public function error(Throwable $error): iterable;
}
```

你始终可以从内置实现中获得灵感。

## 流式通道

随着代理变得越来越交互式且更强大，由于 HTTP 请求生命周期的超时限制，应用开发者越来越被迫在其外部运行它们，这会导致流式输出无法传达给 UI。通道会通过外部广播系统（例如 [Pusher](https://pusher.com/)、websocket、Redis 队列，或你的应用已经在使用的任何其他方式）将代理和工作流的流式输出传递给用户界面。

### 它解决的问题

运行代理有两种方式。你可以消费其实时事件：

```php
foreach ($agent->events() as $event) {
    // 处理每个流式项
}
```

或者你也可以只请求最终结果：

```php
$state = $agent->setThreadId('chat_id')->chat(new UserMessage(...));
```

当你的应用代码从开始到结束都持有该流时，第一种方式效果很好，比如控制器保持 HTTP 连接打开并将每个块打印到浏览器。

当没有人持有该流时，问题就出现了。想象一个在后台任务中运行的代理。任务调用 `events()`，代理会生成块，但该进程没有连接浏览器。没有 Channel，所有输出都会被直接丢弃。

Channels 会自动将流式事件转发到自定义传输：websocket、Redis 队列、SSE 响应，或任何你想要的方式，以便从后台进程向你的 Web 应用实时传输结果。

请记住，使用通道需要流式适配器。如果你想将 Neuron 原生块转发到通道，可以使用内置的 `NeuronAI\Agent\Adapter\AgentChunkAdapter`.

### 附加通道

你可以附加一个实现了以下 `channel()` 方法的 Channel，或者使用 `setChannel()` 直接在 Agent 实例上。

```php
use NeuronAI\Agent\Adapter\AgentChunkAdapter;
use NeuronAI\Workflow\Channel\CallbackChannel;
use NeuronAI\Workflow\Persistence\FilePersistence;

class MyAgent extends Agent
{
    ...
    
    protected function streamAdapter(): ?StreamAdapterInterface
    {
        // 或专门的 UI 协议适配器
        return new AgentChunkAdapter();
    }
    
    protected function channel(): ?StreamingChannelInterface
    {
        return new PusherChannel(
            client: new Pusher(...),
            channel: 'PUSHER_CHANNEL_NAME'
        );
    }
}

// 运行 Agent
MyAgent::make()->stream(new UserMessage('Hi'));
```

### CallbackChannel

最快的上手方式是 `CallbackChannel`。它最多封装四个闭包，每个对应接口的一个方法。它们全部都是可选的。下面是一个完整示例，它会将每个流式项发布到 Redis，因此 websocket 服务器可以把它转发给浏览器：

```php
use NeuronAI\Workflow\Channel\CallbackChannel;
use NeuronAI\Workflow\Persistence\FilePersistence;

$agent = MyAgent::make()
    ->setThreadId('chat_id')
    ->setChannel(new CallbackChannel(
        onSend: function (ProtocolEvent $item) use ($redis): void {
            $redis->publish('thread-123', serialize($item));
        },
    ));

$agent->stream(new UserMessage('Hi'));
```

现在无论 `stream()` 是由控制器、队列 worker 还是 cron 任务调用，块始终会到达 Redis，然后再到达你的前端。

你也可以响应终端回调。此示例会在运行暂停等待批准、完成或失败时通知前端：

```php
use NeuronAI\Workflow\Channel\CallbackChannel;
use NeuronAI\Workflow\Interrupt\InterruptRequest;
use NeuronAI\Workflow\WorkflowState;

$channel = new CallbackChannel(
    onSend: fn (ProtocolEvent $item) => $redis->publish(
        'thread-123', 
        json_encode($item)
    ),
    onInterrupted: fn (InterruptRequest $request, string $runId) => $redis->publish(
        'thread-123',
        json_encode(['type' => 'interrupted', 'runId' => $runId])
    ),
    onCompleted: fn (WorkflowState $state, string $runId) => $redis->publish(
        'thread-123',
        json_encode(['type' => 'completed', 'runId' => $runId])
    ),
    onFailed: fn (\Throwable $e, string $runId) => $redis->publish(
        'thread-123',
        json_encode(['type' => 'failed', 'runId' => $runId, 'message' => $e->getMessage()])
    ),
);

MyAgent::make()
    ->setChannel($channel)
    ->stream(new UserMessage('Hi'));
```

### Pusher

你可以通过 Pusher，或与 Pusher 兼容的服务器，将代理输出流式传输到前端。

```php
use NeuronAI\Agent\Adapter\AgentChunkAdapter;
use NeuronAI\Workflow\Streaming\Channel\PusherChannel;
use NeuronAI\Workflow\Streaming\Channel\StreamingChannelInterface;
use Pusher\Pusher;

class MyAgent extends Agent
{
    ...
    
    protected function streamAdapter(): ?StreamAdapterInterface
    {
        // 或专门的 UI 协议适配器
        return new AgentChunkAdapter();
    }
    
    protected function channel(): StreamingChannelInterface
    {
        return new PusherChannel(
            client: new Pusher(...),
            channel: 'PUSHER_CHANNEL_NAME',
            maxRequestBytes: 10_000,
            batchSize: 10
        );
    }
}
```

**`maxRequestBytes`** 可让你调整该组件与兼容 Pusher 的服务器的兼容性。其默认值 10 KB 适用于 Pusher，但其他服务器可能支持不同的请求大小。

**`batchSize`** 则允许你定义在一次批量请求中发送之前必须收集多少个事件。较高的值会让后端执行更顺畅，但可能导致前端体验较为分散。较低的值会让前端体验更流畅，但会向后端发送更多请求。

{% hint style="warning" %}
使用 **`/neuron-streaming`** 特定技能或框架技能 **`/neuron-laravel-integration`** , **`/neuron-symfony-integration`** 以便为你的代理提供关于此集成的准确指令。
{% endhint %}

#### 部分事件

Pusher 将单个事件限制为 10 KB；Reverb 默认也是如此，Soketi 为 100 KB，而 `maxRequestBytes` （默认 `10_000`）会调整这个上限。

为了在实时服务器存在此类限制时仍支持流式传输，不符合最大大小的事件——通常是工具调用、工具结果或消息快照——会被拆分为连续片段。此外，服务器不能保证片段按顺序到达，也不能保证它们不会交错。因此，浏览器必须能够对这种碎片化和顺序进行重组，以便向你的 UI 组件提供一致的流式体验。

Neuron 自带一个官方 Typescript 模块，可将此能力带入你的前端。

使用以下命令安装该模块：

```shellscript
npm install @neuron-core/streaming
```

查看专门的文档以将其集成到你的前端： <https://www.npmjs.com/package/@neuron-core/streaming>

### Mercure

你可以使用 SSE 将代理输出流式传输到 Mercure Hub：

```php
use NeuronAI\Agent\Adapter\AgentChunkAdapter;
use NeuronAI\Workflow\Streaming\Channel\MercureChannel;
use NeuronAI\Workflow\Streaming\Channel\StreamingChannelInterface;
use Pusher\Pusher;

class MyAgent extends Agent
{
    ...
    
    protected function streamAdapter(): ?StreamAdapterInterface
    {
        // 或专门的 UI 协议适配器
        return new AgentChunkAdapter();
    }
    
    protected function channel(): StreamingChannelInterface
    {
        return new MercureChannel(
            hub: new Hub(...),
            topic: 'thread:'.$this->getThreadId(),
            maxRequestBytes: 1_048_576,
            maxRequestsPerSecond: null,
            private: true
        );
    }
}
```

默认情况下 `maxRequestsPerSecond` 被设为 null，因为自托管实例没有任何速率限制。如果你使用托管云实例，它们会根据你的订阅计划施加严格的速率限制，从每秒 1 次到 20 次请求不等。

一旦你在 MercureChannel 中配置了与 Mercure 服务器相同的限制，该组件就会自动限制发送事件的速度，并且在大小超过 `maxRequestBytes` 时最终将事件拆分为多个片段。浏览器必须能够对这种碎片化和顺序进行重组，以便向你的 UI 组件提供一致的流式传输。

Neuron 自带一个官方 Typescript 模块，可将此能力带入你的前端。

使用以下命令安装该模块：

```shellscript
npm install @neuron-core/streaming
```

查看专门的文档以将其集成到你的前端： <https://www.npmjs.com/package/@neuron-core/streaming>

{% hint style="warning" %}
使用 **`/neuron-streaming`** 特定技能或框架技能 **`/neuron-laravel-integration`** , **`/neuron-symfony-integration`** 以便为你的代理提供关于此集成的准确指令。
{% endhint %}

### Redis

`RedisChannel` 会将该片段发布到 Redis Pub/Sub 通道，这是运行代理的 worker 与持有客户端连接的进程（SSE 端点、websocket 服务器）之间的常见分发方式。它需要 `ext-redis` 以及一个已连接的 `Redis` 客户端。

```php
use NeuronAI\Agent\Adapter\AgentChunkAdapter;
use NeuronAI\Workflow\Streaming\Channel\RedisChannel;
use NeuronAI\Workflow\Streaming\Channel\StreamingChannelInterface;
use Redis;

class MyAgent extends Agent
{
    ...
    
    protected function streamAdapter(): ?StreamAdapterInterface
    {
        return new AGUIAdapter($this->getThreadId());
    }
    
    protected function channel(): StreamingChannelInterface
    {
        return new RedisChannel(
            client: new Redis(...), 
            channel: "chat:{$threadId}",
        );
    }
}
```

#### Redis 消费者

使用通道后，你的代理会将流式块发送到指定的 Redis 队列。因此现在你的应用需要一种方式来监听这些块并将流转发到前端。

`RedisChannelReader` 读取什么 `RedisChannel` 其发布的内容。一个在订阅之前就启动的代理，会抛出 `ChannelReadException`，超过其超时时间后保持静默也一样。Redis 会按顺序传递单个发布者的消息，并且 `RedisChannel` 从不分片，因此无需重排或重组。

```php
(new RedisChannelReader(new Redis(...), 'chat:{$threadId}'))
    ->listen(function (ProtocolEvent $event): void {
        echo SSEEncoder::frame($event);
        if (ob_get_level() > 0) {
            ob_flush();
        }
        flush();
    });
```

{% hint style="warning" %}
使用 **`/neuron-streaming`** 特定技能或框架技能 **`/neuron-laravel-integration`** , **`/neuron-symfony-integration`** 以便为你的代理提供关于此集成的准确指令。
{% endhint %}

### 通道错误绝不会中断运行

通道会与外部系统通信，而外部系统会出故障。Redis 服务器可能宕机，套接字可能关闭。框架会保护运行不受其影响：对 Channel 的每一次调用都受到保护。如果你的 Channel 抛出异常，工作流会捕获它，将其作为 `ChannelError` 事件通过可观测性系统上报，并继续运行，仿佛什么都没发生。

这意味着，即使传输通道出了问题，AI 的工作也绝不会丢失。聊天历史仍然是真相来源。实时流只是其上的一种便利，错过了一些分块的客户端始终可以从历史记录中重新加载最终结果。

如果你的传输需要针对重复失败的真正策略，例如在十次错误后停止重试，那么把这段逻辑放在你的 Channel 实现内部，因为只有 Channel 才知道失败对于它自身的传输意味着什么。

### 自定义 Channel

Channel 是任何实现了 `ChannelInterface`. 它有四个方法。一个接收流式项目，另外三个告诉你运行是如何结束的：

```php
namespace NeuronAI\Workflow\Channel;

interface StreamingChannelInterface
{
    /** 
     * 流适配器按流顺序产生的协议事件。 
     */
    public function send(ProtocolEvent $event): void;

    /**
     * 运行段因一个或多个处于活动状态的中断请求而结束。
     */
    public function interrupted(WorkflowState $state): void;

    /** 运行段干净地结束。 */
    public function completed(WorkflowState $state, string $workflowId): void;

    /**
     * 运行段因未处理的可抛出异常而终止。仅用于通知——
     * 无论如何，异常都会传播给调用者。
     */
    public function failed(Throwable $exception, string $workflowId): void;
}
```

每次运行都会以三个终态调用中的一个结束： `suspended()`, `completed()`，或 `failed()`. 这对用户界面很重要。如果运行失败而你没有错误信号，用户就会一直看到一个永不停止的加载指示。使用 `failed()` 你的前端总会收到明确的结束信号，并且可以恢复，例如重新加载聊天历史。

有两个细节值得注意。 `failed()` 方法只是通知：异常仍然会到达调用 `chat()`.

下面是一个 `LogChannel`:

```php
use NeuronAI\Workflow\Channel\ChannelInterface;
use NeuronAI\Workflow\Interrupt\InterruptRequest;
use NeuronAI\Workflow\WorkflowState;

class LogChannel implements ChannelInterface
{
    public function __construct(protected LoggerInterface $log)
    {
    }

    public function send(ProtocolEvent $item): void
    {
        $this->log->debug(json_encode($item));
    }

    public function interrupted(InterruptRequest $request, string $runId): void
    {
        $this->log->debug("interrupted: {$runId}");
    }

    public function completed(WorkflowState $state, string $runId): void
    {
        $this->log->debug("completed: {$runId}");
    }

    public function failed(Throwable $exception, string $runId): void
    {
        $this->log->debug("failed: {$runId} ({$exception->getMessage()})");
    }
}
```

并将其像任何其他 channel 一样挂接起来：

```php
$agent->setChannel(new LogChannel(new Logger(__DIR__ . '/storage/workflow.log')));
```
