SDK と CLI の互換性

メモ

          Copilot SDK は現在 パブリック プレビューです。 機能と可用性は変更される場合があります。

          GitHub Copilot SDK は、JSON-RPC プロトコルを介して GitHub Copilot CLI（コマンドラインインターフェース） と通信します。 SDK で使用できるようにするには、このプロトコルを使用して機能を明示的に公開する必要があります。 多くの対話型 CLI 機能はターミナル固有であり、プログラムでは使用できません。

機能の比較

SDK で使用可能

特徴	SDK メソッド	メモ

          **セッション管理** |

| | | セッションの作成 | createSession() | 完全な構成のサポート | | セッションを再開する | resumeSession() | 無限のセッションワークスペース | | セッションを切断する | disconnect() | メモリ内リソースを解放する | | セッションを破棄する | destroy() | 代わりに disconnect() を使用してください | | セッションの削除 | deleteSession() | ストレージから削除する | | セッションの一覧 | listSessions() | すべての保存済みセッション | | 最後のセッションを取得する | getLastSessionId() | すばやく再開 | | フォアグラウンドセッションを取得する | getForegroundSessionId() | 複数セッションの調整 | | フォアグラウンドセッションを設定する | setForegroundSessionId() | 複数セッションの調整 | | メッセージング | | | | メッセージの送信 | send() | 添付ファイルあり | | 送信して待機する | sendAndWait() | 完了するまでブロックする | | ステアリング (イミディエイトモード) | send({ mode: "immediate" }) | 中止せずに途中ターンを挿入する | | キューイング (エンキューモード) | send({ mode: "enqueue" }) | 順次処理用のバッファー (既定) | | 添付ファイル | send({ attachments: [{ type: "file", path }] }) | 画像の自動エンコードとサイズ変更 | | ディレクトリの添付ファイル | send({ attachments: [{ type: "directory", path }] }) | ディレクトリコンテキストをアタッチする | | 履歴を取得する | getMessages() | すべてのセッションイベント | | アボート | abort() | 進行中のリクエストをキャンセルする | | ツール | | | | カスタムツールを登録する | registerTools() | 完全な JSON スキーマのサポート | | ツールのアクセス許可の制御 | onPreToolUse フック | 許可/拒否/要求 | | ツールの結果の変更 | onPostToolUse フック | 結果の変換 | | 使用可能なツールまたは除外されたツール | availableTools、excludedTools 設定 | フィルターツール | | モデル | | | | モデルを一覧表示する | listModels() | 機能、課金、ポリシー | | モデルの設定 (作成時) | model セッション構成 | セッションごと | | モデルの切り替え (セッション中) | session.setModel() | また、次を介して session.rpc.model.switchTo() | | 現在のモデルを取得する | session.rpc.model.getCurrent() | アクティブなモデルのクエリを実行する | | 推論作業 | reasoningEffort 設定 | サポートされているモデルの場合 | | エージェントモード | | | | 現在のモードを取得する | session.rpc.mode.get() | 現在のモードを返します。 | | モードの設定 | session.rpc.mode.set() | モードを切り替える | | プラン管理 | | | | プランを読む | session.rpc.plan.read() | plan.mdのコンテンツとパスを取得する | | プランの更新 | session.rpc.plan.update() | plan.md コンテンツを書き込む | | 計画の削除 | session.rpc.plan.delete() | plan.md の削除 | | ワークスペースファイル | | | | ワークスペースファイルを一覧表示する | session.rpc.workspace.listFiles() | セッションワークスペース内のファイル | | ワークスペースファイルの読み取り | session.rpc.workspace.readFile() | ファイルの内容を読み取る | | ワークスペースファイルを作成する | session.rpc.workspace.createFile() | ワークスペースにファイルを作成する | | 認証 | | | | 認証の状態を取得する | getAuthStatus() | ログイン状態を確認する | | トークンを使用する | githubToken オプション | プログラムによる認証 | | 接続 | | | | Ping | client.ping() | サーバータイムスタンプを使用した正常性チェック | | サーバーの状態を取得する | client.getStatus() | プロトコルのバージョンとサーバー情報 | | MCP サーバー | | | | ローカル/stdio サーバー | mcpServers 設定 | プロセスを生成する | | リモート HTTP/SSE | mcpServers 設定 | サービスへの接続 | | フック | | | | ツール使用前 | onPreToolUse | 権限、引数を変更 | | ツールの使用後 | onPostToolUse | 結果を変更する | | ユーザープロンプト | onUserPromptSubmitted | プロンプトを変更する | | セッションの開始/終了 | onSessionStart、onSessionEnd | ソース/理由を含むライフサイクル | | エラー処理 | onErrorOccurred | カスタム処理 | | イベント | | | | すべてのセッションイベント | on()、once() | 40 以上のイベントの種類 | | ストリーミング | streaming: true | デルタイベント | | セッション構成 | | | | カスタムエージェント | customAgents 設定 | 特殊なエージェントを定義する | | システムメッセージ | systemMessage 設定 | 追加または置換 | | カスタムプロバイダー | provider 設定 | BYOK のサポート | | 無限セッション | infiniteSessions 設定 | 自動圧縮 | | 権限ハンドラー | onPermissionRequest | 要求の承認/拒否 | | ユーザー入力ハンドラー | onUserInputRequest | ask_userの処理 | | スキル | skillDirectories 設定 | カスタムスキル | | 無効なスキル | disabledSkills 設定 | 特定のスキルを無効にする | | 設定ディレクトリ | configDir 設定 | デフォルト設定の場所を上書きする | | クライアント名 | clientName 設定 | User-Agent でアプリを識別する | | 作業ディレクトリ | workingDirectory 設定 | セッション cwd を設定する | | 試験段階 | | | | エージェント管理 | session.rpc.agent.* | 現在のエージェントを一覧表示、選択、選択解除、取得する | | フリートモード | session.rpc.fleet.start() | 並列サブエージェントの実行 | | 手動圧縮 | session.rpc.compaction.compact() | オンデマンドで圧縮をトリガーする |

