GitHub Copilot SDK とは

  • 8 分

GitHub Copilot SDK は、AI エージェント ランタイムを独自のアプリケーションに埋め込むことができるマルチプラットフォーム ツールキット (現在 Technical Preview 段階) です。 SDK は、GitHub Copilot CLI の背後にある同じエンジンをプログラミング可能なインターフェイスとして公開し、アプリで自然言語の命令を理解し、アクションを計画し、ツールを呼び出してそれらの指示を満たすことができます。 すべてのインフラストラクチャを最初から構築する必要はありません。

なぜAIエージェントにSDKを使用するのか

一からフル機能の AI エージェントを構築するのは複雑です。 会話状態の管理を順番に処理し、どの外部 API を呼び出すかを決定し、AI の応答が境界内に留まるようにし、さまざまなタスクに対して複数の AI モデルを管理し、安全対策を実装する必要があります。 エージェントワークフローをゼロから構築することは、ビジネスロジックに到達する前に基本的にミニプラットフォームを構築したことを意味します。

GitHub Copilot SDK は、事前構築済みの実稼働テスト済みエージェント エンジンを提供することで、その複雑さを排除します。 SDK は、認証、モデル管理、チャット セッション、ストリーミングを処理します。 これらの構成要素 (ドメイン固有のツールとビジネス ロジック) の上に構築されるものに焦点を当てます。

アーキテクチャの概要

GitHub Copilot SDK は、ローカル プロセスとしてサーバー モードで実行される GitHub Copilot CLI と通信します。 SDK は、CLI プロセスのライフサイクルを自動的に管理します。 すべての SDK 言語で、この同じアーキテクチャが共有されます。

アーキテクチャは、次のフローに従います。

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

選択したプログラミング言語のクライアント ライブラリを使用して SDK と対話します。 SDK は通信プロトコルを処理するため、生メッセージではなく単純なメソッド呼び出しを処理します。

言語のサポート

SDK には、次の 4 つのプログラミング言語用の慣用ライブラリが用意されています。

