copilot-sdk

GitHub Copilot SDK

概要

GitHub Copilot SDK は、Copilot のエージェント型ワークフローをアプリケーションに組み込むためのマルチプラットフォーム対応エージェントランタイムです。Copilot CLI と同じエンジンを公開しているため、独自のオーケストレーションを開発することなく、プログラムから呼び出せます。

ステータス： テクニカルプレビュー（開発およびテストに適しています）

対応言語： TypeScript/Node.js、Python、Go、.NET

主なドキュメント

• GitHub Copilot SDK リポジトリ
• スタートガイド
• レシピ付きクックブック

言語別 SDK ドキュメント

• Node.js/TypeScript SDK
• Python SDK
• Go SDK
• .NET SDK

CLI と設定に関するドキュメント

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

---

前提条件

1. GitHub Copilot サブスクリプション - Pro、Pro+、Business、または Enterprise
2. GitHub Copilot CLI - インストール済みで認証済み（copilot --version）
3. ランタイム： Node.js 18 以降、Python 3.8 以降、Go 1.21 以降、または .NET 8.0 以降

インストール

言語	コマンド
TypeScript/Node.js	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

アーキテクチャ

Application → SDK Client → JSON-RPC → Copilot CLI (server mode)

SDK は CLI のライフサイクルを自動的に管理します。cliUrl / cli_url を使用した外部サーバー接続に対応しています。

---

クイックスタート（TypeScript）

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

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

const session = await client.createSession({ model: "gpt-5" });

// Register handler BEFORE send()
session.on((event) => {
  if (event.type === "assistant.message") {
    console.log(event.data.content);
  }
});

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

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

重要： すべてのイベントを取得するため、send() を呼び出す前にイベントハンドラーを登録してください。

すべての言語での完全な例については、references/working-examples.md を参照してください。

---

コアコンセプト

クライアント

主なエントリーポイントです。CLI サーバーのライフサイクルとセッションの作成を管理します。

操作： start()、stop()、createSession()、resumeSession()

設定： cliPath、cliUrl、port、useStdio、autoStart、autoRestart

セッション

メッセージ履歴を含む、個別の会話コンテキストです。

操作： send()、sendAndWait()、on()、abort()、getMessages()、destroy()

設定： model、streaming、tools、systemMessage

イベント

処理中に発生する主なイベント：

イベント	用途
assistant.message	完全な応答
assistant.message_delta	ストリーミングのチャンク
session.idle	次のプロンプトを受け付け可能
tool.execution_start/end	ツールの呼び出し

イベントのライフサイクル全体と SessionEvent の構造については、references/event-system.md を参照してください。

ストリーミング

• streaming: false（デフォルト）- コンテンツは一度にまとめて届きます
• streaming: true - コンテンツは assistant.message_delta を介して段階的に届きます

ストリーミング設定にかかわらず、最終的な assistant.message は必ず発生します。

---

利用可能なモデル

全リストはサポートされている AI モデルをご覧ください。

プロバイダー	モデル ID	備考
OpenAI	gpt-4.1, gpt-5, gpt-5-mini	含まれています
OpenAI	gpt-5.1, gpt-5.1-codex, gpt-5.2	プレミアム
Anthropic	claude-sonnet-4.5	プレミアム（CLI のデフォルト）
Anthropic	claude-opus-4.5	プレミアム（3× の倍率）
Google	gemini-3-pro-preview	プレミアム

---

カスタムツール

TypeScript（Zod）：

const tool = defineTool("lookup_issue", {
  description: "Fetch issue details",
  parameters: z.object({ id: z.string() }),
  handler: async ({ id }) => fetchIssue(id),
});

Python（Pydantic）：

@define_tool(description="Fetch issue details")
async def lookup_issue(params: IssueParams) -> dict:
    return fetch_issue(params.id)

すべての言語でのツールの完全な例については、references/working-examples.mdをご覧ください。

---

言語規約

概念	TypeScript	Python	Go	.NET
セッションの作成	createSession()	create_session()	CreateSession()	CreateSessionAsync()
差分コンテンツ	deltaContent	delta_content	DeltaContent	DeltaContent

規約の全テーブルについては、references/event-system.mdをご覧ください。

---

CLI の設定

設定は~/.copilot/に保存されます：

• config.json - 全般設定
• mcp-config.json - MCP サーバーの定義

カスタムエージェントと MCP のセットアップについては、references/cli-agents-mcp.mdをご覧ください。

---

トラブルシューティング

問題	解決策
イベントは発生するが、コンテンツが空	event.contentではなくevent.data.contentを使用してください
ハンドラーが一度も呼び出されない	send()の前に登録してください
Python の列挙型に関する問題	event.type.valueを使用してください
Go の nil ポインター	デリファレンスする前に!= nilを確認してください

デバッグ手法については、references/troubleshooting.mdをご覧ください。

---

スキルのリファレンス

このスキルの詳細なドキュメント：

• references/working-examples.md - すべての言語とカスタムツールの完全な例
• references/event-system.md - イベントのライフサイクル、SessionEvent の構造、言語規約
• references/troubleshooting.md - よくある問題、デバッグ手法
• references/cli-agents-mcp.md - CLI の設定、カスタムエージェント、MCP サーバーのセットアップ

---

その他のリソース

• SDK のサンプル
• SDK のリリース
• Cookbook
• awesome-copilot