Copilot SDK 中的流式事件

注意

Copilot SDK 目前处于公开预览阶段。功能和可用性可能会更改。

Copilot 代理执行的每一个操作——思考、编写代码、运行工具——都会以 会话事件 的形式发出，您可以对其进行订阅。本文提供每种事件类型的字段级参考，帮助您准确了解会返回哪些数据。

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

概念	描述
短暂事件	瞬时的；实时流式传输，但不会持久化到会话日志。会话恢复时不会重放。
持久化事件	保存到磁盘上的会话事件日志。会话恢复时会重放。
增量事件	短暂的流式块（文本或推理）。累计增量以构建完整内容。
`parentId` 链	每个事件的 `parentId` 指向前一个事件，形成可遍历的链表。

事件信封

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

字段	类型	描述
`id`	`string` (UUID v4)	唯一事件标识符
`时间戳`	`string` (ISO 8601)	事件创建时间
`parentId`	`string \| null`	链中前一个事件的 ID；首个事件为 `null`
`ephemeral`	`boolean?`	`true` 对短暂事件为 `true`；如果缺失或为 `false` 则表示持久化事件
`type`	`string`	事件类型判别标识（见下表）
`data`	`object`	事件特定负载

订阅事件

// 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 仓库。Java 示例请参阅 github/copilot-sdk-java 仓库。

提示

Python / Go：这些 SDK 使用单一的 Data 类/结构体，所有可能的字段均为可选/可为空。仅表中列出的字段会在对应事件类型中填充——其余字段为 None / nil。

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

TypeScript：TypeScript SDK 使用判别联合——在匹配 event.type 时，data 负载会自动缩小为对应的结构。

Java：Java SDK 使用带有类型化数据访问器的事件类（例如 AssistantMessageEvent、SessionIdleEvent）。

助理事件

这些事件跟踪代理的响应生命周期——从回合开始、流式块到最终消息。

`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`		加密的扩展思考（Anthropic 模型）；会话绑定
`reasoningText`	`string`		来自扩展思考的可读推理文本
`encryptedContent`	`string`		加密的推理内容（OpenAI 模型）；会话绑定
`phase`	`string`		生成阶段（例如 `"thinking"` 与 `"response"`）
`outputTokens`	`number`		API 响应的实际输出 token 数量
`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 调用的 token 使用量和费用信息。

数据字段	类型	是否必填	描述
`model`	`string`	✅	模型标识符（例如 `"gpt-4.1"`）
`inputTokens`	`number`		消耗的输入 tokens
`outputTokens`	`number`		生成的输出 tokens
`cacheReadTokens`	`number`		从提示缓存读取的 tokens
`cacheWriteTokens`	`number`		写入提示缓存的 tokens
`cost`	`number`		计费用的模型倍率费用
`duration`	`number`		API 调用时长（毫秒）
`initiator`	`string`		触发此调用的原因（例如 `"sub-agent"`）；用户发起时缺失
`apiCallId`	`string`		提供者返回的完成 ID（例如 `chatcmpl-abc123`）
`providerCallId`	`string`		GitHub 请求追踪 ID（`x-github-request-id`）
`parentToolCallId`	`string`		当使用来源于子代理时设置
`quotaSnapshots`	`Record<string, QuotaSnapshot>`		按配额标识符键入的每个配额资源使用情况
`copilotUsage`	`CopilotUsage`		API 返回的分项 token 成本细分

`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` 事件的增量
`成功`	`boolean`	✅	执行是否成功
`model`	`string`		生成此工具调用的模型
`interactionId`	`string`		交互标识符
`isUserRequested`	`boolean`		当用户明确请求此工具调用时为 `true`
`result`	`结果`		成功时存在（见下文）
`error`	`{ message, code? }`		失败时存在
`toolTelemetry`	`object`		工具特定的遥测
`parentToolCallId`	`string`		当由子代理调用时设置

Result 字段

字段	类型	是否必填	描述
`content`	`string`	✅	发送给 LLM 的简要结果（可能为节省 token 而截断）
`detailedContent`	`string`		用于展示的完整结果，保留完整内容如 diff
`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`

上下文窗口压缩完成。

数据字段	类型	是否必填	描述
`成功`	`boolean`	✅	压缩是否成功
`error`	`string`		压缩失败时的错误信息
`preCompactionTokens`	`number`		压缩前的 token 数量
`postCompactionTokens`	`number`		压缩后的 token 数量
`preCompactionMessagesLength`	`number`		压缩前的消息数量
`messagesRemoved`	`number`		被移除的消息
`tokensRemoved`	`number`		被移除的 token
`summaryContent`	`string`		LLM 生成的压缩历史摘要
`checkpointNumber`	`number`		用于恢复的检查点快照编号
`checkpointPath`	`string`		检查点存储的文件路径
`compactionTokensUsed`	`{ input, output, cachedInput }`		压缩 LLM 调用的 token 使用情况
`requestId`	`string`		压缩调用的 GitHub 请求追踪 ID

`session.title_changed`

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

数据字段	类型	是否必填	描述
`title`	`string`	✅	新的会话标题

`session.context_changed`

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

数据字段	类型	是否必填	描述
`cwd`	`string`	✅	当前工作目录
`gitRoot`	`string`		Git 仓库根目录
`repository`	`string`		`"owner/name"` 格式的仓库
`branch`	`string`		当前 Git 分支

`session.usage_info`

短暂的。上下文窗口使用快照。

数据字段	类型	是否必填	描述
`tokenLimit`	`number`	✅	模型上下文窗口的最大 token 数
`currentTokens`	`number`	✅	当前上下文窗口中的 token 数
`messagesLength`	`number`	✅	对话中当前的消息数量

`session.task_complete`

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

数据字段	类型	是否必填	描述
`summary`	`string`		已完成任务的摘要

`session.shutdown`

会话已结束。

数据字段	类型	是否必填	描述
`shutdownType`	`"routine" \| "error"`	✅	正常关闭或崩溃
`errorReason`	`string`		`shutdownType` 为 `"error"` 时的错误描述
`totalPremiumRequests`	`number`	✅	已使用的高级 API 请求总数
`totalApiDurationMs`	`number`	✅	C累计 API 调用时长（毫秒）
`sessionStartTime`	`number`	✅	会话开始时的 Unix 时间戳（毫秒）
`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 命令
`"write"`	`fileName`, `diff`, `intention`, `newFileContents?`	写入/修改文件
`"read"`	`path`, `intention`	读取文件或目录
`"mcp"`	`serverName`, `toolName`, `toolTitle`, `args?`, `readOnly`	调用 MCP 工具
`"url"`	`url`, `intention`	获取 URL
`"memory"`	`subject`, `fact`, `citations`	存储记忆
`"custom-tool"`	`toolName`, `toolDescription`, `args?`	调用自定义工具

