Copilot SDK 中的流式处理事件

注意

          Copilot SDK 当前处于 技术预览版. 功能和可用性可能会发生更改。

代理执行的每个操作 Copilot （思考、编写代码、运行工具）都会作为可以订阅的 会话事件 发出。本文是每个事件类型的字段级参考，以便确切地了解预期数据。

设置在会话上的 streaming: true，SDK 会实时发出临时事件（增量、进度更新）以及持久事件（完整的消息、工具结果）。所有事件共享一个公用信封，并携带一个载荷，其形状取决于事件 type。有关完整事件流的序列图，请参阅 github/copilot-sdk 存储库。

概念	说明

          **临时事件** | 瞬时; 实时流传，但不持久保存到会话日志。 会话恢复时未重播。 |

事件封装

无论类型如何，每个会话事件都包含以下字段：

领域	类型	说明
`id`

          `string` （UUID v4） | 唯一事件标识符 |

订阅事件

// All events
session.on((event) => {
    console.log(event.type, event.data);
});

// Specific event type — data is narrowed automatically
session.on("assistant.message_delta", (event) => {
    process.stdout.write(event.data.deltaContent);
});

有关 Python、Go 和 .NET 中的示例，请参阅 github/copilot-sdk 存储库。

提示

          **Python/Go：** 这些 SDK 使用一个包含所有可能字段、字段可选且可为空的单个类或结构体。 只有下表中列出的字段会针对每个事件类型进行填充，其余字段会保持为`None` / `nil`。

          **.NET：** .NET SDK 为每个事件使用单独的强类型数据类（例如 `AssistantMessageDeltaData`），因此每种类型仅包括相关字段。

          **TypeScript：** TypeScript SDK 使用区分的联合 - 匹配 `event.type`时， `data` 有效负载会自动缩小到正确的形状。

助理活动

这些事件跟踪代理程序的整个响应生命周期【从轮次开始，经过流式处理区块，直至最终消息】。

`assistant.turn_start`

代理开始处理轮次时发出。

数据字段	类型	必需	说明
`turnId`	`string`	✅	轮次标识符（通常是字符串化的轮次编号）
`interactionId`	`string`
遥测关联交互标识符

`assistant.intent`

短暂。代理当前正在执行任务的简短描述，在其运行过程中不断更新。

数据字段	类型	必需	说明
`intent`	`string`	✅	人可读的意图（例如“探索代码库”）

`assistant.reasoning`

完成从模型中提取的扩展思维块。推理完成后发出。

数据字段	类型	必需	说明
`reasoningId`	`string`	✅	此推理块的唯一标识符
`content`	`string`	✅	完整的扩展思维文本

`assistant.reasoning_delta`

短暂。模型扩展推理的增量块，实时流式传输。

数据字段	类型	必需	说明
`reasoningId`	`string`	✅	匹配相应的 `assistant.reasoning` 事件
`deltaContent`	`string`	✅	要附加到推理内容的文本片段

`assistant.message`

此 LLM 呼叫的助理的完整响应。可能包括工具调用请求。

数据字段	类型	必需	说明
`messageId`	`string`	✅	此消息的唯一标识符
`content`	`string`	✅	助手的文本响应
`toolRequests`	`ToolRequest[]`
助理拟进行的工具调用（请参阅下文）
`reasoningOpaque`	`string`
加密扩展思维（人类模型）：会话绑定
`reasoningText`	`string`
扩展思维中的可读推理文本
`encryptedContent`	`string`
加密推理内容（OpenAI 模型）：会话绑定
`phase`	`string`
生成阶段（例如， `"thinking"` vs `"response"`）
`outputTokens`	`number`
来自 API 响应的实际输出令牌计数
`interactionId`	`string`
遥测的交互标识符
`parentToolCallId`	`string`
当此消息源自子代理时进行设置

          **
          `ToolRequest` 领域：**

