.NET documentation update: .NET: Feat/dotnet shell tool は、単なるドキュメント修正ではなく、Microsoft Agent Framework for .NET に「エージェントがシェルコマンドを実行するための仕組み」を追加するPRです。結論から言うと、Agent Frameworkで.NET製AIエージェントを開発している人は、マージ後すぐ使い始める前に、実行権限・承認フロー・Docker隔離・タイムアウト・永続セッションの扱いを確認すべきです。
特に注意したいのは、ここでいう「dotnet shell tool」が通常の dotnet CLIコマンドではなく、AIエージェントがローカルまたはコンテナ内でシェルを実行するためのツール群を指している点です。PR #5604 は2026年5月5日に複数のレビュー対応コミットが追加され、その後もレビューが続いているため、導入判断では「機能が追加されたか」だけでなく「最終的なAPI名や安全設定が確定しているか」まで見る必要があります。(GitHub)
.NETのshell tool更新で何が変わるのか
今回の変更は、Microsoft Agent Frameworkの.NET側に、シェルコマンド実行用の新しいコンポーネントを追加するものです。GitHub上のPR概要では、エージェントがローカルシェルまたは強化されたDockerコンテナ内でコマンドを実行できるようにする変更として説明されています。(GitHub)
Microsoft Agent Frameworkでは、ツールによってエージェントが外部システムとの対話、コード実行、データ検索などを行えるとされています。今回のshell toolは、その中でも「OSコマンドを実行する」という強い権限を持つ領域に関わるため、通常の関数ツールよりも運用設計の重要度が高くなります。(Microsoft Learn)
主な変更点は次のとおりです。
| 確認項目 | 変更内容 | 実務上の意味 |
|---|---|---|
| 新しいシェル実行コンポーネント | Microsoft.Agents.AI.Tools.Shell 配下にシェル実行関連のコードが追加 | Agent Frameworkの.NETアプリからシェル実行をツールとして組み込める可能性がある |
| ローカル実行 | 最新差分では LocalShellExecutor がローカルマシン上のPowerShell、bash、shなどを使う構成 | ホストOS上で直接コマンドが動くため、承認やポリシー設定が必須 |
| Docker実行 | DockerShellExecutor がコンテナ内でコマンドを実行 | ネットワークなし、非root、読み取り専用rootなどの初期設定を使えるが、完全な安全保証ではない |
| 実行モード | StatelessとPersistentを選択可能 | 1回ごとに新しいシェルを使うか、同じシェル状態を維持するかを選ぶ |
| ポリシー制御 | ShellPolicy による許可・拒否パターン | 危険なコマンドの抑止に使えるが、セキュリティ境界として過信しない |
| 実行結果 | stdout、stderr、exit code、タイムアウト、出力切り詰めを返す | エージェントが実行結果をもとに次の判断をしやすくなる |
| 環境情報の注入 | ShellEnvironmentProvider がOS、シェル種類、CLIバージョンなどをプロンプトに反映 | Windowsでbash構文を出す、POSIXでPowerShell構文を出すといった失敗を減らせる |
PRのファイル一覧には、LocalShellExecutor.cs、DockerShellExecutor.cs、ShellPolicy.cs、ShellSession.cs、ShellEnvironmentProvider.cs、テストプロジェクト、サンプルが含まれており、単なる説明文の追加ではなく、実装・テスト・サンプルを含む機能追加であることが分かります。(GitHub)
まず対応すべき人、すぐには影響しない人
今回の.NET documentation updateは、すべての.NET開発者に即時対応を求めるものではありません。影響が大きいのは、Microsoft Agent FrameworkでAIエージェントを作り、ツール呼び出しやコード実行に関心があるチームです。
| 対象者 | 対応優先度 | 確認すべきこと |
|---|---|---|
| Agent Framework for .NETでエージェントを開発している | 高 | PRのマージ状況、パッケージ公開状況、API名、サンプルの更新 |
| AIエージェントにファイル操作、CLI実行、ビルド、テスト実行を任せたい | 高 | ローカル実行ではなくDocker隔離を使うべきか、承認を必須にするか |
| CI/CDや社内ツールにAIエージェントを組み込みたい | 高 | 実行ユーザー、作業ディレクトリ、環境変数、ネットワーク制限、ログ保全 |
| Python側のshell tool相当機能との互換性を見ている | 中 | .NET版のAPI名、既定値、永続セッションの差分 |
| 通常のASP.NET Core、Blazor、コンソールアプリだけを作っている | 低 | Agent Frameworkを使っていなければ直接影響は小さい |
実務では、「使えるようになったから有効化する」ではなく、「AIにどの範囲まで実行権限を渡すか」を先に決めるべきです。Agent Frameworkの公式ドキュメントでも、サードパーティシステムやコードなどを扱うアプリケーションでは、データ共有、品質、信頼性、セキュリティを利用者側で慎重に確認する必要があると説明されています。(Microsoft Learn)
2026年5月5日の更新で特に見るべきポイント
2026年5月5日のコミットでは、shell toolの中でも「出力の扱い」「環境プローブ」「重複検知」など、実運用で地味に効く修正が入っています。PRのコミット一覧では、5月5日にround 7、round 8、round 9のレビュー対応が追加されています。(GitHub)
UTF-8ベースの出力制限に変わった点
5月5日のround 7では、HeadTailBuffer がUTF-16文字数ではなくUTF-8バイト数で出力制限を扱うように変更されています。これにより、日本語や絵文字のようなマルチバイト文字を含む出力で、上限を超えたり、不正なサロゲートペアが発生したりする問題を避けやすくなります。(GitHub)
これは日本語環境では重要です。たとえば、AIエージェントに dotnet test や git log を実行させたとき、テスト名、エラーメッセージ、コミットメッセージに日本語が含まれることがあります。出力上限が「文字数」基準のつもりで「バイト数」契約になっていると、ログの途中で不自然に壊れる可能性があります。
確認すべき観点は次のとおりです。
| 確認項目 | 推奨アクション |
|---|---|
| 日本語ログを扱うか | 日本語を含むstdout、stderrで切り詰め結果を確認する |
| 長大なビルドログを扱うか | MaxOutputBytes の既定値で十分か検証する |
| エージェントに要約させるか | headとtailだけで判断できるプロンプト設計にする |
| 機密情報が出る可能性があるか | 出力制限だけに頼らず、ログマスクやコマンド制限を入れる |
ShellEnvironmentProviderの失敗回復
同じく5月5日のround 7では、ShellEnvironmentProvider の初回プローブが失敗した場合に、失敗したタスクがキャッシュされ続ける問題への対応が入っています。以前の状態では、最初のプローブ失敗が後続の ProvideAIContextAsync にも影響し続ける可能性があったため、次回呼び出しで再プローブできるように修正されています。(GitHub)
これは、エージェント起動時にDockerがまだ起動していない、CLIの検出が一時的に失敗した、開発環境のPATHが変わった、といったケースで効きます。導入時は、初回失敗後に再試行できるかを必ずテストしてください。
odd capと重複ProbeToolsの修正
round 8では、出力上限が奇数値だった場合のデータ欠落、未ペアのサロゲート文字、clean environmentで保持する環境変数リストの重複管理が見直されています。round 9では、ProbeTools に git と GIT のような大文字小文字違いの重複があっても同じCLIを二重にプローブしない修正が入っています。(GitHub)
実務では、ProbeTools に git、dotnet、node、npm、az などを指定する可能性があります。チーム内で設定を合成する場合、大文字小文字の重複や不要なCLI検出が入りやすいため、設定ファイル側でも重複排除しておくと安全です。
LocalShellExecutorを使う場合の確認ポイント
ローカル実行は便利ですが、最も慎重に扱うべき構成です。最新の差分では、LocalShellExecutor は実マシン上でbash、sh、PowerShell、cmdなどを起動し、stdout、stderr、exit codeを取得する設計です。Persistent modeでは cd や環境変数の変更が次の呼び出しにも残ります。(GitHub)
ローカル実行を検討する場合、最低限次の設定を確認してください。
| 設定 | 見るべき理由 | 推奨判断 |
|---|---|---|
requireApproval | AIが生成したコマンドを人間が承認するか | 本番・共有環境では原則オン |
AcknowledgeUnsafe | 承認なし実行を明示的に許可するか | ローカルホストでは安易に有効化しない |
ShellMode.Persistent | cd や環境変数が次回に残る | 開発支援では便利だが、ユーザー共有環境では注意 |
ConfineWorkingDirectory | 作業ディレクトリ外への移動を抑える | 既定値を変える前に目的を明確化 |
CleanEnvironment | 親プロセスの環境変数継承を抑える | APIキーや社内設定の漏えい防止に有効 |
Timeout | 長時間・無限実行を防ぐ | null の意味を確認し、必要なら明示設定 |
MaxOutputBytes | 出力肥大化を防ぐ | ビルドログやテストログ量に合わせて調整 |
特に危険なのは、「開発環境だから」と承認を外し、そのままCIや社内サーバーに持ち込むことです。Agent Frameworkの承認機能では、関数実行前に人間の承認を必要とする仕組みが説明されており、承認が必要な関数呼び出しがある場合は、呼び出し側が承認・拒否を処理する必要があります。(Microsoft Learn)
DockerShellExecutorを使う場合の確認ポイント
Docker実行は、ローカル実行よりも境界を作りやすい構成です。最新差分では、DockerShellExecutor はDockerまたは互換ランタイム内でコマンドを実行し、既定ではネットワークなし、非rootユーザー、読み取り専用root filesystem、capability drop、no-new-privileges、メモリ・PID制限などの強化設定を使う説明になっています。(GitHub)
ただし、Dockerを使えば安全という意味ではありません。PR内の説明でも、隔離の強さはホストカーネル、コンテナランタイム、イメージ、追加引数に依存し、単独の防御策として過信すべきではないとされています。(GitHub)
| Docker設定 | 既定・確認ポイント | 注意点 |
|---|---|---|
| Network | 既定はネットワークなし | 外部API呼び出しが必要な場合、許可範囲を明示する |
| User | 非rootユーザーが基本 | root実行に変えると承認・監査の重要度が上がる |
| ReadOnlyRoot | root filesystemを読み取り専用 | 書き込み先は /tmp やワークスペースに限定する |
| HostWorkdir | ホストディレクトリをマウント可能 | 読み取り専用を維持し、秘密情報を置かない |
| ExtraRunArgs | 追加のdocker run引数 | ここで隔離を弱めると安全前提が崩れる |
| Timeout | コマンドごとの上限 | 長時間ビルドやテストでは適切に調整する |
DockerShellExecutor には、構成が推奨ハードニングに合っているかを見る IsHardenedConfiguration があり、設定を緩めた場合は承認を要求する方向に倒す設計が示されています。ただし、これは便利な既定値であり、承認やポリシー判断を自動判定に丸投げしてよいという意味ではありません。(GitHub)
StatelessとPersistentはどう選ぶべきか
shell tool導入で迷いやすいのが、Stateless modeとPersistent modeの選択です。
| モード | 特徴 | 向いている用途 | 失敗しやすいポイント |
|---|---|---|---|
| Stateless | 毎回新しいシェルで実行 | 単発コマンド、監査しやすい実行、ユーザー共有環境 | cd や環境変数が次回に残らない |
| Persistent | 同じシェルを再利用 | コーディング支援、複数手順のビルド・テスト、同じ作業ディレクトリでの連続作業 | 状態が残るため、別ユーザーや別タスクに流用すると危険 |
PRのサンプルでは、Statelessでは前回の cd が次回に残らず、Persistentでは作業ディレクトリや環境変数が次回呼び出しに残ることを示すコードが追加されています。(GitHub)
判断基準はシンプルです。エージェントに「プロジェクトを開いて、依存関係を確認し、ビルドし、テストし、失敗箇所を直す」といった連続作業をさせるならPersistentが便利です。一方、ユーザーごとの分離が必要なWebサービスや、監査性を優先する社内実行基盤では、Statelessまたはセッションごとに独立したExecutorを使う設計が向いています。
ShellPolicyは安全装置だが、境界ではない
ShellPolicy は、危険なコマンドを正規表現で拒否するガードレールです。既定のdeny listには、rm、mkfs、shutdown、reboot、curl | sh、PowerShellの Remove-Item や Format-Volume などに関するパターンが含まれています。(GitHub)
ただし、PR内のコメントでも、パターンベースのフィルタは変数展開、別インタープリター、base64化、別コマンドなどで回避され得るため、セキュリティ境界ではないと説明されています。(GitHub)
実務では、次のように使い分けるのが現実的です。
| 対策 | 役割 | 単独で十分か |
|---|---|---|
| ShellPolicy | 明らかに危険なコマンドを止める | 不十分 |
| Human approval | 実行前に人間が内容を確認する | 重要だが運用設計が必要 |
| Docker隔離 | ホストへの影響範囲を狭める | 過信は不可 |
| 最小権限ユーザー | 実行権限を限定する | 必須に近い |
| 監査ログ | 何を実行したか追跡する | 本番では必須 |
| ネットワーク制限 | データ持ち出しを抑える | 機密環境では必須 |
移行・導入前のチェックリスト
PRがマージされ、正式なパッケージやドキュメントとして利用できるようになったら、次の順序で確認すると失敗しにくくなります。
| 手順 | 確認内容 | 完了の目安 |
|---|---|---|
| PRとリリース状況を確認 | PRがマージ済みか、NuGetに公開済みか、API名が確定しているか | サンプルと公式ドキュメントの型名が一致している |
| 実行境界を決める | ローカル実行かDocker実行か | 本番では原則Dockerまたは専用隔離環境 |
| 承認フローを設計 | 誰が、どの画面で、何を見て承認するか | コマンド、作業ディレクトリ、引数、理由を表示できる |
| ポリシーを定義 | deny list、allow list、作業ディレクトリ制限 | 危険操作と許可操作をチームで合意済み |
| タイムアウトを決める | null、30秒、長時間ビルド用など | 無限実行やコンテナ放置を防げる |
| 出力上限を決める | MaxOutputBytes とログ保存方針 | エージェント判断に必要な情報が残る |
| 環境変数を整理 | 親プロセス環境を引き継ぐか | APIキーやトークンが不要に露出しない |
| マルチユーザー設計を確認 | ExecutorやPersistent sessionを共有しないか | ユーザー・セッションごとに状態が分離されている |
| テストを追加 | 日本語出力、stderr、timeout、policy deny、Dockerなし環境 | CIで再現可能なテストになっている |
特に、後続レビューでは LocalShellTool/DockerShellTool から LocalShellExecutor/DockerShellExecutor へのリネームなども入っているため、記事や社内手順書を作る場合は、PR本文だけでなく最新の差分とサンプルを照合してください。(GitHub)
よくある誤解と注意点
dotnet shell という新しいCLIコマンドではない
今回の「Feat/dotnet shell tool」は、通常の.NET SDKに dotnet shell コマンドが追加されたという意味ではありません。Microsoft Agent Frameworkの.NET実装に、AIエージェント用のシェル実行ツールが追加されるPRと理解するのが自然です。PRは microsoft/agent-framework リポジトリの変更であり、ファイル一覧もAgent Frameworkのツール実装配下にあります。(GitHub)
Dockerなら承認不要と決めつけない
Docker実行は有効な選択肢ですが、ネットワークを有効にする、rootで実行する、ホストディレクトリを書き込み可能でマウントする、追加の docker run 引数で権限を広げる、といった変更をすればリスクは大きく変わります。DockerShellExecutor の説明でも、隔離は環境に依存し、強い隔離が必要な場合は専用VMや追加の分離技術も検討すべきとされています。(GitHub)
Persistent modeを共有インスタンスで使わない
Persistent modeは、同じシェル状態を維持できるためコーディングエージェントには便利です。しかし、Webアプリのシングルトンとして1つのExecutorを複数ユーザーに共有すると、前のユーザーの作業ディレクトリ、環境変数、関数定義が次のユーザーに影響する可能性があります。
ユーザー単位、セッション単位、ジョブ単位で分離する設計にしてください。
プロンプトだけで安全性を担保しない
「危険なコマンドを実行しないで」とinstructionsに書くだけでは不十分です。AIエージェントが実行権限を持つ場合は、プロンプト、ポリシー、承認、隔離、監査ログを組み合わせる必要があります。
導入後に使える実務シナリオ
安全設計を前提にすれば、shell toolは.NET開発ワークフローで有用です。
| シナリオ | 例 | 推奨構成 |
|---|---|---|
| テスト失敗の原因調査 | dotnet test を実行し、失敗ログを読んで修正候補を出す | Docker、Persistent、承認あり |
| 依存関係確認 | dotnet list package、dotnet workload list を実行 | Statelessでも可 |
| リポジトリ状態の確認 | git status、git diff、git log を取得 | 読み取り中心のallow list |
| ビルド支援 | dotnet build を実行し、エラーを要約 | 出力上限とtimeoutを調整 |
| 開発環境診断 | OS、シェル、CLIバージョンを確認 | ShellEnvironmentProviderを活用 |
一方で、デプロイ、削除、権限変更、外部への送信、秘密情報を含む操作は、AIエージェントに直接任せるのではなく、人間の承認や別ワークフローに分けるべきです。
今回の更新を受けて次にやること
.NETのshell tool更新を確認したら、最初にやるべきことは「試すこと」ではなく「実行境界を決めること」です。
開発支援だけなら、まずローカルではなくDocker隔離で試し、承認あり、ネットワークなし、読み取り専用マウントから始めるのが安全です。次に、日本語ログ、長いビルドログ、タイムアウト、拒否ポリシー、CLI未インストール時の挙動をテストします。最後に、PRのマージ状況、NuGetパッケージ、公式ドキュメント、サンプルコードでAPI名が一致していることを確認してから、社内標準や本番環境への導入を判断してください。
この更新は、.NETのAIエージェント開発を実用面で大きく前進させる可能性があります。一方で、シェル実行は便利さと危険性が同時に増える機能です。対応すべきポイントは、機能の有無ではなく「誰の権限で、どこで、何を、どの承認のもとで実行するか」です。
コメント