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

# 流式事件

> 整理在启用 SessionConfig 的 streaming 时可以接收到的 Session Event 种类和 payload。

## 流式事件

启用 `SessionConfig` 中的 `streaming: true` 后，会话过程中的动作会以事件形式依次投递。
本页是把官方 `streaming-events.md` 面向 Laravel 整理得更易读的中文版。

> [SessionEvent](/zh/packages/laravel-copilot-sdk/session-event) 页面介绍的是面向 Laravel 扩展的 `SessionEvent` 类本身。
> 本页是「哪种事件类型下会传来哪些数据」的参考。

## 概览

Copilot 代理的处理（推理、消息生成、工具执行、权限确认等）全部以会话事件的形式流转。

* **Ephemeral event**: 仅实时投递。不会持久化到会话日志中（恢复时不会重放）
* **Persisted event**: 保存到会话日志（恢复时会重放）
* **Delta event**: 分片到达的差量事件（如 `deltaContent`）。拼接后构成完整内容
* **`parentId` chain**: 每个事件引用前一个事件 ID 形成链

## Event envelope（共通字段）

所有事件都具有以下共通结构。

| Field       | Type             | 说明                     |
| ----------- | ---------------- | ---------------------- |
| `id`        | `string`         | 事件唯一 ID（UUID v4）       |
| `timestamp` | `string`         | 创建时间（ISO 8601）         |
| `parentId`  | `string \| null` | 前一个事件 ID（首个事件为 `null`） |
| `ephemeral` | `boolean?`       | 临时事件时为 `true`          |
| `type`      | `string`         | 事件类型                   |
| `data`      | `object`         | 事件专属的 payload          |