领域	类型	必需	说明
`toolCallId`	`string`	✅	此工具调用的唯一 ID
`name`	`string`	✅	工具名称（例如， `"bash"`， "edit"``"grep"）
`arguments`	`object`
用于工具的解析参数
`type`	`"function" \| "custom"`
调用类型；如果缺失，默认为`"function"`

`assistant.message_delta`

短暂。助理文本响应的增量区块，实时流式传输。

数据字段	类型	必需	说明
`messageId`	`string`	✅	匹配相应的 `assistant.message` 事件
`deltaContent`	`string`	✅	要追加到消息的文本片段
`parentToolCallId`	`string`
当由子代理发起时设定

`assistant.turn_end`

代理完成轮次时发出（所有工具执行完成，最终响应已传递）。

数据字段	类型	必需	说明
`turnId`	`string`	✅	匹配相应的 `assistant.turn_start` 事件

`assistant.usage`

短暂。单个 API 调用的令牌使用情况和成本信息。

数据字段	类型	必需	说明
`model`	`string`	✅	模型标识符（例如） `"gpt-4.1"`
`inputTokens`	`number`
消耗的输入令牌
`outputTokens`	`number`
生成的输出令牌
`cacheReadTokens`	`number`
从提示缓存中读取的令牌
`cacheWriteTokens`	`number`
写入以提示缓存的令牌
`cost`	`number`
计费的模型乘数成本
`duration`	`number`
API 调用持续时间（以毫秒为单位）
`initiator`	`string`
触发此调用的内容（例如，`"sub-agent"`）；如果是用户启动，则不填。
`apiCallId`	`string`
提供程序的完成 ID（例如 `chatcmpl-abc123`）
`providerCallId`	`string`

          GitHub 请求跟踪 ID （`x-github-request-id`） |

`assistant.streaming_delta`

短暂。低级别网络进度指示器 - 从流式处理 API 响应接收的总字节数。

数据字段	类型	必需	说明
`totalResponseSizeBytes`	`number`	✅	到目前为止收到的累积字节数

工具执行事件

这些事件跟踪每个工具调用的完整生命周期，从模型请求工具调用到执行和结束。

`tool.execution_start`

当工具开始执行时发出。

数据字段	类型	必需	说明
`toolCallId`	`string`	✅	此工具调用的唯一标识符
`toolName`	`string`	✅	工具的名称（例如，，"bash"``"edit"， `"grep"`）
`arguments`	`object`
传递给工具的已分析参数
`mcpServerName`	`string`
MCP 服务器名称，当 MCP 服务器提供该工具时
`mcpToolName`	`string`
MCP 服务器上的原始工具名称
`parentToolCallId`	`string`
在子代理调用时设置

`tool.execution_partial_result`

短暂。正在运行的工具的增量输出（例如流式处理 bash 输出）。

数据字段	类型	必需	说明
`toolCallId`	`string`	✅	匹配相应的 `tool.execution_start`
`partialOutput`	`string`	✅	增量输出区块

`tool.execution_progress`

短暂。运行工具中的人工可读进度状态（例如 MCP 服务器进度通知）。

数据字段	类型	必需	说明
`toolCallId`	`string`	✅	匹配相应的 `tool.execution_start`
`progressMessage`	`string`	✅	进度状态消息

`tool.execution_complete`

当工具完成执行时发出 — 成功或出错。

数据字段	类型	必需	说明
`toolCallId`	`string`	✅	匹配相应的 `tool.execution_start`
`success`	`boolean`	✅	执行是否成功
`model`	`string`
生成此工具调用的模型
`interactionId`	`string`
交互标识符
`isUserRequested`	`boolean`

          `true` 当用户显式请求此工具调用时 |

| result | Result | | 显示成功（请参阅下文） | | error | { message, code? } | | 失败时显示 | | toolTelemetry | object | | 特定于工具的遥测 | | parentToolCallId | string | | 在子代理调用时设置 |

          **
          `Result` 领域：**

领域	类型	必需	说明
`content`	`string`	✅	发送到 LLM 的简洁结果（可能会因令牌效率而截断）
`detailedContent`	`string`
显示的完整结果，包括保留差异等完整细节
`contents`	`ContentBlock[]`
结构化内容块（文本、终端、图像、音频、资源）

