流式处理会话事件

概述

对会话设置 streaming: true 时，SDK 会实时发出临时事件（增量、进度更新）以及持久事件（完整的消息、工具结果）。 所有事件共享一个公用信封，并携带一个载荷，其形状取决于事件 data。

事件封装

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

订阅事件

// 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);
});

from copilot.session_events import SessionEventType

def handle(event):
    if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
        print(event.data.delta_content, end="", flush=True)

session.on(handle)

session.On(func(event copilot.SessionEvent) {
    if d, ok := event.Data.(*copilot.AssistantMessageDeltaData); ok {
        fmt.Print(d.DeltaContent)
    }
})

session.On<SessionEvent>(evt =>
{
    if (evt is AssistantMessageDeltaEvent delta)
    {
        Console.Write(delta.Data.DeltaContent);
    }
});

// All events
session.on(event -> System.out.println(event.getType()));

// Specific event type — data is narrowed to the matching class
session.on(AssistantMessageDeltaEvent.class, event ->
    System.out.print(event.getData().deltaContent())
);

会话开始前订阅

会话可以在创建或恢复调用返回之前发出事件。 代理可能已经在运行——尤其是在使用 continuePendingWork 恢复时——而且诸如 session.idle 之类的瞬时事件绝不会写入会话日志，因此 getMessages 之后也无法恢复它们。 在会话句柄创建之后安装的订阅会错过该启动时机。

use github_copilot_sdk::{Client, SessionConfig};

async fn create_without_missing_startup_events(
    client: &Client,
) -> Result<(), github_copilot_sdk::Error> {
    let prepared = client.prepare_session(
        SessionConfig::default().with_event_buffer_capacity(2048),
    )?;

    // Installed before any wire activity: nothing is dropped for lack of a receiver.
    let mut events = prepared.subscribe();
    tokio::spawn(async move {
        while let Ok(event) = events.recv().await {
            println!("{}", event.event_type);
        }
    });

    let session = prepared.start().await?;
    let _ = session;
    Ok(())
}

prepare_* 是同步且惰性的：它会验证缓冲区容量、分配一个本地通道，而不会执行任何其他操作。 尚未注册任何会话，在首次轮询 start() 之前，CLI 不会收到任何内容。 丢弃一个已准备但从未启动的会话，不会留下任何状态，并会关闭其订阅；丢弃 start() Future 会取消正在进行的启动过程并注销该会话，因此，使用相同的会话 ID 重试会成功。 清理的范围限定为放弃的启动拥有的确切注册，因此无法逐出已接管同一会话 ID 的重试。

启动缓冲值得提前规划：

• 事件缓冲区是有限的— 512 个事件，除非 event_buffer_capacity 重写它。 容量 0 被拒绝，并出现无效配置错误，而不是固定。
• 处理速度较慢的订阅者会看到一个 Lagged 错误，其中会报告跳过了多少个事件。 它们永远不会对会话的事件循环应用反压。
• 需要无损地查看启动时的大量突发数据的使用方，必须配置足以覆盖该突发的容量，或者与 start() 同时并行排空订阅中的数据。

仅显示父代理响应

子代理事件共享父会话流，并包括信封级别的 agentId。 根代理/主代理事件和会话级事件会省略 agentId，因此主聊天渲染器可以忽略已设置 agentId 的助手事件，并将这些事件转而路由到跟踪界面或进度界面。

import type { CopilotSession } from "@github/copilot-sdk";

export function subscribeParentResponse(session: CopilotSession): void {
    session.on("assistant.message_delta", (event) => {
        if (!event.agentId) {
            process.stdout.write(event.data.deltaContent);
        }
    });
}

from copilot import CopilotSession, SessionEvent, SessionEventType
from copilot.session_events import AssistantMessageDeltaData

def subscribe_parent_response(session: CopilotSession) -> None:
    def handle(event: SessionEvent) -> None:
        if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA and event.agent_id is None:
            data = event.data
            if isinstance(data, AssistantMessageDeltaData):
                print(data.delta_content, end="", flush=True)

    session.on(handle)

package example

import (
    "fmt"

    copilot "github.com/github/copilot-sdk/go"
)

