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` フック | 許可/拒否/要求 |

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

特徴	CLI コマンド/オプション	理由
セッションのエクスポート
[ファイルへエクスポート]

          `--share`、`/share` | プロトコルに含まれていない |

対処方法

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

          `--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 に相当するものがあります (上記の回避策を参照)。
CLI を直接使用します。 1 回限りの操作の場合は、CLI を呼び出します。
機能を要求します。 プロトコルのサポートを要求するには、 github/copilot-sdk リポジトリで問題を開きます。

バージョン互換性

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 のみ)

対処方法

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

アクセス許可の制御

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

コンテキスト圧縮

プランの管理

メッセージ制御

プロトコルの制限事項

バージョン互換性