GitHub Copilot SDK

概要

GitHub Copilot SDK は、同じ Copilot CLI エージェントランタイムを JSON-RPC で公開し、アプリが独自のオーケストレーションレイヤーを構築する代わりに Copilot をプログラムで駆動できるようにします。

ステータス: パブリックプレビュー
SDK: Node.js/TypeScript、Python、Go、.NET、Java
アーキテクチャ: Application -> SDK client -> JSON-RPC -> Copilot CLI

このスキルの使い方

Copilot SDK を支援する際：

1. メモリよりも公式ドキュメントインデックスと言語固有の README を優先します。
2. トップレベルの SDK README と docs/ を共有動作の情報源として扱います。
3. 安定性や破壊的な変更が重要な場合はプレビューステータスを指摘します。
4. ランタイム発見が利用可能な場合、listModels() 経由でのモデルリストのハードコーディングを避けます。
5. 権限、ライフサイクルメソッド、およびイベント名に関する古い情報に注意します。

現在の情報源

コア SDK ドキュメント

• GitHub Copilot SDK リポジトリ
• ドキュメントインデックス
• Getting Started ガイド
• セットアップガイド
• ローカル CLI セットアップ
• バンドル CLI セットアップ
• バックエンドサービスセットアップ
• スケーリングとマルチテナント
• Azure Managed Identity と BYOK
• 認証
• BYOK
• フィーチャーインデックス
• イメージ入力
• Steering とキューイング
• OpenTelemetry インストルメンテーション
• トラブルシューティング
• SDK/CLI 互換性

言語固有のドキュメント

• Node.js / TypeScript README
• Python README
• Go README
• .NET README
• Java SDK リポジトリ

Copilot CLI と GitHub ドキュメント

• GitHub Copilot CLI について
• GitHub Copilot CLI の使用
• カスタムエージェント設定リファレンス
• MCP によるエージェントモードの強化
• サポートされているモデル

レシピとサンプル

• Copilot SDK cookbook
• Node.js サンプル
• Go サンプル
• .NET サンプル

---

高価値の事実

認証と前提条件

• GitHub Copilot のサブスクリプションは、通常の SDK 使用に必要です。
• BYOK はサポートされており、GitHub Copilot 認証は不要です。
• Node.js、Python、.NET は Copilot CLI を自動的にバンドルします。
• Go はインストール済みの CLI を使用するか、go tool bundler ワークフローで CLI を埋め込み/バンドルできます。
• Java は現在 github/copilot-sdk-java にあり、CLI を別途インストールすることを前提としています。
• Azure Managed Identity / Entra auth は、DefaultAzureCredential から短命のベアラートークンを渡すことで、文書化された BYOK パターンとしてサポートされています。

権限

• SDK はデフォルト拒否の権限モデルを使用します。
• 実際には、create/resume フローは以下のような明示的な権限ハンドラーを提供する必要があります：
  • TypeScript: approveAll
  • Python: PermissionHandler.approve_all
  • Go: copilot.PermissionHandler.ApproveAll
  • .NET: PermissionHandler.ApproveAll
  • Java: PermissionHandler.APPROVE_ALL

セッションライフサイクル

• 推奨されるクリーンアップ方法: disconnect()
• 非推奨のクリーンアップ方法: destroy()
• セッションを確実に再開するには、作成時に独自の sessionId を提供してください。
• BYOK プロバイダー設定は、キーが永続化されないため、再開時に再度提供する必要があります。

トランスポートとデプロイ

• デフォルトトランスポートは stdio で SDK 管理 CLI プロセスです。
• 外部ヘッドレス CLI サーバーに cliUrl 経由で接続できます。
• 現在の外部サーバードキュメントは以下を使用しています：

copilot --headless --port 4321

モデル

• ユーザーが特に固定リストを必要とする場合を除き、モデルサポートをハードコーディングしないでください。
• client.listModels() と公式サポートモデルページを優先してください。
• reasoningEffort はそれをサポートするモデルに存在します。

---

インストール

SDK	インストール
Node.js / TypeScript	npm install @github/copilot-sdk
Python	pip install github-copilot-sdk
Go	go get github.com/github/copilot-sdk/go
.NET	dotnet add package GitHub.Copilot.SDK
Java	Maven/Gradle パッケージ com.github:copilot-sdk-java

セットアップとデプロイ選択肢

アプリケーションの形に一致するセットアップを選択してください：

• ローカル CLI - 個人ツール開発の最も単純なパス。
• バンドル CLI - デスクトップ/配布可能なツール用にアプリと共に CLI バイナリを出荷します。
• バックエンドサービス - ヘッドレスモードで CLI を実行し、cliUrl で接続します。
• スケーリングとマルチテナント - 共有 CLI vs CLI-per-user、共有ストレージ、セッションロック。
• Azure Managed Identity - 静的 API キーの代わりに、Azure auth が実際の要件である場合、BYOK で短命のベアラートークンを使用します。

クイックスタートパターン

すべての言語で同じメンタルモデルを使用します：

1. クライアントを作成/開始します。
2. 権限ハンドラーを使用してセッションを作成します。
3. ストリーミングまたは進捗が必要な場合、send() 前にイベントハンドラーを登録します。
4. send() または sendAndWait() で送信します。
5. session.idle または返された最終メッセージを待ちます。
6. セッションを disconnect() し、クライアントを停止/破棄します。

TypeScript の例

import { CopilotClient, approveAll } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
  model: "gpt-5",
  streaming: true,
  onPermissionRequest: approveAll,
});

