.NETでMicrosoft Agent FrameworkのGitHub Copilot連携を使っている場合、今回のMicrosoft Copilot documentation updateで最初に確認すべき点は、GitHub.Copilot.SDK 0.3.0対応が破壊的変更（BREAKING）として扱われていることです。特に、Microsoft.Agents.AI.GitHub.CopilotとGitHub.Copilot.SDKを組み合わせているプロジェクトでは、型名の変更、OnPermissionRequestの必須化、セッション設定の引き継ぎ範囲を確認しないと、実行時エラーやストリーミング応答の停止につながる可能性があります。
今回の変更は、単なるSDKバージョン更新ではありません。GitHub.Copilot.SDK 0.3.0でGA前のAPI整理が進み、添付ファイル、MCP設定、権限リクエスト、セッション設定まわりの扱いが変わっています。Microsoft CopilotやGitHub Copilot SDKを.NETアプリに組み込んでいる開発者は、依存パッケージの更新前に「自分のコードが影響を受けるか」を切り分けてから移行するのが安全です。(GitHub)
今回のMicrosoft Copilot documentation updateで何が変わったのか
今回の更新は、Microsoft Agent Frameworkの.NET向けGitHub Copilot連携パッケージであるMicrosoft.Agents.AI.GitHub.Copilotを、GitHub.Copilot.SDK 0.3.0に対応させるための変更です。
背景として、既存のMicrosoft.Agents.AI.GitHub.CopilotはGitHub.Copilot.SDK 0.1.29を前提にコンパイルされていました。一方、GitHub.Copilot.SDK 0.3.0ではGAに向けた型名整理や機能追加が行われ、古い型名を参照するコードでは互換性問題が発生します。関連Issueでは、Microsoft.Agents.AI.GitHub.Copilot 1.3.0-preview.260423.1とGitHub.Copilot.SDK 0.3.0の組み合わせで、RunAsyncやRunStreamingAsync実行時にTypeLoadExceptionが発生するケースが報告されています。(GitHub)
Microsoft LearnのGitHub Copilotエージェント資料では、Microsoft Agent FrameworkがGitHub Copilot SDKをバックエンドにしたエージェント作成をサポートし、シェルコマンド、ファイル操作、URLフェッチ、MCPサーバー統合などの機能にアクセスできると説明されています。つまり今回の変更は、単なるドキュメント上の文言修正ではなく、実際にエージェントを実行する.NETアプリの安定性とセキュリティ設計に関わる更新です。(Microsoft Learn)
対応が必要な人、様子見でよい人
まず、自分のプロジェクトが今回のMicrosoft Copilot documentation updateの影響を受けるかを確認しましょう。
| 対象 | 対応の優先度 | 確認すべきこと |
|---|---|---|
.NETでMicrosoft.Agents.AI.GitHub.Copilotを使っている | 高 | GitHub.Copilot.SDKの解決バージョン、RunAsync/RunStreamingAsyncの動作 |
GitHub.Copilot.SDK 0.3.0以上を明示的に参照している | 高 | 型名変更、OnPermissionRequest、GitHubTokenなどの新プロパティ |
| MCPサーバー連携を使っている | 高 | McpLocalServerConfig、McpRemoteServerConfigの名称変更 |
| セッションごとのGitHubトークンを使いたい | 高 | SessionConfig.GitHubTokenが正しく渡されるか |
| Python版のAgent Frameworkだけを使っている | 中 | 今回の.NET PRの直接影響は限定的だが、SDKプレビューのAPI変更には注意 |
| Visual Studio CodeやGitHub上の通常のCopilot補完だけを使っている | 低 | アプリ組み込みSDKの話であり、通常利用への直接影響は限定的 |
特に注意したいのは、アプリ側でGitHub.Copilot.SDK 0.3.0の機能を使いたくて明示的にバージョンを固定しているケースです。0.3.0ではセッション単位のGitHub認証などが追加されており、同じCLIサーバー上の異なるセッションで別々のGitHub ID、Copilotプラン、クォータを扱えるとリリースノートで説明されています。(GitHub)
重要な変更点
GitHub.Copilot.SDKが0.1.29から0.3.0へ更新される
PRでは、Directory.Packages.props内のGitHub.Copilot.SDKを0.1.29から0.3.0へ上げる変更が示されています。これは依存関係の数字が変わるだけではなく、SDKのAPI面に合わせてラッパー側のコードとテストも更新する内容です。(GitHub)
GitHub.Copilot.SDK 0.3.0のリリースでは、セッション単位の認証、スコープ付き権限、エージェント単位のツール・スキル制御、MCP関連ユーティリティなどが追加され、同時に広範な命名整理が行われています。リリース説明でも、GAに近づく過程でAPIの読みやすさと一貫性を高めるための整理だとされています。(GitHub)
開発現場では、次のような点を確認してください。
dotnet list package --include-transitiveこのコマンドで、プロジェクトがどのバージョンのGitHub.Copilot.SDKを解決しているかを確認できます。Microsoft.Agents.AI.GitHub.Copilotを直接参照していなくても、別のパッケージ経由でSDKが入っている場合があります。
型名が変更される
PRで示されている主な型名変更は次の通りです。
| 旧名称 | 新名称 | 影響しやすい箇所 |
|---|---|---|
UserMessageDataAttachmentsItem | UserMessageAttachment | 添付ファイル付きメッセージ |
UserMessageDataAttachmentsItemFile | UserMessageAttachmentFile | ファイル添付 |
McpLocalServerConfig | McpStdioServerConfig | ローカルMCPサーバー設定 |
McpRemoteServerConfig | McpHttpServerConfig | HTTP経由のMCPサーバー設定 |
PermissionRequestResultKindの文字列指定 | enum指定 | 権限リクエストの戻り値処理 |
影響が出やすいのは、SDKの生成型やMCP設定型をアプリ側で直接参照しているコードです。たとえばMCPサーバー連携を行っている場合、古いMcpLocalServerConfigやMcpRemoteServerConfigを使ったコードは、SDK 0.3.0対応後に置き換えが必要になる可能性があります。(GitHub)
Microsoft Learn上の現行ドキュメント例では、MCP設定のサンプルにMcpLocalServerConfigとMcpRemoteServerConfigが登場していますが、今回のPRでは0.3.0対応としてMcpStdioServerConfigとMcpHttpServerConfigへの変更が示されています。実装時は、参照しているパッケージの実際の型定義とドキュメント更新状況を必ず照合してください。(Microsoft Learn)
OnPermissionRequestがセッション作成時に必須になる
今回の更新で最も実務上の影響が大きいのは、OnPermissionRequestの扱いです。
PRでは、SDK 0.3.0ではすべてのCreateSessionAsync呼び出しでOnPermissionRequestが必要になり、指定されていない場合はセッション作成時にSDK側で例外が発生すると説明されています。隠れたデフォルト値を自動注入せず、呼び出し側が明示的に権限ハンドラーを渡す設計です。(GitHub)
これはセキュリティ上は妥当な変更です。GitHub Copilotエージェントは、設定次第でシェルコマンド、ファイル読み書き、URLフェッチ、MCP連携などを扱えます。Microsoft Learnでも、既定ではこれらの操作は実行できず、有効にするにはSessionConfigでアクセス許可ハンドラーを指定すると説明されています。(Microsoft Learn)
実務では、単に「常に許可」にするのではなく、用途に応じて権限ポリシーを分けるのが安全です。
| 利用シーン | 推奨される権限設計 |
|---|---|
| 社内ドキュメントの読み取り支援 | 読み取り系ツールのみ許可 |
| コード生成・修正支援 | 対象ディレクトリを限定し、書き込みは確認制にする |
| CI/CDや自動修正ボット | 破壊的操作、外部通信、秘密情報アクセスを明示的に制限 |
| 検証用ローカル環境 | 許可範囲を広げる場合も、コンテナやDev Container内で実行する |
| 本番運用 | 監査ログ、ユーザー確認、失敗時の停止条件を必ず設ける |
GitHubのCopilot SDKドキュメントでも、フックを使うことでアクセス許可、監査、通知などを実装でき、onPreToolUseで許可リストやディレクトリ制限、破壊的操作前の確認を設計できると説明されています。(GitHub Docs)
影響範囲を確認するチェックリスト
今回のMicrosoft Copilot documentation updateを見て、最初にやるべきことは「すぐ更新する」ではなく「壊れる場所を先に特定する」ことです。以下の順で確認すると、影響範囲を絞り込みやすくなります。
パッケージの解決バージョンを確認する
まず、.csprojと集中管理ファイルを確認します。
<!-- Directory.Packages.props の例 -->
<PackageVersion Include="GitHub.Copilot.SDK" Version="0.3.0" />
<PackageVersion Include="Microsoft.Agents.AI.GitHub.Copilot" Version="..." />次に、実際に解決されているパッケージを確認します。
dotnet restore
dotnet list package --include-transitive見るべきポイントは次の3つです。
GitHub.Copilot.SDKが0.3.0以上になっているかMicrosoft.Agents.AI.GitHub.Copilotのバージョンが0.3.0対応済みか- 直接参照と推移的参照で、意図しないバージョン競合が起きていないか
関連Issueでは、Microsoft.Agents.AI.GitHub.Copilot 1.3.0-preview.260423.1とGitHub.Copilot.SDK 0.3.0の組み合わせで互換性問題が報告されています。該当するバージョンを使っている場合は、プレビュー版だから動くだろうと判断せず、実行テストまで行ってください。(GitHub)
古い型名を検索する
リポジトリ全体で、次の文字列を検索します。
UserMessageDataAttachmentsItem
UserMessageDataAttachmentsItemFile
McpLocalServerConfig
McpRemoteServerConfig
PermissionRequestResultKind
OnPermissionRequest
CreateSessionAsync
RunAsync
RunStreamingAsync検索結果が出た場合は、単純置換ではなく、周辺コードの目的を見て判断します。
たとえばMcpLocalServerConfigをMcpStdioServerConfigに変えるだけでは不十分な場合があります。MCPサーバーの起動コマンド、引数、許可ツール、作業ディレクトリ、権限ハンドラーの関係も一緒に確認する必要があります。
RunAsyncとRunStreamingAsyncを重点的にテストする
今回の互換性問題は、ビルド時ではなく実行時に表面化する可能性があります。関連Issueでは、CLIプロセス自体は正常でも、ラッパー側が古いSDKの型を読み込もうとしてTypeLoadExceptionが発生し、本番環境では応答が返らない、またはストリーミングされない形で見えることがあると報告されています。(GitHub)
最低限、次のテストを用意してください。
| テスト項目 | 確認内容 |
|---|---|
| 通常実行 | RunAsyncで短い応答が返るか |
| ストリーミング | RunStreamingAsyncで途中チャンクが返るか |
| セッション作成 | CreateSessionAsyncでOnPermissionRequest未設定時の挙動を把握しているか |
| MCP連携 | ローカルstdio、HTTPのMCP設定が新しい型で動くか |
| 権限拒否 | ファイル書き込みやシェル実行を拒否したときに安全に停止するか |
| トークン切り替え | GitHubTokenを使う場合、セッション単位で意図した認証になるか |
移行時の実務手順
まず検証ブランチで依存関係を固定する
プレビューSDKの変更は、推移的依存関係によって予期せず取り込まれることがあります。移行時は、検証ブランチで依存関係を明示的に固定しましょう。
git checkout -b verify-copilot-sdk-030
dotnet restore
dotnet list package --include-transitiveNuGetの集中管理を使っている場合は、Directory.Packages.propsでSDKとAgent Framework関連パッケージの組み合わせを見える化しておくと、CIでの再現性が上がります。
OnPermissionRequestを明示的に実装する
もっとも避けたいのは、エラーを消すためだけに全操作を許可することです。検証段階では一時的に全許可に見える実装を使う場合でも、本番では用途別に制限してください。
実装の考え方は次のようになります。
// 実装例のイメージです。実際の型名やenum名は利用中のSDKバージョンに合わせて確認してください。
static Task<PermissionRequestResult> HandlePermissionAsync(
PermissionRequest request,
PermissionInvocation invocation)
{
// 例: まずはログに残す
Console.WriteLine($"Permission request: {request.Kind}");
// 例: 破壊的操作は拒否、読み取り系は許可、判断が必要なものはユーザー確認に回す
// ここはプロジェクトのセキュリティ要件に合わせて実装する
return Task.FromResult(new PermissionRequestResult
{
// SDK 0.3.0では文字列ではなくenum指定になっている箇所があるため、
// 利用中のSDK定義を確認して指定する
});
}Microsoft Learnの例では、SessionConfigにOnPermissionRequestを設定してからAsAIAgent(sessionConfig)でエージェントを作成する流れが示されています。今回の更新では、この権限ハンドラーを「任意」ではなく「セッション作成に必要な設定」として扱う意識が重要です。(Microsoft Learn)
MCP設定の型名と権限を同時に見直す
MCPサーバーを使っている場合、型名変更だけでなくアクセス範囲も見直してください。
旧設定の考え方では「ローカルMCP」「リモートMCP」と呼ばれていたものが、0.3.0対応ではstdioとHTTPの実態に近い命名へ整理されています。これは読みやすくなる一方で、既存コードではコンパイルエラーや実行時エラーの原因になります。
確認すべき点は次の通りです。
| 確認項目 | 見落としやすいポイント |
|---|---|
| MCP設定型 | 旧型名が残っていないか |
| サーバー種別 | stdioなのかHTTPなのか |
| コマンド・引数 | npxなど外部コマンド実行が必要か |
| 許可ツール | Tools = ["*"]のように広く許可していないか |
| 実行環境 | ホストOS直下ではなくコンテナで隔離できるか |
| ログ | どのツールがどの引数で呼ばれたか追跡できるか |
Microsoft Learnでも、GitHub Copilotエージェントをシェルやファイルアクセス権限付きで動かす場合は、セキュリティのためDockerやDev Containerなどのコンテナー化された環境で実行することが推奨されています。(Microsoft Learn)
セッション設定の引き継ぎ漏れを確認する
PRでは、CopySessionConfigとCopyResumeSessionConfigを通じて、SDK 0.3.0で追加・重要化された複数のセッション設定を転送する変更が示されています。対象には、SessionId、ClientName、ModelCapabilities、EnableConfigDiscovery、IncludeSubAgentStreamingEvents、DefaultAgent、Agent、OnElicitationRequest、OnEvent、CreateSessionFsHandler、Commands、GitHubTokenなどが含まれます。(GitHub)
この変更は、セッションを再開するアプリや、ユーザーごとに認証情報を切り替えるアプリで特に重要です。GitHubのセッション永続化ドキュメントでは、セッション作成時にsessionIdを与えることで、再起動やクライアント移行後にセッションを再開できると説明されています。(GitHub Docs)
次のようなアプリでは、セッション設定の引き継ぎ漏れが不具合につながります。
- WebアプリでユーザーごとにCopilotセッションを分ける
- Azure Container Appsなどのコンテナ環境でセッションを再開する
- サブエージェントのストリーミングイベントをUIに表示する
- 独自コマンドを
Commandsとして渡している GitHubTokenをセッション単位で切り替える- 監査や通知のために
OnEventやフックを使う
よくある失敗と回避策
ビルドが通ったので安全だと思い込む
今回のようなSDK互換性問題では、ビルドが通っても実行時に失敗することがあります。特に、古いSDKの型を前提にコンパイルされたラッパーと、新しいSDKが実行時に組み合わさると、TypeLoadExceptionのような形で表面化します。
回避策は、CIに「実際にCopilotセッションを作成して1回実行するテスト」を入れることです。単体テストだけでなく、RunAsyncとRunStreamingAsyncの両方を最低1ケースずつ確認してください。
OnPermissionRequestを全許可にして本番投入する
OnPermissionRequestが必須になると、開発者はとりあえず全許可のハンドラーで通したくなります。しかし、GitHub Copilotエージェントはファイル操作やシェル実行と組み合わさるため、全許可は本番運用では危険です。
安全に始めるなら、最初は次のようなポリシーにします。
| 操作 | 初期ポリシー |
|---|---|
| ファイル読み取り | 対象ディレクトリ内のみ許可 |
| ファイル書き込み | ユーザー確認後に許可 |
| ファイル削除 | 原則拒否 |
| シェル実行 | 検証環境のみ許可 |
| 外部URLアクセス | 許可ドメインを限定 |
| MCPツール | 用途ごとに許可リスト化 |
GitHubのフック解説でも、読み取り専用ツールの許可リスト、特定ディレクトリへのファイルアクセス制限、破壊的操作前の確認といった設計例が示されています。(GitHub Docs)
ドキュメント例と実パッケージの差分を見落とす
プレビュー段階のSDKやドキュメントでは、PR、Issue、リリースノート、Microsoft Learnの反映タイミングがずれることがあります。今回も、PRではMCP設定型の新名称が示されている一方で、参照タイミングによってはドキュメント例に旧名称が残っている可能性があります。
移行時は、次の順で確認すると安全です。
- 実際に参照しているNuGetパッケージの型定義
- GitHub Copilot SDKのリリースノート
- Microsoft Agent FrameworkのPRまたはIssue
- Microsoft Learnのサンプルコード
- 自社コードのテスト結果
「公式ドキュメントに載っているから正しい」と判断するのではなく、プレビューSDKでは実際のパッケージ定義と照合することが重要です。
移行前に決めておきたい運用ルール
今回の変更は、単にエラーを直すだけでなく、Copilotエージェントを安全に運用するための設計を見直す良い機会です。
権限リクエストの判断基準をコード化する
OnPermissionRequestは、ユーザーに毎回質問するだけの仕組みではありません。どの操作を自動許可し、どの操作を拒否し、どの操作を人間に確認するかをルール化する場所です。
おすすめは、権限判断をアプリ本体の処理に埋め込まず、専用クラスやポリシーとして分離することです。
PermissionPolicy
├─ 読み取り操作の許可条件
├─ 書き込み操作の許可条件
├─ シェル実行の許可条件
├─ MCPツールの許可条件
└─ 監査ログの出力条件こうしておくと、SDK更新時に権限まわりの差分をテストしやすくなります。
セッション単位のGitHubTokenを使うならログ設計も見直す
GitHub.Copilot.SDK 0.3.0では、セッション単位のGitHub認証が新機能として説明されています。同じCLIサーバー上で異なるセッションが別々のGitHubユーザー、Copilotプラン、クォータを持てるため、マルチユーザーアプリでは便利です。(GitHub)
一方で、運用上は「誰のトークンで、どのセッションが、どの操作をしたか」を追跡できる必要があります。ログにはトークンそのものを出してはいけませんが、ユーザーID、セッションID、操作種別、権限判断、エラー種別は記録しておくべきです。
プレビューSDKは更新タイミングを管理する
GitHub Copilot SDKのドキュメントでは、Copilot SDKはパブリックプレビューであり、機能と可用性は変更される可能性があると明記されています。(GitHub Docs)
そのため、開発チームでは次のルールを決めておくと混乱を減らせます。
| ルール | 目的 |
|---|---|
| SDK更新は検証ブランチで行う | 本番ブランチへの偶発的な破壊的変更を防ぐ |
| パッケージバージョンを明示固定する | 推移的依存の変化による再現不能な不具合を防ぐ |
| Copilot関連のE2Eテストを用意する | 実行時エラーを早期発見する |
| 権限ポリシーをテスト対象にする | セキュリティ退行を防ぐ |
| リリースノートとPRをセットで確認する | ドキュメント反映前の差分を把握する |
まず実行すべき対応まとめ
今回のMicrosoft Copilot documentation updateで確認すべきポイントは、GitHub.Copilot.SDK 0.3.0への対応、型名変更、OnPermissionRequestの必須化、セッション設定の転送範囲です。特に.NETでMicrosoft.Agents.AI.GitHub.Copilotを使い、RunAsyncやRunStreamingAsyncを利用しているプロジェクトは、依存関係の組み合わせによって実行時エラーが起きる可能性があります。
最初に行うべき作業は、次の3つです。
dotnet list package --include-transitiveでGitHub.Copilot.SDKの解決バージョンを確認する- 旧型名と
OnPermissionRequest未設定のコードを検索する RunAsync、RunStreamingAsync、MCP連携、権限拒否のテストを検証環境で実行する
そのうえで、SDK 0.3.0に移行する場合は、OnPermissionRequestを単なる必須パラメーターとしてではなく、Copilotエージェントの安全性を左右する権限ポリシーとして設計してください。プレビュー段階のSDKでは変更が続く可能性があるため、パッケージ固定、E2Eテスト、監査ログ、コンテナ実行をセットで整備してから本番適用するのが現実的です。
コメント