func subscribeParentResponse(session *copilot.Session) {
    session.On(func(event copilot.SessionEvent) {
        if event.AgentID != nil {
            return
        }

        if d, ok := event.Data.(*copilot.AssistantMessageDeltaData); ok {
            fmt.Print(d.DeltaContent)
        }
    })
}

using System;
using GitHub.Copilot;

static class ParentAgentResponseExample
{
    public static void SubscribeParentResponse(CopilotSession session)
    {
        session.On<AssistantMessageDeltaEvent>(evt =>
        {
            if (evt.AgentId is null)
            {
                Console.Write(evt.Data.DeltaContent);
            }
        });
    }
}

import com.github.copilot.CopilotSession;
import com.github.copilot.generated.AssistantMessageDeltaEvent;

final class ParentAgentResponseExample {
    static void subscribeParentResponse(CopilotSession session) {
        session.on(AssistantMessageDeltaEvent.class, event -> {
            if (event.getAgentId() == null) {
                System.out.print(event.getData().deltaContent());
            }
        });
    }
}

use github_copilot_sdk::session::Session;

async fn subscribe_parent_response(session: &Session) {
    let mut events = session.subscribe();

    while let Ok(event) = events.recv().await {
        if event.event_type == "assistant.message_delta" && event.agent_id.is_none() {
            if let Some(delta) = event.data.get("deltaContent").and_then(|v| v.as_str()) {
                print!("{delta}");
            }
        }
    }
}

助理活动

这些事件会跟踪代理的响应生命周期 - 从轮次开始，经过流式处理块，直到最终消息。

assistant.turn_start

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

assistant.intent

短暂。 代理当前正在执行的操作的简短描述，随着其工作的进行而更新。

assistant.reasoning

从模型中得出完整的扩展思维定式。 推理完成后发出。

assistant.reasoning_delta

短暂。 实时流式处理的模型扩展思维增量区块。

assistant.message

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

** ToolRequest 领域：**

assistant.message_delta

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

assistant.turn_end

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

assistant.usage

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

assistant.streaming_delta

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

工具执行事件

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

tool.execution_start

当工具开始执行时发出。

tool.execution_partial_result

短暂。 运行中工具的增量输出（例如 bash 的流式输出）。

tool.execution_progress

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

tool.execution_complete

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

** Result 领域：**

tool.user_requested

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

会话生命周期事件

session.idle

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

session.error

会话处理期间出错。

session.compaction_start

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

session.compaction_complete

上下文窗口压缩已完成。

session.title_changed

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

session.context_changed

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

session.usage_info

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

session.session_limits_changed

当前会计窗口的会话限制已更改。 值 null``sessionLimits 表示没有活动限制。

session.usage_checkpoint

用于在会话恢复时重建计费信息的持久累计使用量检查点。

session.task_complete

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

session.shutdown

会话已结束。

权限和用户输入事件

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

permission.requested

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

permissionRequest 是 kind 上的可区分联合：

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

permission.completed

权限请求已解决。

user_input.requested

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

user_input.completed

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

elicitation.requested

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

elicitation.completed

短暂。 启发请求已解决。

子代理和技能事件

subagent.started

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

subagent.completed

子代理成功完成。

subagent.failed

子代理遇到错误。

subagent.selected

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

subagent.deselected

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

skill.invoked

为当前对话激活了技能。

其他事件

abort

当前轮次已中止。

user.message

用户发送了一条消息。 已针对会话时间线进行记录。

system.message

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

external_tool.requested

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

external_tool.completed

解决了外部工具请求。

exit_plan_mode.requested

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

exit_plan_mode.completed

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

command.queued

短暂。 斜杠命令已排队执行。

command.completed

短暂。 排队的命令已解决。

session_limits_exhausted.requested

短暂。 当前会话预算已用尽，运行时需要在继续之前做出用户决策。

session_limits_exhausted.completed

短暂。 一个待处理的超限请求已解决。

快速参考：智能回合流程

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

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
│   ├── permission.completed  → Approval result
│   ├── 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)

所有事件类型一目了然

此表列出了关键 data 有效负载字段。 上面记录了常见的信封字段。