`tool.user_requested`

当用户显式请求工具调用（而不是由模型选择调用时）发出。

数据字段	类型	必需	说明
`toolCallId`	`string`	✅	此工具调用的唯一标识符
`toolName`	`string`	✅	用户要调用的工具的名称
`arguments`	`object`
函数调用的参数

会话生命周期事件

`session.idle`

短暂。代理已完成所有处理，并已准备好下一条消息。这是转弯已完全完成的信号。

数据字段	类型	必需	说明
`backgroundTasks`	`BackgroundTasks`
后台代理/shell 在代理变得空闲时仍然运行中

`session.error`

会话处理期间出错。

数据字段	类型	必需	说明
`errorType`	`string`	✅	错误类别（例如， `"authentication"`， "quota"``"rate_limit"）
`message`	`string`	✅	人类可读错误信息
`stack`	`string`
错误堆栈跟踪
`statusCode`	`number`
来自上游请求的 HTTP 状态代码
`providerCallId`	`string`

          GitHub 用于服务器端日志关联的请求跟踪 ID |

`session.compaction_start`

上下文窗口压缩已经开始。数据有效负载为空（{}）。

`session.compaction_complete`

上下文窗口压缩已完成。

数据字段	类型	必需	说明
`success`	`boolean`	✅	压缩是否成功
`error`	`string`
压缩失败时出现错误消息
`preCompactionTokens`	`number`
压缩前的令牌
`postCompactionTokens`	`number`
压缩后的令牌
`preCompactionMessagesLength`	`number`
压缩前的消息计数
`messagesRemoved`	`number`
已删除邮件
`tokensRemoved`	`number`
已删除令牌
`summaryContent`	`string`
LLM 生成的压缩历史记录摘要
`checkpointNumber`	`number`
为恢复创建的检查点快照编号
`checkpointPath`	`string`
存储检查点的文件路径
`compactionTokensUsed`	`{ input, output, cachedInput }`
压缩LLM调用中的令牌使用情况
`requestId`	`string`

          GitHub 压缩调用的请求跟踪 ID |

`session.title_changed`

短暂。会话自动生成的标题已更新。

数据字段	类型	必需	说明
`title`	`string`	✅	新会话标题

`session.context_changed`

会话的工作目录或存储库上下文已更改。

数据字段	类型	必需	说明
`cwd`	`string`	✅	当前工作目录
`gitRoot`	`string`
Git 存储库根目录
`repository`	`string`

          `"owner/name"` 格式的存储库 |

`session.usage_info`

短暂。上下文窗口利用率快照。

数据字段	类型	必需	说明
`tokenLimit`	`number`	✅	模型上下文窗口的最大标记数
`currentTokens`	`number`	✅	上下文窗口中的当前标记
`messagesLength`	`number`	✅	对话中的当前消息计数

`session.task_complete`

代理已完成其分配的任务。

数据字段	类型	必需	说明
`summary`	`string`
已完成任务的摘要

`session.shutdown`

会话已结束。

数据字段	类型	必需	说明
`shutdownType`	`"routine" \| "error"`	✅	正常关闭或崩溃
`errorReason`	`string`

          `shutdownType` 为 `"error"` 时的错误描述 |

| totalPremiumRequests | number | ✅ | 使用的高级 API 请求总数 | | totalApiDurationMs | number | ✅ | 累积 API 调用时间（以毫秒为单位） | | sessionStartTime | number | ✅ | 会话启动时的 Unix 时间戳（ms） | | codeChanges | { linesAdded, linesRemoved, filesModified } | ✅ | 代码更改的聚合指标 | | modelMetrics | Record<string, ModelMetric> | ✅ | 按模型使用情况细分 | | currentModel | string | | 关闭时选择的模型 |

权限和用户输入事件

在继续操作之前，当代理需要用户批准或输入时，将发出这些事件。

`permission.requested`

