Microsoft Foundry でオンプレミス API に安全に接続したいのに、同じ VNet 内の VM からは成功し、Foundry のエージェントからだけ失敗する。この症状なら、最初に疑うべきは VPN や ExpressRoute そのものではなく、Capability Host と VNet injection が成立しているかです。Microsoft は 2026年4月20日のトラブルシュート記事で、Project / Agent Capability Hosts が private connectivity の見落とされがちな前提条件だと明示しました。Private Endpoint を作っただけでは、エージェント実行トラフィックは自動であなたの VNet に入りません。この記事では、なぜこの落とし穴が起きるのか、どこを見れば最短で原因に届くのか、401/403 をどう読めばよいのかまで、実務で使える形に整理します。 (TECHCOMMUNITY.MICROSOFT.COM)
2026年4月20日時点で何が明確になったのか
Microsoft の 2026年4月20日の記事が重要なのは、これまで「DNS は正しい」「VM から疎通できる」「Private Endpoint もある」という確認で止まりがちだった private connectivity の調査に対して、Capability Host がない限り Foundry agent の実行は顧客 VNet に注入されないという前提をはっきり打ち出した点です。つまり、ネットワーク設計そのものが正しくても、エージェントの“実行場所”が違えば失敗する、というのが核心です。 (TECHCOMMUNITY.MICROSOFT.COM)
この整理は、Learn の現行ドキュメントとも整合しています。Foundry Agent Service の private networking では、顧客管理の VNet と委任サブネット、BYO の Azure Storage / Cosmos DB / Azure AI Search などを使う Standard Setup with private networking が前提で、Agent の outbound 通信を private 経路に乗せるには VNet integration / virtual network injection が必要です。 (Microsoft Learn)
先に結論: Private Endpoint は「入口」、Capability Host は「出口」
Private Endpoint は、Foundry アカウントや関連 PaaS への受信側アクセスを私設化する仕組みです。一方で、オンプレミス API や private な Azure リソースへ向かう Foundry agent の送信側トラフィックをあなたの VNet に載せるには、Agent runtime がそのサブネットで動けるようにする control point が必要です。Microsoft はこれを Capability Host として説明しています。 (TECHCOMMUNITY.MICROSOFT.COM)
実務では、次の順で理解すると混乱しにくくなります。
Foundry account / project → capability host → delegated agent subnet → agent runtime → VPN/ExpressRoute → on-prem API。
このチェーンのどこかが欠けると、VM からの疎通結果は良くても、agent 側は corporate DNS・ルーティング・NSG・Firewall の前提を継承できません。 (TECHCOMMUNITY.MICROSOFT.COM)
なぜ VM では成功し、エージェントだけ失敗するのか
いちばんハマりやすいのは、VM テストで成功したことを、そのまま agent runtime の成功条件だと思い込むことです。VM は確実に VNet 内にいますが、Foundry agent は Capability Host と subnet binding が正しく成立していなければ、その DNS やルーティングを継承しません。Microsoft の 2026年4月20日の記事でも、まさにこのパターンが繰り返し出る enterprise scenario として整理されています。 (TECHCOMMUNITY.MICROSOFT.COM)
| 見えている症状 | まず疑うべきこと | 読み方 |
|---|---|---|
| VM では on-prem API に到達できるが agent は timeout / DNS failure | Capability Host 未作成、または誤った subnet binding | DNS 設計が壊れているのではなく、agent がその DNS 経路に入っていない可能性が高い |
| Private Endpoint はあるのに agent だけ失敗 | inbound private access と outbound VNet injection を混同している | Private Endpoint だけでは agent outbound は private 化されない |
| subnet injection 後に 401 が出る | API 認証・認可 | むしろ private path で到達し始めたサイン |
| capability host が Failed | RBAC / 接続不足 / Cosmos RU/s / provider 未登録 / subnet 問題 | ネットワーク以前に host 自体が成立していない |
| ログに想定外の backend/proxy URL が出る | 実行経路の誤認 | 想定した private path を通っていない可能性がある |
表は Microsoft の field guidance と公式ドキュメントをもとに、切り分け順序が分かるよう再構成しています。特に 「VM では引ける名前が agent では引けない」= DNS 設計不良 と即断しないことが重要です。 (TECHCOMMUNITY.MICROSOFT.COM)
Capability Hosts をどう理解すればいいか
ここは用語が少しややこしい部分です。2026年4月20日のブログは「Project / Agent Capability Hosts」という言い方をしていますが、Learn の現行概念・API ドキュメントでは、Capability Host は account スコープと project スコープのサブリソースとして説明されています。さらに DR ガイドでは “Agent capability host” をproject 単位で agents を収容する基盤として扱っています。つまり、用語の粒度に差はありますが、運用上のチェックポイントは同じです。account / project の capability host が存在し、project 側が正しい接続先と customerSubnet を参照し、Succeeded になっているかを確認してください。 (TECHCOMMUNITY.MICROSOFT.COM)
Learn の Capability Hosts ドキュメントでは、account-level host が共有既定値、project-level host がその上書き役として説明され、project host には thread storage、vector store、file storage、必要に応じて Azure OpenAI の connection 名を設定します。REST と ARM の定義には customerSubnet プロパティもあり、private networking ではこの subnet binding が実務上の要点になります。 (Microsoft Learn)
private なオンプレ接続に必要なセットアップを3つで整理する
Foundry Agent Service は、ざっくり言うと次の3モードで考えると判断しやすいです。 (Microsoft Learn)
| セットアップ | データ保存先 | outbound の private 制御 | オンプレ private API 接続との相性 |
|---|---|---|---|
| Basic Setup | Microsoft 管理 | なし | 不向き |
| Standard Setup | 自社 Azure リソース | 可能だが public networking 前提もある | 要件次第 |
| Standard Setup with private networking / BYO VNet | 自社 Azure リソース | あり。委任サブネットで VNet injection | 本命 |
この比較で重要なのは、Basic Setup では private network isolation を前提にした agent outbound 制御ができないことです。Environment setup の比較表でも、Bring Your Own Virtual Network による Private Network Isolation は Standard Setup 側の話として整理されています。 (Microsoft Learn)
さらに厄介なのは、「ポータルで作れた = network-isolated agent ができた」ではないことです。Foundry のドキュメントは体験や世代が混在しており、basic-setup 前提の quickstart もあれば、2026年4月22日時点の network isolation ドキュメントでは、BYO Storage / Search / Cosmos DB を選び、Public network access を無効化した場合に限って、ポータルから virtual network injection を伴う構成を案内しています。GA 概要でも、new Foundry portal で未対応のシナリオは classic experience を使い続ける前提が明記されています。要するに、画面上の作成フローではなく、最終的な setup mode と capability host の実体を確認することが大切です。 (Microsoft Learn)
なお、managed virtual network は別系統の運用モデルです。preview ドキュメントでは、on-prem resources への private access が必要な場合に Application Gateway を使う案内が出ています。BYO VNet と managed VNet は前提が違うため、設計を混ぜないほうが安全です。 (Microsoft Learn)
どのツールが本当に VNet を通るのか
設計ミスを減らしたいなら、「どのツールの通信が自分の VNet を通るのか」を先に確認してください。2026年4月22日更新の network isolation ドキュメントでは、new Responses API agents 向けに次のような違いが明示されています。 (Microsoft Learn)
| ツール / パターン | 通信経路 | 実務上の意味 |
|---|---|---|
| OpenAPI tool / Azure Functions / MCP / A2A | あなたの VNet | private API や on-prem API に向く |
| Azure AI Search | private endpoint | private search 連携向き |
| Code Interpreter / Function Calling | Microsoft backbone | VNet 経由とは限らない |
| Bing Grounding / Websearch / SharePoint Grounding | public endpoint | 全通信 private 必須の環境では不適合になりうる |
オンプレミス API を呼ぶケースでは、OpenAPI tool や Azure Functions、MCP などVNet 経由のツールを前提に考えるのが基本です。逆に、Code Interpreter が動いたからといって「private networking が正しく効いている」と判断するのは危険です。 (Microsoft Learn)
最短で原因にたどり着く切り分け手順
まず setup mode を確定する
最初にやるべきは、「今の project は Basic なのか、Standard なのか、private networking 付き Standard なのか」を曖昧にしないことです。オンプレ private API に安全接続したいなら、BYO resources + private networking + delegated subnet が入っている構成でなければ話が前に進みません。ここが Basic なら、DNS や VPN をいくら掘っても本質解決になりません。 (Microsoft Learn)
Capability Host を列挙して provisioningState を見る
次に、account / project の capability host が本当に存在するか確認します。概念ドキュメントにも、account と project の両方を GET して設定を確認する手順が出ています。 (Microsoft Learn)
az rest --method GET \
--url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/capabilityHosts?api-version=2025-06-01"
az rest --method GET \
--url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/projects/<project-name>/capabilityHosts?api-version=2025-06-01"見るべき項目は、存在有無、provisioningState、customerSubnet、storageConnections、vectorStoreConnections、threadStorageConnections、必要に応じて aiServicesConnections です。ここで host が無い、または Failed なら、ネットワーク層の深掘りより先に host 作成条件を見直すほうが早いです。 (Microsoft Learn)
customerSubnet、subnet delegation、region を見る
private networking では、agent subnet は Microsoft.App/environments に委任されている必要があります。専用サブネットであること、十分なアドレス空間があること、すべての Foundry workspace resources が VNet と同じ region にあることも重要です。Microsoft の dedicated private networking ガイドでは /24 推奨、別の network isolation ガイドでは /27 以上という条件が案内されており、実務では 小さすぎる subnet を避けて余裕を持たせるのが安全です。さらに、agent subnet は複数の Foundry resource で共有できません。 (Microsoft Learn)
ここで見落としやすいのが、設定変更後の挙動です。Capability Host は更新非対応で、構成を変えたいときは削除して作り直す前提です。subnet や接続先を後から直しても、そのままでは効かないケースがあります。 (Microsoft Learn)
Connections、RBAC、Cosmos RU/s を見る
Capability Host が Failed になる原因は、ネットワークだけではありません。Standard Setup では、Azure Storage、Azure Cosmos DB、Azure AI Search の接続が project に存在していることが前提で、作成者には Foundry account への Contributor、さらに下流リソースへロールを付与するための User Access Administrator / Owner / Role Based Access Control Administrator 相当の権限が必要です。 project の managed identity にも、Cosmos、Storage、Search へ必要なロールが必要です。 (Microsoft Learn)
加えて、Cosmos DB のスループット不足は見落としやすい実務ポイントです。Standard Setup のドキュメントでは、合計 3000 RU/s 以上が必要で、不足すると capability host provisioning failure の原因になります。オンプレ API とは直接関係がないので後回しにされがちですが、host 自体が壊れていれば当然 private networking も機能しません。 (Microsoft Learn)
DNS は「VNet の中から」確認する
DNS の確認は、ローカル PC ではなく、その VNet から名前解決できるマシンで行ってください。private networking ガイドでは、private DNS zones の設定、privatelink.* の名前解決、custom DNS を使う場合の条件付きフォワーダー先として Azure DNS virtual server 168.63.129.16 を案内しています。VM から nslookup して private IP に解決されることは重要ですが、それは「VNet 側 DNS が正しい」ことの確認であって、「agent runtime がそれを継承している」ことの証明にはなりません。そこは Capability Host と subnet injection で別に確認が必要です。 (Microsoft Learn)
401 / 403 / timeout の読み方を変える
エラーコードの読み違いも、調査を長引かせる原因です。Microsoft の 2026年4月20日の記事では、subnet injection と DNS 修正後に 401 が出るのは、private path で API に届き始めたサインとして説明されています。ここで DNS や VPN に戻るのではなく、トークン、audience、header、connection の認証設定を見直すべきです。 (TECHCOMMUNITY.MICROSOFT.COM)
一方で、403 は文脈によって意味が変わります。Foundry 側の操作で 403 なら RBAC 不足の可能性が高く、API 側で 403 なら API の認可ルールの問題です。認証・認可の整理では、Foundry は control plane と data plane を分けており、Capability Host 作成は control plane、agent 利用は data plane 側です。この違いを理解していないと、「Azure AI User は持っているのに host が作れない」という状態に陥ります。 (Microsoft Learn)
見落としやすい落とし穴
| 落とし穴 | 何が問題か | 正しい考え方 |
|---|---|---|
| Private Endpoint を作れば outbound も private になると思う | inbound と outbound を混同している | outbound には VNet injection と capability host が必要 |
| VM から通るので agent も同じ経路だと思う | 実行場所が違う | VM テストは VNet 設計の確認、agent 配置の確認ではない |
| Basic Setup のまま private API を呼ばせようとする | セットアップモードが不一致 | private on-prem 接続は Standard + private networking 前提 |
| Capability Host は後から更新できると思う | 実際は更新非対応 | 変更時は delete / recreate を前提にする |
| agent subnet を他の Foundry と共有する | サポート外 | Foundry ごとに専用サブネットを使う |
| 172.17.0.0/16 を使う | Docker bridge と競合 | その範囲は避ける |
| public endpoint ツールも private だと思う | 実際は public 通信 | 全通信 private 必須ならツール選定から見直す |
この表は Microsoft Learn の private networking / network isolation / capability host ドキュメントをもとに、障害時に頻出する誤解へ落とし込んだものです。 (Microsoft Learn)
再発防止の設計指針
ここまでの話を一時的なトラブルシュートで終わらせないために、設計段階でやっておきたいことがあります。 (Microsoft Learn)
- Capability Host を IaC に含める
account / project host、connections、subnet、private endpoints、DNS をまとめて Bicep / Terraform で管理すると、「VNet はできたが host が無い」という抜け漏れを減らせます。DR ガイドも agent 定義と capability host dependencies を IaC として扱うことを勧めています。 (Microsoft Learn) - Azure Policy で“valid Agent capability host なし”を監査する
Microsoft は custom policy のユースケースとして、valid Agent capability host を持たない Foundry resources の監査を挙げています。規制や内部統制が強い組織では、ここを人手チェックにしないほうが安全です。 (Microsoft Learn) - Basic と Standard を同じ account / project 群で混ぜない
Capability Hosts ドキュメントでは、standard setup と basic setup を同じ Foundry account に混在させないことが推奨されています。ネットワーク前提が違うため、運用トラブルの元になります。 (Microsoft Learn) - project を blast radius として設計する
DR ドキュメントでは、通常は 1 project が回復単位です。しかも Agent Service には built-in DR や state migration がなく、cross-region failover でも thread history や user-uploaded files はそのまま引き継げません。private networking を組めば終わりではなく、project 単位の復旧設計まで持っておくべきです。 (Microsoft Learn)
要するに、Microsoft Foundry でオンプレミスの private API へ安全接続できないとき、VPN / ExpressRoute / DNS / Private Endpoint が正しいだけでは不十分です。Capability Host が正しく作成され、project が BYO resources と delegated subnet に結び付いて初めて、agent runtime は VNet の DNS・ルーティング・セキュリティ制御を継承します。次にやるべきことは明確です。まず setup mode を確認する。次に account / project capability hosts の Succeeded と customerSubnet を見る。そこが通ったら、401/403 はネットワークではなく認証・認可として切り分ける。この順番に変えるだけで、長い war room をかなり減らせます。 (TECHCOMMUNITY.MICROSOFT.COM)
コメント