copilot-sdk

Name: copilot-sdk
Author: intellectronica

github.com/intellectronica開発298532 回インストール27 週間前に更新

copilot-sdk について

GitHub Copilot SDK を使ったアプリ開発のためのスキルガイドです。JSON-RPC 経由で Copilot CLI のエージェントランタイムを利用でき、5つの言語環境、セッション管理、ツール、MCP 設定を扱います。SDK はパブリックプレビューです。

主な機能

015言語のSDK
02JSON-RPCによるCopilot CLI利用
03セッションとイベントAPI
04カスタムツールとエージェント
05MCPサーバーの接続
06ストリーミングとテレメトリーの案内

活用シーン

01アプリへのCopilotセッション組み込み
02エージェント応答とツール進捗のストリーミング
03ローカルまたはリモートのMCPサーバー接続
04長時間セッションの再開

MCP 対応

SDK は `mcpServers` を使ってローカルまたはリモートの MCP サーバーをセッションに接続できます。このスキルでは関連設定と互換性も説明します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/intellectronica/agent-skills --skill copilot-sdk

インストール後、Claude Code で/copilot-sdkを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

cli-agents-mcp.md

event-system.md

troubleshooting.md

working-examples.md

詳細

GitHub Copilot SDK

概要

GitHub Copilot SDK は、同じ Copilot CLI エージェントのランタイムを JSON-RPC 経由で公開するため、アプリは独自のオーケストレーションレイヤーを構築せずに、プログラムから Copilot を操作できます。

ステータス： パブリックプレビュー
SDK： Node.js/TypeScript、Python、Go、.NET、Java
アーキテクチャ： アプリケーション -> SDK クライアント -> JSON-RPC -> Copilot CLI

このスキルの使い方

Copilot SDK のサポートを行う際は、次の点に従ってください。

記憶に頼らず、公式ドキュメントのインデックスと各言語の README を優先してください。
共通の動作については、最上位の SDK README と docs/ を信頼できる情報源として扱ってください。
安定性や破壊的変更が重要な場合は、プレビューであることを明示してください。
listModels() による実行時の検出が利用できる場合は、モデルの一覧をハードコードしないでください。
権限、ライフサイクルメソッド、イベント名に関する古い案内に注意してください。

現在の信頼できる情報源

SDK のコアドキュメント

言語別ドキュメント

Copilot CLI と GitHub のドキュメント

レシピとサンプル

重要な情報

認証と前提条件

通常の SDK 使用には GitHub Copilot のサブスクリプションが必要です。
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 認証は、DefaultAzureCredential から有効期間の短いベアラートークンを渡す、ドキュメント化された BYOK パターンとしてサポートされています。

権限

SDK はデフォルトで拒否する権限モデルを採用しています。
実際には、作成／再開フローで次のような明示的な権限ハンドラーを指定してください。
- TypeScript：approveAll
- Python：PermissionHandler.approve_all
- Go：copilot.PermissionHandler.ApproveAll
- .NET：PermissionHandler.ApproveAll
- Java：PermissionHandler.APPROVE_ALL

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

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

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

デフォルトのトランスポートは、SDK が管理する CLI プロセスを使用する stdio です。
cliUrl を使用して、外部のヘッドレス CLI サーバーに接続できます。
現在の外部サーバーのドキュメントでは、次のように記載されています。

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 の共有とユーザーごとの CLI、共有ストレージ、セッションロックを検討します。
Azure Managed Identity - Azure 認証が本来の要件である場合は、静的な API キーの代わりに、有効期間の短いベアラートークンを使用した BYOK を利用します。

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

すべての言語で、同じ考え方を使用します。

クライアントを作成して起動します。
権限ハンドラーを指定してセッションを作成します。
ストリーミングや進捗表示が必要な場合は、send() の前にイベントハンドラーを登録します。
send() または sendAndWait() で送信します。
session.idle または返された最終メッセージを待ちます。
セッションで 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 は、ターン完了を示す信頼できるシグナルです。
イベントシステムには、推論、ツールの進捗、権限、情報要求、サブエージェント、スキルのイベントが追加されています。

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 を参照してください。

添付ファイル、コマンド、インタラクション

セッションでは、ファイル、ディレクトリ、画像を添付して送信できます。
画像入力では、ファイル添付と blob 添付の両方がサポートされます。ビジョン機能はモデルの機能を通じて確認してください。
進行中のメッセージでは、mode: "immediate" で処理を誘導し、mode: "enqueue" でキューに追加できます。
SDK では、カスタムのスラッシュ commands を登録できます。
アプリでは、onUserInputRequest を使ってユーザーの質問に回答できます。
接続先のクライアントが対応している場合は、エリシテーションハンドラーと session.ui を通じて、リッチ UI のプロンプトを利用できます。

テレメトリと可観測性

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

永続化と長時間実行の作業

再開可能なセッションには、安定した sessionId を使用してください。
コンパクションが必要になる可能性のある長時間のワークフローには、infiniteSessions を使用してください。
設定で変更しない限り、セッション状態は ~/.copilot/session-state/ に保存されます。

SDK と 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.content ではなく event.data.* を使用します。
ストリーミング／イベントの購読は、send() の前に設定してください。
呼び出し元が sessionId を指定しない場合、セッションの再開は運用しにくくなります。

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

references/working-examples.md - 現在のスターター例（ツールと再開パターンを含む）
references/event-system.md - イベント名、ライフサイクル、言語アクセスパターン
references/cli-agents-mcp.md - カスタムエージェント、スキル、MCP、ヘッドレス CLI、設定ファイルの場所
references/troubleshooting.md - よくある失敗、デバッグログ、認証、権限、トランスポートの問題

Markdown 対応

ログインしてコメント

基本情報

作者: intellectronica
リポジトリ: intellectronica/agent-skills
カテゴリ: 開発
インストール数: 532
GitHub スター: 298

問題を報告