session.on("assistant.message_delta", (event) => {
  process.stdout.write(event.data.deltaContent ?? "");
});

await session.sendAndWait({ prompt: "What is 2+2?" });

await session.disconnect();
await client.stop();

---

覚えておく必要があるコア機能

クライアントとセッション API

SDK 全体の共通操作：

• クライアントライフサイクル: start()、stop()、forceStop()
• セッションライフサイクル: createSession()、resumeSession()、disconnect()
• メッセージング: send()、sendAndWait()、abort()、getMessages()
• 発見: listModels()、listSessions()、getStatus() / ping()

イベントとストリーミング

• 最終的なアシスタント出力は assistant.message に到着します。
• ストリーミングテキストは assistant.message_delta に到着します。
• session.idle は信頼できる「ターン完了」シグナルです。
• イベントシステムには、reasoning、ツール進捗、権限、elicitation、サブエージェント、スキルイベントが含まれるようになりました。

references/event-system.md を参照してください。

カスタムツール

• Node は Zod または生の JSON Schema で defineTool(...) を使用します。
• Python は Pydantic モデルで @define_tool を使用します。
• Go は DefineTool(...) を優先します。
• .NET は AIFunctionFactory.Create(...) を使用します。
• ビルトインのオーバーライドには常に明示的なオプトインが必要です：
  • TypeScript: overridesBuiltInTool: true
  • Python: overrides_built_in_tool=True
  • Go: OverridesBuiltInTool = true
  • .NET: AdditionalProperties["is_override"] = true
• カスタムツールは skipPermission にもオプトインできます。

カスタムエージェント、MCP、フック、スキル

• customAgents はセッションごとにサブエージェントを定義できます。
• mcpServers はローカルまたはリモート MCP サーバーをアタッチします。
• フックは onPreToolUse、onPostToolUse、onUserPromptSubmitted、およびライフサイクル/エラーフックなどの制御ポイントを提供します。
• スキルは skillDirectories で読み込まれます。disabledSkills で選択的に無効化します。

references/cli-agents-mcp.md を参照してください。

アタッチメント、コマンド、相互作用

• セッションはファイル、ディレクトリ、イメージアタッチメントを送信できます。
• イメージ入力はファイルとブロブアタッチメント両方をサポート、視覚はモデル機能を通じてチェックする必要があります。
• 送信中のメッセージングは、steering 用の mode: "immediate" とキューイング用の mode: "enqueue" をサポートしています。
• SDK はカスタムスラッシュ commands を登録できます。
• アプリは onUserInputRequest でユーザーの質問に答えられます。
• リッチ UI プロンプトは、接続されたクライアントがサポートする場合、elicitation ハンドラーと session.ui を通じて利用可能です。

テレメトリと監視

• SDK は TelemetryConfig を通じた OpenTelemetry 設定をサポートします。
• トレースコンテキスト伝播は組み込まれており、Node はアウトバウンド伝播用に明示的な onGetTraceContext コールバックを使用します。

永続化と長時間実行作業

• 再開可能セッション用に安定した sessionId を使用します。
• 圧縮が必要な長時間実行ワークフロー用に infiniteSessions を使用します。
• セッション状態は、設定でオーバーライドされない限り ~/.copilot/session-state/ に保存されます。

SDK vs CLI のみの機能

• SDK は、セッション、モデル、プラン、モード切り替え、ワークスペースファイル、カスタムエージェント、フック、MCP、スキル、テレメトリのプログラマティックなサーフェスを公開します。
• 多くのターミナル UX フィーチャーは CLI のみのまま、ほとんどのスラッシュコマンドワークフロー、インタラクティブピッカー、エクスポート/共有コマンドなど。
• CLI ワークフローをアプリコードに変換する際、SDK 同等物を持つスラッシュコマンドを想定する前に互換性ガイドをチェックしてください。

---

言語規則

概念	TypeScript	Python	Go	.NET	Java
セッション作成	createSession()	create_session()	CreateSession()	CreateSessionAsync()	createSession()
セッション再開	resumeSession()	resume_session()	ResumeSession()	ResumeSessionAsync()	resumeSession()
最終的なコンテンツ	event.data.content	event.data.content	*event.Data.Content	evt.Data.Content	event.getData().content()
デルタコンテンツ	event.data.deltaContent	event.data.delta_content	*event.Data.DeltaContent	evt.Data.DeltaContent	event.getData().deltaContent()
スキルフィールド	skillDirectories	skill_directories	SkillDirectories	SkillDirectories	setSkillDirectories(...)

---

よくある落とし穴

• SDK はパブリックプレビューのため、古いサンプルはすぐに古くなります。
• ハードコードされたモデルテーブルは古くなります。ランタイム発見を優先してください。
• destroy() はまだ古いサンプルに現れますが、disconnect() が現在の方法です。
• 権限ハンドラーがないとすぐに混乱が生じます。実際のセッションでは必須として扱ってください。
• assistant.message と assistant.message_delta は event.data.* を使用し、トップレベルの event.content ではありません。
• ストリーミング/イベントサブスクリプションは send() 前にアタッチする必要があります。
• 呼び出し元が提供した sessionId なしでのセッション再開は、運用化が難しいです。

---

このスキル内のローカルリファレンスファイル

• references/working-examples.md - ツールと再開パターンを含む現在のスターターサンプル
• references/event-system.md - イベント名、ライフサイクル、言語アクセスパターン
• references/cli-agents-mcp.md - カスタムエージェント、スキル、MCP、ヘッドレス CLI、設定場所
• references/troubleshooting.md - 一般的な障害、デバッグログ、認証、権限、トランスポート問題