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

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 の容量は、クリップされるのではなく、無効な設定エラーとして拒否されます。
• 低速サブスクライバーは、スキップされたイベントの数を報告する 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

Deprecated. ライブターミナル出力には tool.shell_output を使用します。 このエフェメラル イベントは、移行中は置換先と並行して引き続き発行されます。同じ出力を 2 回表示しないように、1 つの表現のみをサブスクライブします。

tool.shell_output

儚い。 接続されたターミナル コマンドまたはユーザーが要求したターミナル コマンドからの追記専用の出力。 各イベントには、モデルの最終的なツール結果の書式設定に使用される区切り記号やマーカーを使用せずに、新しく観察されたシークレット フィルター処理されたテキストが含まれます。

streamとtextごとにtoolCallIdを個別に蓄積するか、統合表示用にチャンクを順番どおりに結合します。 シーケンス番号は、重複と欠落したチャンクを識別します。独立したオペレーティング システムの書き込み間の正確な順序は示しません。 後から購読したサブスクライバーは、0 より大きい最初のシーケンスを受信できます。

これらのイベントはライブ専用です。再開しても永続化または再生されません。 最終的な tool.execution_complete 結果、モデルに対する書式設定、分離されたコマンドのキャプチャは変更されません。 テキストにはターミナル コントロール シーケンスを含めることができます。レンダラーは、通常のターミナル テキスト処理を適用する必要があります。

接続されたターミナル コマンドは、非同期で実行される場合や initial_wait を過ぎても続行する場合、tool.execution_complete の後も実行を続けることができます。 続行中に受信した出力は、元の toolCallId を使用し、ゼロから再開するのではなく、同じ sequence を続行します。 アクティブな呼び出しのみを表示するコンシューマーは、完了した呼び出し状態を再作成するのではなく、完了後に受信したチャンクを無視する必要があります。

シークレットのフィルタリングは、デコードされた各チャンクに対して適用されます。 ランタイムは人為的に行を分割しませんが、オペレーティング システムの読み取りにより、行またはシークレットが複数のチャンクにまたがって分割されることがあります。クロスチャンク シークレット再構築は提供されていません。

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 も含まれています。

書き込み要求は、promptRequest と fileEdits の両方に permissionRequest を含めることもできます。 各エントリにはオプションの before と after スナップショットが含まれており、それぞれにセッション ファイルシステム名前空間内の絶対pathと完全なUTF-8 contentがあります。 before がないことは作成を意味し、after がないことは削除を意味します。 空の content 文字列は、使用できないプレビューではなく、空のファイルを表します。 移動は、その両側に異なるパスを持つことができます。 移動によって既存の宛先が上書きされると、別のエントリでソースの削除と宛先の置換が記述されます。

これらのスナップショットは、後でライブ ファイルシステムを読み取るのではなく、計画された操作を記述します。 サンドボックスで保護されたファイルを読み取る前に行われた要求、UTF-8 以外のコンテンツ、名前付きパイプなどの読み取り不可能または通常ファイルではない移動先など、完全なテキスト プレビューを提供できない場合、ランタイムは fileEdits を省略します。 空の legacy newFileContents 値を削除と見なさないでください。 プレビューを使用しないコンシューマーは、既存のフィールドと承認の選択肢を引き続き使用できます。

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