## 在 Laravel 中订阅示例

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session): void {
    // 所有事件
    $session->on(function (SessionEvent $event): void {
        info($event->type(), $event->toArray());
    });

    // 特定事件
    $session->on(SessionEventType::ASSISTANT_MESSAGE_DELTA, function (SessionEvent $event): void {
        echo $event->deltaContent();
    });

    $session->sendAndWait(prompt: '告诉我 Laravel 的特点');
}, config: new SessionConfig(streaming: true));
```

## 主要事件分类

## Assistant events

### `assistant.turn_start`

turn 开始。

* `turnId`（必需）
* `interactionId`（可选）

### `assistant.intent`（ephemeral）

当前的执行意图（如 `Exploring codebase`）。

* `intent`（必需）

### `assistant.reasoning`

推理块的完整版。

* `reasoningId`（必需）
* `content`（必需）

### `assistant.reasoning_delta`（ephemeral）

推理文本的差量。

* `reasoningId`（必需）
* `deltaContent`（必需）

### `assistant.message`

助手的完整消息。

主要字段：

* `messageId`（必需）
* `content`（必需）
* `toolRequests`（可选）
* `reasoningOpaque` / `reasoningText` / `encryptedContent`（可选）
* `phase` / `outputTokens` / `interactionId`（可选）
* `parentToolCallId`（可选，来自子代理时）

### `assistant.message_delta`（ephemeral）

消息正文的差量。

* `messageId`（必需）
* `deltaContent`（必需）
* `parentToolCallId`（可选）

### `assistant.turn_end`

turn 结束。

* `turnId`（必需）

### `assistant.usage`（ephemeral）

以 API 调用为单位的使用量信息。

主要字段：

* `model`（必需）
* `inputTokens` / `outputTokens` / `cost` / `duration`（可选）
* `apiCallId` / `providerCallId`（可选）
* `quotaSnapshots` / `copilotUsage`（可选）

### `assistant.streaming_delta`（ephemeral）

低级别的接收进度。

* `totalResponseSizeBytes`（必需）

## Tool execution events

### `tool.execution_start`

工具执行开始。

* `toolCallId`（必需）
* `toolName`（必需）
* `arguments` / `mcpServerName` / `mcpToolName` / `parentToolCallId`（可选）

### `tool.execution_partial_result`（ephemeral）

工具执行过程中的部分输出。

* `toolCallId`（必需）
* `partialOutput`（必需）

### `tool.execution_progress`（ephemeral）

进度消息。

* `toolCallId`（必需）
* `progressMessage`（必需）

### `tool.execution_complete`

工具执行完成（成功 / 失败）。

* `toolCallId`（必需）
* `success`（必需）
* `result`（成功时）
* `error`（失败时）
* `toolTelemetry` / `parentToolCallId`（可选）

### `tool.user_requested`

用户显式请求的工具调用。

* `toolCallId`（必需）
* `toolName`（必需）
* `arguments`（可选）

## Session lifecycle events

### `session.start`

会话开始。在 Cloud Sessions 中，等到 `producer` 确认了 `copilot-agent` 的 `session.start` 之后再发送第一个 prompt 会更安全。

* `producer`（可选）

### `session.idle`（ephemeral）

当前处理完成，等待下一个输入。

* `backgroundTasks`（可选）

### `session.error`

会话处理中的错误。

* `errorType`（必需）
* `message`（必需）
* `stack` / `statusCode` / `providerCallId`（可选）

### `session.compaction_start`

上下文压缩开始（`data` 为空对象）。

### `session.compaction_complete`

上下文压缩完成。

主要字段：

* `success`（必需）
* `error`（可选）
* `preCompactionTokens` / `postCompactionTokens`（可选）
* `summaryContent` / `checkpointPath`（可选）

### `session.title_changed`（ephemeral）

自动标题更新。

* `title`（必需）

### `session.context_changed`

工作上下文变化。

* `cwd`（必需）
* `gitRoot` / `repository` / `branch`（可选）

### `session.info`

远程 URL 等会话信息。

* `infoType`（必需）
* `url`（可选，`infoType` 为 `remote` 等情况下）

### `session.remote_steerable_changed`

表示是否可以从 Mission Control 进行远程操作发生变化的事件。

* `remoteSteerable`（可选）

### `session.usage_info`（ephemeral）

上下文窗口的使用情况。

* `tokenLimit`（必需）
* `currentTokens`（必需）
* `messagesLength`（必需）

### `session.task_complete`

任务完成通知。

* `summary`（可选）

### `session.shutdown`

会话终止。

主要字段：

* `shutdownType`（必需）
* `errorReason`（可选）
* `totalPremiumRequests` / `totalApiDurationMs`（必需）
* `codeChanges` / `modelMetrics`（必需）

## Permission / user input events

### `permission.requested`（ephemeral）

权限确认请求。

* `requestId`（必需）
* `permissionRequest`（必需）

`permissionRequest.kind`：

* `shell`
* `write`
* `read`
* `mcp`
* `url`
* `memory`
* `custom-tool`

### `permission.completed`（ephemeral）

权限确认的解决结果。

* `requestId`（必需）
* `result.kind`（必需）

### `user_input.requested`（ephemeral）

向用户提问。

* `requestId`（必需）
* `question`（必需）
* `choices` / `allowFreeform`（可选）

### `user_input.completed`（ephemeral）

用户输入完成。

* `requestId`（必需）

### `elicitation.requested`（ephemeral）

结构化输入（表单）请求。

* `requestId`（必需）
* `message`（必需）
* `requestedSchema`（必需）

### `elicitation.completed`（ephemeral）

结构化输入完成。

* `requestId`（必需）

## Sub-agent / skill events

### `subagent.started`

* `toolCallId`（必需）
* `agentName` / `agentDisplayName` / `agentDescription`（必需）

### `subagent.completed`

* `toolCallId`（必需）
* `agentName` / `agentDisplayName`（必需）

### `subagent.failed`

* `toolCallId`（必需）
* `agentName` / `agentDisplayName`（必需）
* `error`（必需）

### `subagent.selected`

* `agentName`（必需）
* `agentDisplayName`（必需）
* `tools`（必需，允许 `null`）

### `subagent.deselected`

恢复到默认代理（`data` 为空对象）。

### `skill.invoked`

* `name` / `path` / `content`（必需）
* `allowedTools` / `pluginName` / `pluginVersion`（可选）

## Other events

### `abort`

* `reason`（必需）

### `user.message`

* `content`（必需）
* `transformedContent` / `attachments` / `source` / `agentMode` / `interactionId`（可选）

### `system.message`

* `content`（必需）
* `role`（必需）
* `name` / `metadata`（可选）

### `external_tool.requested`（ephemeral）

* `requestId` / `sessionId` / `toolCallId` / `toolName`（必需）
* `arguments`（可选）

### `external_tool.completed`（ephemeral）

* `requestId`（必需）

### `exit_plan_mode.requested`（ephemeral）

* `requestId` / `summary` / `planContent` / `actions` / `recommendedAction`（必需）

### `exit_plan_mode.completed`（ephemeral）

* `requestId`（必需）

### `command.queued`（ephemeral）

* `requestId`（必需）
* `command`（必需）

### `command.completed`（ephemeral）

* `requestId`（必需）

## 典型的事件顺序

```text theme={null}
assistant.turn_start
├── assistant.intent (ephemeral)
├── assistant.reasoning_delta (ephemeral, 多次)
├── assistant.reasoning
├── assistant.message_delta (ephemeral, 多次)
├── assistant.message
├── assistant.usage (ephemeral)
├── [必要时 permission / tool.* 会循环]
assistant.turn_end
session.idle (ephemeral)
```

## 全部事件一览（快速参考）

| Event Type                         | Ephemeral | Category      |
| ---------------------------------- | --------- | ------------- |
| `session.start`                    |           | Session       |
| `assistant.turn_start`             |           | Assistant     |
| `assistant.intent`                 | ✅         | Assistant     |
| `assistant.reasoning`              |           | Assistant     |
| `assistant.reasoning_delta`        | ✅         | Assistant     |
| `assistant.streaming_delta`        | ✅         | Assistant     |
| `assistant.message`                |           | Assistant     |
| `assistant.message_delta`          | ✅         | Assistant     |
| `assistant.turn_end`               |           | Assistant     |
| `assistant.usage`                  | ✅         | Assistant     |
| `tool.user_requested`              |           | Tool          |
| `tool.execution_start`             |           | Tool          |
| `tool.execution_partial_result`    | ✅         | Tool          |
| `tool.execution_progress`          | ✅         | Tool          |
| `tool.execution_complete`          |           | Tool          |
| `session.idle`                     | ✅         | Session       |
| `session.error`                    |           | Session       |
| `session.compaction_start`         |           | Session       |
| `session.compaction_complete`      |           | Session       |
| `session.title_changed`            | ✅         | Session       |
| `session.context_changed`          |           | Session       |
| `session.info`                     |           | Session       |
| `session.remote_steerable_changed` |           | Session       |
| `session.usage_info`               | ✅         | Session       |
| `session.task_complete`            |           | Session       |
| `session.shutdown`                 |           | Session       |
| `permission.requested`             | ✅         | Permission    |
| `permission.completed`             | ✅         | Permission    |
| `user_input.requested`             | ✅         | User Input    |
| `user_input.completed`             | ✅         | User Input    |
| `elicitation.requested`            | ✅         | User Input    |
| `elicitation.completed`            | ✅         | User Input    |
| `subagent.started`                 |           | Sub-Agent     |
| `subagent.completed`               |           | Sub-Agent     |
| `subagent.failed`                  |           | Sub-Agent     |
| `subagent.selected`                |           | Sub-Agent     |
| `subagent.deselected`              |           | Sub-Agent     |
| `skill.invoked`                    |           | Skill         |
| `abort`                            |           | Control       |
| `user.message`                     |           | User          |
| `system.message`                   |           | System        |
| `external_tool.requested`          | ✅         | External Tool |
| `external_tool.completed`          | ✅         | External Tool |
| `command.queued`                   | ✅         | Command       |
| `command.completed`                | ✅         | Command       |
| `exit_plan_mode.requested`         | ✅         | Plan Mode     |
| `exit_plan_mode.completed`         | ✅         | Plan Mode     |

## 相关文档

* [官方 Streaming Events 参考](https://github.com/github/copilot-sdk/blob/main/docs/features/streaming-events.md)
* Laravel 版事件类说明：[SessionEvent](/zh/packages/laravel-copilot-sdk/session-event)
* 流式实现模式：[Streaming](/zh/packages/laravel-copilot-sdk/streaming)


## Related topics

- [代理循环](/zh/packages/laravel-copilot-sdk/agent-loop.md)
- [Cloud Sessions](/zh/packages/laravel-copilot-sdk/cloud-sessions.md)
- [Fleet Mode](/zh/packages/laravel-copilot-sdk/fleet-mode.md)
- [事件](/zh/packages/laravel-copilot-sdk/events.md)
- [用于 Laravel AI SDK 的 Amazon Bedrock 驱动](/zh/packages/laravel-amazon-bedrock.md)