短暂。代理需要权限才能执行操作（运行命令、写入文件等）。

数据字段	类型	必需	说明
`requestId`	`string`	✅	使用该功能通过 `session.respondToPermission()` 进行响应
`permissionRequest`	`PermissionRequest`	✅	正在请求的权限的详细信息

          `permissionRequest`是一个区分联合体`kind`：

`kind`	关键字段	说明
`"shell"`

          `fullCommandText`、`intention`、`commands[]`、`possiblePaths[]` | 执行 shell 命令 |

所有 kind 变体均包含一个可选的 toolCallId 链接，其指向触发请求的工具调用。

`permission.completed`

短暂。权限请求已解决。

数据字段	类型	必需	说明
`requestId`	`string`	✅	匹配相应的 `permission.requested`
`result.kind`	`string`	✅	其中之一：`"approved"`、、"denied-by-rules"``"denied-interactively-by-user"、`"denied-no-approval-rule-and-could-not-request-from-user"`、`"denied-by-content-exclusion-policy"`

`user_input.requested`

短暂。代理正在向用户提问。

数据字段	类型	必需	说明
`requestId`	`string`	✅	使用此来响应 `session.respondToUserInput()`
`question`	`string`	✅	向用户呈现的问题
`choices`	`string[]`
用户的预定义选项
`allowFreeform`	`boolean`
是否允许自由格式文本输入

`user_input.completed`

短暂。解决了用户输入请求。

数据字段	类型	必需	说明
`requestId`	`string`	✅	匹配相应的 `user_input.requested`

`elicitation.requested`

短暂。代理需要用户（MCP 引证协议）的结构化表单输入。

数据字段	类型	必需	说明
`requestId`	`string`	✅	通过此来响应 `session.respondToElicitation()`
`message`	`string`	✅	所需信息的说明
`mode`	`"form"`
引证模式（目前仅 `"form"`）
`requestedSchema`	`{ type: "object", properties, required? }`	✅	描述窗体字段的 JSON 架构

`elicitation.completed`

短暂。已解析引证请求。

数据字段	类型	必需	说明
`requestId`	`string`	✅	匹配相应的 `elicitation.requested`

子代理和技能事件

`subagent.started`

自定义代理被调用为子代理。

数据字段	类型	必需	说明
`toolCallId`	`string`	✅	生成此子代理的父工具调用
`agentName`	`string`	✅	子代理的内部名称
`agentDisplayName`	`string`	✅	人工可读的显示名称
`agentDescription`	`string`	✅	子代理的作用说明

`subagent.completed`

一个子代理成功完成。

数据字段	类型	必需	说明
`toolCallId`	`string`	✅	匹配相应的 `subagent.started`
`agentName`	`string`	✅	内部名称
`agentDisplayName`	`string`	✅	显示名称

`subagent.failed`

子代理遇到错误。

数据字段	类型	必需	说明
`toolCallId`	`string`	✅	匹配相应的 `subagent.started`
`agentName`	`string`	✅	内部名称
`agentDisplayName`	`string`	✅	显示名称
`error`	`string`	✅	错误消息

`subagent.selected`

已选择自定义代理（推断）来处理当前请求。

数据字段	类型	必需	说明
`agentName`	`string`	✅	所选代理的内部名称
`agentDisplayName`	`string`	✅	显示名称
`tools`	`string[] \| null`	✅	此代理可用的工具名称; `null` 适用于所有工具

`subagent.deselected`

取消了自定义代理的选择，返回到默认代理。响应有效负载将为空（{}）。

`skill.invoked`

为当前对话激活了技能。

数据字段	类型	必需	说明
`name`	`string`	✅	技能名称
`path`	`string`	✅	SKILL.md 定义的文件路径
`content`	`string`	✅	将完整的技能内容注入到对话中
`allowedTools`	`string[]`
此技能处于活动状态时自动批准的工具
`pluginName`	`string`
插件的技术来源于
`pluginVersion`	`string`
插件版本

其他事件

`abort`

当前轮次已中止。

