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]

Microsoft Copilot SDK v2 の既定構成。SDK クライアントと Copilot ランタイムは同じアプリのプロセス内で JSON-RPC を使って通信する。独自ツールはアプリ側で実行し、モデルと MCP サーバーにはランタイムから接続する

図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 を入れる

bash
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 を作ります。

typescript
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);

実行します。

bash
npx tsx index.ts

4 と表示されれば成功です。[^sdk-getting-started]

ここでのポイントは次の 3 つです。

  • mode: クライアントには明示的なモードが必須です。coding-agent は CLI のような使い方向けで、empty はマルチユーザーのサービス向けです。[^sdk-getting-started]
  • セッション: 会話の単位です。モデルやツール、システムメッセージなどをセッションごとに設定します。
  • sendAndWait: 応答が完了するまで待って最終メッセージを返します。

6. 手順 4:ストリーミングで逐次表示する

待ち時間を減らすため、セッション作成時にストリーミングを有効にし、イベントを購読します。

typescript
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:カスタムツールで自分のコードを呼ばせる

エージェントらしさが出るのがツールです。説明、パラメータのスキーマ、ハンドラを渡して登録します。

typescript
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]

  1. Copilot がパラメータ付きでツール呼び出しを要求する
  2. SDK がハンドラを実行する
  3. 結果が Copilot に返される
  4. Copilot が結果を取り込んで応答する

7.2 ツール設計のコツ

  • description は「いつ使うか」が伝わるように書きます。モデルはこの説明とスキーマで呼ぶか判断します。
  • ハンドラ側で引数を必ず検証します。モデルが作った引数は信頼できる入力ではありません。
  • 副作用のある操作(書き込み・外部送信)は、承認を挟む設計にします。

8. 手順 6:システムメッセージとカスタムエージェントで振る舞いを整える

8.1 システムメッセージ

追記形式で、応答の方針を指定できます。

typescript
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 カスタムエージェント

用途別の役割を定義できます。

typescript
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]

typescript
const session = await client.createSession({
  mcp: {
    servers: {
      github: {
        type: "http",
        url: "https://api.githubcopilot.com/mcp/"
      }
    }
  }
});

接続先ごとに認証や承認の要件が異なるため、使うツールの権限は必要最小限に絞ります。

10. 本番運用で押さえる 4 つの注意点

  1. モードの選択: 複数のユーザーやテナントを扱うサーバーでは mode: "empty" を使います。coding-agent はホストのファイルシステムなど周辺機能にアクセスしうるため、共有サーバーには使いません。[^sdk-multi-tenancy]
  2. 認証の分離: ユーザーごとに、セッション単位のトークンや認証プロバイダーを使い、他のユーザーの ID を引き継がせません。[^sdk-multi-tenancy]
  3. 権限の許可: サンプルの approve_all 系(全承認)は学習用です。実運用では、リクエストごとに許可・拒否を判断する処理を書きます。
  4. 名称移行への備え: 旧称の GitHub Copilot SDK と新称が混在する期間です。依存パッケージ名とバージョンを固定し、更新情報を確認します。[^sdk-readme]

11. まとめ

Microsoft Copilot SDK でエージェントを作る流れは、次の 7 ステップです。

  1. SDK を導入する
  2. 認証を整える
  3. 最初のメッセージを送る
  4. ストリーミングを有効にする
  5. カスタムツールを登録する
  6. システムメッセージやカスタムエージェントで振る舞いを整える
  7. MCP サーバーで機能を広げる

オーケストレーションを自前で書かずに、アプリ固有のツールと方針に集中できる点が最大の利点です。まずは最小構成を動かし、次にツールを 1 つ足すところから始めてみてください。

12. 参考情報

[^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)