Language パッケージ
Node.js (TypeScript) npm install @github/copilot-sdk
Python pip install github-copilot-sdk
Go go get github.com/github/copilot-sdk/go
.NET (C#) dotnet add package GitHub.Copilot.SDK

TypeScript で Web アプリケーションを構築する場合でも、C# でバックエンド サービスを構築する場合でも、同じ AI エージェント機能を組み込むことができます。

主要な機能

SDK には、AI エージェントの構築を簡略化するいくつかの組み込み機能が用意されています。

プロダクショングレードのエージェントループ

SDK は、GitHub Copilot CLI を実行するのと同じ実証済みの実行ループを提供します。 この実行ループは、複数ターンの会話を管理し、ツールを呼び出し、タスクが完了するまで反復処理します。 計画とオーケストレーションのロジックをコーディングする必要はありません。

ツールの調整と管理

AI エージェントが推論プロセス中に必要に応じて呼び出すカスタム ツールを定義できます。 ツール ( lookupCustomer(id) など) を登録すると、エージェントの AI モデルで呼び出すタイミングを決定できます。 SDK は配線を処理するため、AI はコードを推測するのではなく、ランタイム内の実際の関数呼び出しを介して構造化された方法でツールを呼び出すことができます。

.NET では、ツールはAIFunctionFactory パッケージのMicrosoft.Extensions.AIを使用して定義されます。 各ツールには、名前、説明、パラメーター スキーマ、ハンドラー関数が含まれています。

マルチモデルの柔軟性

SDK は 1 つの AI モデルに関連付けられません。 複数の AI モデルをサポートし、動的なモデル ルーティングを可能にします。 たとえば、単純なタスクに対してより高速なモデルを使用し、複雑な推論のためのより高度なモデルを同じアプリケーション内で使用できます。

リアルタイム ストリーミング

SDK はストリーミング応答をサポートしています。つまり、AI によって出力が生成されると、それをアプリにストリーミングできます。 たとえば、トークンをストリーミングして、チャット UI で入力インジケーターまたは部分的な回答を表示できます。 この動作により、エクスペリエンスの対話型性と応答性が向上します。

認証とセキュリティ

SDK では、複数の認証方法がサポートされています。

  • GitHub サインイン ユーザー: Copilot CLI ログインから格納されている OAuth 資格情報を再利用します。
  • OAuth GitHub アプリ: GitHub OAuth アプリからユーザー トークンを渡します。
  • 環境変数: COPILOT_GITHUB_TOKEN、 GH_TOKEN、または GITHUB_TOKENを使用します。
  • Bring Your Own Key (BYOK):GitHub 認証を必要とせずに、OpenAI、Azure AI Foundry、Anthropic などのプロバイダーに独自の API キーを使用します。

BYOK オプションを使用しない限り、GitHub Copilot サブスクリプションが必要です。

コンテキスト管理

SDK は、セッション内の会話履歴を自動的に管理します。 以前のメッセージとツールの出力を追跡するため、AI モデルには、一貫性のある複数ターンの対話に必要なコンテキストがあります。 長いセッションの場合、SDK は、コンテキスト ウィンドウが制限に近づくとコンテキストを自動的に圧縮し、トークン オーバーフロー エラーを防ぐ 無限セッション 機能を提供します。

主要な概念

SDK の主要な概念を理解することは、SDK を効果的に操作するのに役立ちます。

Client

CopilotClient クラスは、Copilot CLI サーバーへの接続を管理します。 アプリケーション用に 1 つのクライアント インスタンスを作成し、それを使用してセッションを作成します。 クライアントは、CLI プロセスの開始と停止、通信チャネルの確立、セッションライフサイクルの管理を処理します。

構成オプションには、 AutoStart (最初のセッションの作成時に CLI サーバーを自動的に起動する)、 LogLevel (ログの詳細度を制御)、 CliPath (CLI 実行可能ファイルへのカスタム パスを指定します)、 GithubToken (環境変数や CLI ログインに依存するのではなく、GitHub トークンを直接提供する) があります。

Session

CopilotSessionは、1 つの会話またはタスク コンテキストを表します。 各セッションには、独自の会話履歴、モデル構成、ツール定義、およびシステム プロンプトがあります。 CreateSessionAsyncを使用してクライアントからセッションを作成し、メッセージを送信し、イベント ドリブン モデルを介して応答を受信します。

キー セッションの構成オプションは次のとおりです。

  • モデル: 使用する AI モデル (たとえば、 gpt-4.1)。
  • SystemMessage: SystemMessageConfig (Append または Replace) とMode文字列を持つContent オブジェクトを使用して、エージェントのロールと動作を定義します。
  • ツール: エージェントが呼び出すことができるカスタム ツール定義。
  • InfiniteSessions: InfiniteSessionConfig オブジェクトを介してコンテキストの自動圧縮を制御します。 有効にすると、 BackgroundCompactionThreshold (バックグラウンド圧縮をトリガーするコンテキスト ウィンドウの使用率) と BufferExhaustionThreshold (SDK がトークン オーバーフローを防ぐために圧縮を強制する割合) を構成できます。

Tools

ツールはセッションに登録する関数であるため、AI エージェントは推論中に呼び出すことができます。 各ツールには、名前、説明、パラメーター、ハンドラー関数があります。 AI モデルがツールの使用を決定すると、SDK は要求をインターセプトし、ハンドラーを呼び出し、さらに推論するために結果をモデルに送り返します。

.NET では、AIFunctionFactory.CreateのMicrosoft.Extensions.AIを使用してツールを定義します。

AIFunctionFactory.Create(
    async ([Description("The order ID number")] int orderId) =>
        await GetOrderDetailsAsync(orderId),
    "get_order_details",
    "Look up the status and details of a specific order.")

イベント

SDK では、イベントドリブン通信モデルが使用されます。 セッションにメッセージを送信すると、処理が進行する中で SDK がイベントをトリガーします。

  • AssistantMessageEvent: AI モデルによって完全な応答が生成されました。
  • AssistantMessageDeltaEvent: AI モデルは、ストリーミング中に部分的な応答トークンを生成しました。 Data.DeltaContent プロパティには、リアルタイムで表示できる増分テキストが含まれています。
  • SessionIdleEvent: セッションが完了した処理 (ツール呼び出しを含む)。
  • SessionErrorEvent: 処理中にエラーが発生しました。
  • ToolExecutionStartEvent と ToolExecutionCompleteEvent: ツールが呼び出されました。

これらのイベントをサブスクライブして、エージェントの応答をキャプチャし、エラーを処理します。 非ストリーミング シナリオの場合は、 AssistantMessageEvent を使用して完全な応答を収集します。 ストリーミング シナリオ (チャット UI に入力インジケーターを表示するなど) の場合は、 AssistantMessageDeltaEvent を使用してトークンを到着時にレンダリングします。

セッション フック

SDK には、キー ポイントでエージェントの動作をインターセプトして変更できるフックが用意されています。

  • OnPreToolUse: 実行前にツール呼び出しをインターセプトします。 ハンドラーは PermissionDecision 値を返します。続行Allow 、呼び出しをブロックする Deny 、またはユーザーに確認を求める Ask 。
  • OnPostToolUse: 実行後にツールの結果を処理します。モデルに到達する前に結果をログに記録したり変更したりするのに役立ちます。
  • OnUserPromptSubmitted: 処理前にユーザー プロンプトをインターセプトして変更します。
  • OnErrorOccurred: ErrorHandling 値を返してエラーを処理します。Retry 操作を再試行 Skip 、結果なしで続行するか、処理を停止 Abort 。
  • OnSessionStart: セッションの開始時に実行され、初期化タスクに役立ちます。
  • OnSessionEnd: セッションの終了時に実行され、クリーンアップやログ記録に役立ちます。

これらのフックを使用すると、アクセス許可の制御、ログ記録、および安全ガードレールを実装できます。

.NET 開発の前提条件

.NET アプリケーションで GitHub Copilot SDK を使用するには、環境に次のものが必要です。

  • .NET 8.0 以降。
  • GitHub Copilot CLI がインストールされ、システム PATH で使用できます。
  • アクティブな Copilot サブスクリプション (または BYOK 用の独自の API キー) を持つ GitHub アカウント。
  • GitHub.Copilot.SDK NuGet パッケージ。
  • Microsoft.Extensions.AI NuGet パッケージ (AIFunctionFactory を使用してツールを定義する場合)。

概要

GitHub Copilot SDK は、アプリケーションで AI エージェントを構築するための、実稼働対応の強力なプラットフォームを提供します。 エージェントのオーケストレーション、ツール統合、コンテキスト管理の複雑さを取り除くことで、SDK を使用すると、エージェントの機能とビジネス ロジックの定義に集中できます。 複数の言語、リアルタイム ストリーミング、柔軟な認証オプションをサポートする GitHub Copilot SDK は、さまざまなアプリケーションに AI エージェント機能を追加するための汎用性の高い選択肢です。