1. はじめに
LLM を使ったエージェントを自作すると、計画、ツール選択、実行結果の取り込み、ファイル操作といったオーケストレーションを自前で書くことになります。Microsoft Copilot SDK は、Copilot CLI と同じエンジンをプログラムから呼び出せるようにし、この部分を肩代わりします。[^sdk-readme]
本記事の目的は、このSDK でエージェントを作る流れを、手を動かせる順番で整理することです。言語は TypeScript を選びましたが、SDK は Python・Go・.NET・Java・Rust にも提供されており、基本の流れは共通です。
注意: 本記事のコードは公式の Getting Started を基に構成しており、筆者環境での実行確認は未実施です。パッケージ名や API は移行期間中に変わる可能性があるため、実施時に公式資料を確認してください。
1.1 名称変更について
公式 README によると、GitHub Copilot SDK は、Microsoft と GitHub の製品で共有されるエージェント基盤「Microsoft Copilot harness」のプログラム用インターフェースとして、Microsoft Copilot SDK へ移行中です。リポジトリも段階的に Microsoft 組織へ移り、既存のパッケージ名や名前空間、一部の文書には旧称が残る場合があります。既存ユーザーに即時の変更は不要とされています。[^sdk-readme]
2. 全体像と前提
2.1 アーキテクチャ
すべての SDK は、Copilot のエージェントランタイムと JSON-RPC で通信します。v2 の既定では、ネイティブのランタイムをアプリのプロセス内に読み込み、メモリ上の接続で通信します。別プロセスとして起動するなど、プロセス外で動かす構成も選べます。[^sdk-readme]
図1 SDK とランタイムの関係
独自ツールは SDK がアプリ側のハンドラを呼び出して実行します。MCP サーバーを設定した場合は、ランタイムからサーバーに接続します。[^sdk-getting-started]
プロセス内ホスティングには、クラッシュの分離もサンドボックスもありません。ランタイムのクラッシュがアプリに波及しないようにするには、別プロセスで動かす構成を検討します。[^sdk-readme]
2.2 前提条件
- Node.js
^20.19.0または>=22.12.0[^sdk-nodejs] - 認証手段:GitHub のトークン、サインイン済みの CLI 資格情報、または BYOK(自分のモデル用キー)のいずれか[^sdk-getting-started]
- Copilot CLI の別途インストールは不要です。Node.js 版にはプラットフォーム別のランタイムが同梱されます。[^sdk-getting-started]
3. 手順 1:プロジェクトを作って SDK を入れる
mkdir copilot-demo && cd copilot-demo
npm init -y --init-type module
npm install @microsoft/copilot-sdk tsx
tsx は TypeScript ファイルをそのまま実行するために使います。[^sdk-getting-started]
4. 手順 2:認証を整える
認証方式は用途で選びます。[^sdk-auth]
| 方式 | 向いている用途 | Copilot 契約 |
|---|---|---|
| GitHub サインイン済みユーザー | 対話的なアプリ | 必要 |
| GitHub OAuth アプリ | ユーザーに代わって動くアプリ | 必要 |
| 環境変数 | CI/CD、自動化、サーバー間連携 | 必要 |
| サーバー間認証 | 組織に紐づく自動化と組織への直接課金 | 利用者個別には不要 |
| BYOK(Microsoft Foundry など) | 自分の API キーを使う | 不要 |
手元で試すだけなら、Copilot CLI で一度 copilot login してサインインしておくのが最も簡単です。SDK は保存された資格情報を自動的に使います。[^sdk-auth]
5. 手順 3:最初のメッセージを送る
index.ts を作ります。
import { CopilotClient } from "@microsoft/copilot-sdk";
const client = new CopilotClient({ mode: "coding-agent" });
const session = await client.createSession({ model: "auto" });
const response = await session.sendAndWait({ prompt: "What is 2 + 2?" });
console.log(response?.data.content);
await client.stop();
process.exit(0);
実行します。
npx tsx index.ts
4 と表示されれば成功です。[^sdk-getting-started]
ここでのポイントは次の 3 つです。
mode: クライアントには明示的なモードが必須です。coding-agentは CLI のような使い方向けで、emptyはマルチユーザーのサービス向けです。[^sdk-getting-started]- セッション: 会話の単位です。モデルやツール、システムメッセージなどをセッションごとに設定します。
sendAndWait: 応答が完了するまで待って最終メッセージを返します。
6. 手順 4:ストリーミングで逐次表示する
待ち時間を減らすため、セッション作成時にストリーミングを有効にし、イベントを購読します。
import { CopilotClient } from "@microsoft/copilot-sdk";
const client = new CopilotClient({ mode: "coding-agent" });
const session = await client.createSession({
model: "auto",
events: { streaming: true }
});
session.on("assistant.message_delta", (event) => {
process.stdout.write(event.data.deltaContent);
});
session.on("session.idle", () => {
console.log();
});
await session.sendAndWait({ prompt: "Tell me a short joke" });
await client.stop();
process.exit(0);
on(handler) は全イベントを、on(eventType, handler) は特定のイベントだけを購読し、どちらも購読解除用の関数を返します(イベント種別を指定する形式は Node.js / TypeScript のみ)。[^sdk-getting-started]
7. 手順 5:カスタムツールで自分のコードを呼ばせる
エージェントらしさが出るのがツールです。説明、パラメータのスキーマ、ハンドラを渡して登録します。
import { CopilotClient, defineTool } from "@microsoft/copilot-sdk";
const getWeather = defineTool("get_weather", {
description: "Get the current weather for a city",
parameters: {
type: "object",
properties: {
city: { type: "string", description: "The city name" }
},
required: ["city"]
},
handler: async (args: { city: string }) => {
// 実際のアプリでは天気 API を呼ぶ
return { city: args.city, temperature: "20°C", condition: "sunny" };
}
});
const client = new CopilotClient({ mode: "coding-agent" });
const session = await client.createSession({
model: "auto",
events: { streaming: true },
tools: { definitions: [getWeather] }
});
session.on("assistant.message_delta", (event) => {
process.stdout.write(event.data.deltaContent);
});
await session.sendAndWait({
prompt: "What's the weather like in Seattle and Tokyo?"
});
await client.stop();
process.exit(0);
公式ガイドのサンプルは天気をランダム生成するダミー実装です。ここでは固定値に置き換えています。[^sdk-getting-started]
7.1 ツール呼び出しの流れ
Copilot はユーザーの質問に応じて、ツールを呼ぶかを判断します。呼ぶときは次の順に進みます。[^sdk-getting-started]
- Copilot がパラメータ付きでツール呼び出しを要求する
- SDK がハンドラを実行する
- 結果が Copilot に返される
- Copilot が結果を取り込んで応答する
7.2 ツール設計のコツ
descriptionは「いつ使うか」が伝わるように書きます。モデルはこの説明とスキーマで呼ぶか判断します。- ハンドラ側で引数を必ず検証します。モデルが作った引数は信頼できる入力ではありません。
- 副作用のある操作(書き込み・外部送信)は、承認を挟む設計にします。
8. 手順 6:システムメッセージとカスタムエージェントで振る舞いを整える
8.1 システムメッセージ
追記形式で、応答の方針を指定できます。
const session = await client.createSession({
systemMessage: {
content: "You are a helpful assistant for our engineering team. Always be concise."
}
});
さらに細かく調整するなら mode: "customize" を使い、システムプロンプトの節(tone、guidelines など)ごとに replace・remove・append・prepend・preserve を指定できます。[^sdk-getting-started]
8.2 カスタムエージェント
用途別の役割を定義できます。
const session = await client.createSession({
agents: {
definitions: [
{
name: "pr-reviewer",
displayName: "PR Reviewer",
description: "Reviews pull requests for best practices",
prompt:
"You are an expert code reviewer. Focus on security, performance, and maintainability."
}
]
}
});
セッション設定の agent に名前を指定すると、最初から選択した状態で始められます。[^sdk-getting-started]
9. 手順 7:MCP サーバーに接続する
既製のツールは MCP(Model Context Protocol)サーバー経由で追加できます。公式ガイドでは、GitHub の MCP サーバーへの接続が例示されています。[^sdk-getting-started]
const session = await client.createSession({
mcp: {
servers: {
github: {
type: "http",
url: "https://api.githubcopilot.com/mcp/"
}
}
}
});
接続先ごとに認証や承認の要件が異なるため、使うツールの権限は必要最小限に絞ります。
10. 本番運用で押さえる 4 つの注意点
- モードの選択: 複数のユーザーやテナントを扱うサーバーでは
mode: "empty"を使います。coding-agentはホストのファイルシステムなど周辺機能にアクセスしうるため、共有サーバーには使いません。[^sdk-multi-tenancy] - 認証の分離: ユーザーごとに、セッション単位のトークンや認証プロバイダーを使い、他のユーザーの ID を引き継がせません。[^sdk-multi-tenancy]
- 権限の許可: サンプルの
approve_all系(全承認)は学習用です。実運用では、リクエストごとに許可・拒否を判断する処理を書きます。 - 名称移行への備え: 旧称の
GitHub Copilot SDKと新称が混在する期間です。依存パッケージ名とバージョンを固定し、更新情報を確認します。[^sdk-readme]
11. まとめ
Microsoft Copilot SDK でエージェントを作る流れは、次の 7 ステップです。
- SDK を導入する
- 認証を整える
- 最初のメッセージを送る
- ストリーミングを有効にする
- カスタムツールを登録する
- システムメッセージやカスタムエージェントで振る舞いを整える
- MCP サーバーで機能を広げる
オーケストレーションを自前で書かずに、アプリ固有のツールと方針に集中できる点が最大の利点です。まずは最小構成を動かし、次にツールを 1 つ足すところから始めてみてください。
12. 参考情報
- Microsoft Copilot SDK README — 概要、対応言語、アーキテクチャ、名称移行の案内
- Build your first Copilot-powered app — 本記事の手順の元となる公式チュートリアル
- Authentication — 認証方式の比較と設定方法
- Multi-tenancy and server deployments — マルチユーザー運用の指針
- 2026-06-09-claude-api-vs-copilot-sdk.md — Claude API との使い分けを整理した関連記事
[^sdk-readme]: Microsoft Copilot SDK README — GitHub(確認日: 2026-11-20)
[^sdk-getting-started]: Build your first Copilot-powered app — GitHub(確認日: 2026-11-20)
[^sdk-nodejs]: Copilot SDK for Node.js/TypeScript — GitHub(確認日: 2026-11-20)
[^sdk-auth]: Authentication — GitHub(確認日: 2026-11-20)
[^sdk-multi-tenancy]: Multi-tenancy and server deployments — GitHub(確認日: 2026-11-20)