SDK では使用できません (CLI のみ)

特徴	CLI コマンド/オプション	理由

          **セッションのエクスポート** |

対処方法

セッションのエクスポート

          `--share` オプションは SDK では使用できません。 これを解決するには、次のようにします。

* イベントを手動で収集する: セッションイベントをサブスクライブし、独自のエクスポートを作成します。

TypeScript

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getMessages();
// Format as markdown yourself

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getMessages();
// Format as markdown yourself

1 回限りのエクスポートには CLI を直接使用します。

アクセス許可の制御

SDK では、既定で拒否アクセス許可モデルが使用されます。アプリが onPermissionRequest ハンドラーを提供しない限り、すべてのアクセス許可要求 (ファイルの書き込み、シェルコマンド、URL フェッチなど) は拒否されます。

          `--allow-all-paths`または`--yolo`の代わりに、アクセス許可ハンドラーを使用します。

TypeScript

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

トークンの使用状況の追跡

          `/usage`の代わりに、使用状況イベントをサブスクライブします。

TypeScript

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

コンテキスト圧縮

          `/compact`の代わりに、自動圧縮を構成するか、手動でトリガーします。

TypeScript

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

メモ

しきい値は、絶対トークン数ではなく、コンテキスト使用率の比率 (0.0 から 1.0) です。

プランの管理

プログラムによるセッション計画の読み取りと書き込み:

TypeScript

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

メッセージ制御

中止せずに、現在の LLM ターンにメッセージを挿入します。

TypeScript

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

プロトコルの制限事項

SDK は、CLI の JSON-RPC プロトコルを介して公開されている機能にのみアクセスできます。使用できない CLI 機能が必要な場合:

        **代替手段を確認します。** 多くの機能には、SDK に相当するものがあります (上記 [の回避策を](#workarounds) 参照)。

        **CLI を直接使用します。** 1 回限りの操作の場合は、CLI を呼び出します。

        **機能を要求します。** プロトコルのサポートを要求するには、 [github/copilot-sdk](https://github.com/github/copilot-sdk/issues) リポジトリで問題を開きます。

バージョン互換性

SDK プロトコルの範囲	CLI プロトコルのバージョン	互換性
v2-v3	v3	完全なサポート
v2-v3	v2	自動 v2 アダプターでサポート

SDK は起動時に CLI とプロトコルバージョンをネゴシエートします。 SDK では、プロトコルバージョン 2 から 3 がサポートされています。 v2 CLI サーバーに接続すると、SDK は tool.call と permission.request メッセージを v3 イベントモデルに自動的に適合させます。コードの変更は必要ありません。

実行時にバージョンを確認できます。

TypeScript

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

この機能を使用できるユーザーについて

この記事で

機能の比較

SDK で使用可能

SDK では使用できません (CLI のみ)

対処方法

セッションのエクスポート

アクセス許可の制御

トークンの使用状況の追跡

コンテキスト圧縮

プランの管理

メッセージ制御

プロトコルの制限事項

バージョン互換性