数据字段	类型	必需	说明
`reason`	`string`	✅	为什么轮次被中止（例如 `"user initiated"`，）

`user.message`

用户发送了一条消息。记录在会话时间线中。

数据字段	类型	必需	说明
`content`	`string`	✅	用户的消息内容
`transformedContent`	`string`
预处理后的转换版本
`attachments`	`Attachment[]`
文件、目录、选择、Blob 或 GitHub 引用附件
`source`	`string`
消息源标识符
`agentMode`	`string`
代理模式：`"interactive"`、、"plan"``"autopilot"或`"shell"`
`interactionId`	`string`
交互标识符

`system.message`

系统或开发人员提示已被注入对话。

数据字段	类型	必需	说明
`content`	`string`	✅	提示文本
`role`	`"system" \| "developer"`	✅	消息角色
`name`	`string`
源标识符
`metadata`	`{ promptVersion?, variables? }`
提示模板元数据

`external_tool.requested`

短暂。代理想要调用外部工具（由 SDK 使用者提供）。

数据字段	类型	必需	说明
`requestId`	`string`	✅	通过此来响应 `session.respondToExternalTool()`
`sessionId`	`string`	✅	此请求所属的会话
`toolCallId`	`string`	✅	此调用的工具 ID
`toolName`	`string`	✅	外部工具的名称
`arguments`	`object`
工具的参数

`external_tool.completed`

短暂。解决了外部工具请求。

数据字段	类型	必需	说明
`requestId`	`string`	✅	匹配相应的 `external_tool.requested`

`exit_plan_mode.requested`

短暂。代理已创建计划并想要退出计划模式。

数据字段	类型	必需	说明
`requestId`	`string`	✅	通过此来响应 `session.respondToExitPlanMode()`
`summary`	`string`	✅	计划摘要
`planContent`	`string`	✅	完整计划文件内容
`actions`	`string[]`	✅	可用的用户操作（例如，批准、编辑、拒绝）
`recommendedAction`	`string`	✅	建议的操作

`exit_plan_mode.completed`

短暂。已解决退出计划模式请求。

数据字段	类型	必需	说明
`requestId`	`string`	✅	匹配相应的 `exit_plan_mode.requested`

`command.queued`

短暂。斜杠命令已进入执行队列。

数据字段	类型	必需	说明
`requestId`	`string`	✅	通过此来响应 `session.respondToQueuedCommand()`
`command`	`string`	✅	斜杠命令文本（例如， /help``/clear）

`command.completed`

短暂。已解析排队命令。

数据字段	类型	必需	说明
`requestId`	`string`	✅	匹配相应的 `command.queued`

快速参考：代理轮次流

典型的代理行为轮次按以下顺序触发事件：

assistant.turn_start          → Turn begins
├── assistant.intent          → What the agent plans to do (ephemeral)
├── assistant.reasoning_delta → Streaming thinking chunks (ephemeral, repeated)
├── assistant.reasoning       → Complete thinking block
├── assistant.message_delta   → Streaming response chunks (ephemeral, repeated)
├── assistant.message         → Complete response (may include toolRequests)
├── assistant.usage           → Token usage for this API call (ephemeral)
│
├── [If tools were requested:]
│   ├── permission.requested  → Needs user approval (ephemeral)
│   ├── permission.completed  → Approval result (ephemeral)
│   ├── tool.execution_start  → Tool begins
│   ├── tool.execution_partial_result  → Streaming tool output (ephemeral, repeated)
│   ├── tool.execution_progress        → Progress updates (ephemeral, repeated)
│   ├── tool.execution_complete        → Tool finished
│   │
│   └── [Agent loops: more reasoning → message → tool calls...]
│
assistant.turn_end            → Turn complete
session.idle                  → Ready for next message (ephemeral)

所有事件类型一目了然

事件类型	临时	类别	关键数据字段
`assistant.turn_start`
助手

          `turnId`、`interactionId?` |

Copilot SDK 中的流式处理事件

谁可以使用此功能？

在本文中