ストリーミング セッション イベント

Overview

セッションでstreaming: trueが設定されると、SDK は、一時的なイベント (デルタ、進行状況の更新) をリアルタイムで、永続的なイベント (完全なメッセージ、ツールの結果) と共に出力します。 すべてのイベントは共通のエンベロープを共有し、その形状がイベント dataに依存するtypeペイロードを運びます。

イベント エンベロープ

種類に関係なく、すべてのセッション イベントには次のフィールドが含まれます。

イベントに登録する

// 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() フューチャーを破棄すると、進行中の起動処理が取り消され、セッションの登録が解除されるため、同じセッション ID を使用した再試行は成功します。 クリーンアップの対象は、中断された起動処理が所有していた当該登録に厳密に限定されているため、すでに同じセッション ID を引き継いでいる再試行を排除することはできません。

スタートアップ バッファリングは、次の場合に計画する価値があります。

• イベント バッファーは有限であり、 event_buffer_capacity がオーバーライドしない限り 512 イベントです。 0 の容量は、クランプされるのではなく、invalid-config エラーとして拒否されます。
• 低速サブスクライバーは、スキップされたイベントの数を報告する Lagged エラーを確認します。 セッションのイベント ループにバックプレッシャを適用することはありません。
• 大規模なスタートアップ バーストの無損失ビューを必要とするコンシューマーは、それをカバーする容量を構成するか、 start()と同時にサブスクリプションをドレインする必要があります。

親エージェントの応答のみをレンダリングする

サブエージェント イベントは親セッション ストリームを共有し、エンベロープ レベルの agentIdを含めます。 ルート/メイン エージェント イベントとセッション レベルのイベントでは agentIdが省略されるため、メイン チャット レンダラーは、 agentId が設定されているアシスタント イベントを無視し、代わりにそれらのイベントをトレースまたは進行状況 UI にルーティングできます。

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 ペイロード フィールドを示します。 共通のエンベロープ フィールドについては、上記で説明しています。