所有 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 Schema

`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`	✅	Skill name
`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 引用附件
`来源`	`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`	✅	Tool call ID for this invocation
`toolName`	`string`	✅	Name of the external tool
`arguments`	`object`		Arguments for the tool

`external_tool.completed`

短暂的。外部工具请求已解决。

数据字段	类型	是否必填	描述
`requestId`	`string`	✅	对应 `external_tool.requested` 事件

`exit_plan_mode.requested`

短暂的。代理已创建计划并希望退出计划模式。

数据字段	类型	是否必填	描述
`requestId`	`string`	✅	使用此方式通过 `session.respondToExitPlanMode()` 响应
`summary`	`string`	✅	计划摘要
`planContent`	`string`	✅	完整的计划文件内容
`actions`	`string[]`	✅	可用的用户操作（例如 approve、edit、reject）
`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?`
`assistant.intent`	✅	助理	`intent`
`assistant.reasoning`		助理	`reasoningId`, `content`
`assistant.reasoning_delta`	✅	助理	`reasoningId`, `deltaContent`
`assistant.streaming_delta`	✅	助理	`totalResponseSizeBytes`
`assistant.message`		助理	`messageId`, `content`, `toolRequests?`, `outputTokens?`, `phase?`
`assistant.message_delta`	✅	助理	`messageId`, `deltaContent`, `parentToolCallId?`
`assistant.turn_end`		助理	`turnId`
`assistant.usage`	✅	助理	`model`, `inputTokens?`, `outputTokens?`, `cost?`, `duration?`
`tool.user_requested`		工具	`toolCallId`, `toolName`, `arguments?`
`tool.execution_start`		工具	`toolCallId`, `toolName`, `arguments?`, `mcpServerName?`
`tool.execution_partial_result`	✅	工具	`toolCallId`, `partialOutput`
`tool.execution_progress`	✅	工具	`toolCallId`, `progressMessage`
`tool.execution_complete`		工具	`toolCallId`, `success`, `result?`, `error?`
`session.idle`	✅	会话	`backgroundTasks?`
`session.error`		会话	`errorType`, `message`, `statusCode?`
`session.compaction_start`		会话	(空)
`session.compaction_complete`		会话	`success`, `preCompactionTokens?`, `summaryContent?`
`session.title_changed`	✅	会话	`title`
`session.context_changed`		会话	`cwd`, `gitRoot?`, `repository?`, `branch?`
`session.usage_info`	✅	会话	`tokenLimit`, `currentTokens`, `messagesLength`
`session.task_complete`		会话	`summary?`
`session.shutdown`		会话	`shutdownType`, `codeChanges`, `modelMetrics`
`permission.requested`	✅	权限	`requestId`, `permissionRequest`
`permission.completed`	✅	权限	`requestId`, `result.kind`
`user_input.requested`	✅	用户输入	`requestId`, `question`, `choices?`
`user_input.completed`	✅	用户输入	`requestId`
`elicitation.requested`	✅	用户输入	`requestId`, `message`, `requestedSchema`
`elicitation.completed`	✅	用户输入	`requestId`
`subagent.started`		子代理	`toolCallId`, `agentName`, `agentDisplayName`
`subagent.completed`		子代理	`toolCallId`, `agentName`, `agentDisplayName`
`subagent.failed`		子代理	`toolCallId`, `agentName`, `error`
`subagent.selected`		子代理	`agentName`, `agentDisplayName`, `tools`
`subagent.deselected`		子代理	(空)
`skill.invoked`		技能	`name`, `path`, `content`, `allowedTools?`
`abort`		控制	`reason`
`user.message`		用户	`content`, `attachments?`, `agentMode?`
`system.message`		系统	`content`, `role`
`external_tool.requested`	✅	外部工具	`requestId`, `toolName`, `arguments?`
`external_tool.completed`	✅	外部工具	`requestId`
`command.queued`	✅	命令	`requestId`, `command`
`command.completed`	✅	命令	`requestId`
`exit_plan_mode.requested`	✅	计划模式	`requestId`, `summary`, `planContent`, `actions`
`exit_plan_mode.completed`	✅	计划模式	`requestId`

谁可以使用此功能？

本文内容