Microsoft Foundry Agent Service / private networking でオンプレミス API に接続できない場合、最初に見るべきポイントは VPN や ExpressRoute そのものではありません。結論から言うと、Foundry エージェントの実行基盤が本当に VNet 内の委任サブネットへ配置されているか、つまり Capability Host が正しく作成・関連付けされているかを確認する必要があります。
Microsoft は 2026年4月20日付で「Troubleshooting Microsoft Foundry Accessing On‑Premises APIs Over Private Networking」というガイダンスを公開し、VM からはオンプレミス API に到達できるのに、Foundry agent からは DNS 解決失敗、タイムアウト、HTTP 401/403 などが発生する典型パターンを整理しました。ポイントは、Private Endpoint を作成しただけでは、Agent runtime のアウトバウンド通信が自動的に自社 VNet を通るわけではないという点です。(TECHCOMMUNITY.MICROSOFT.COM)
この記事では、Enterprise AI architects、network engineers、security architects がすぐに確認すべき変更点、影響範囲、初動チェックを実務視点で整理します。
Microsoft Foundry Agent Service / private networking の最新動向
今回の Microsoft ガイダンスは、Microsoft Foundry Agent Service がオンプレミス、またはプライベートにホストされた API を VPN / ExpressRoute 経由で呼び出す構成を対象にしています。特に、VNet 内の VM では名前解決も API 呼び出しも成功するのに、Foundry agent では同じ API 呼び出しが失敗するケースが中心です。(TECHCOMMUNITY.MICROSOFT.COM)
実務で重要なのは、これは単なるトラブルシューティング記事ではなく、Foundry Agent Service の private networking 設計における前提確認リストとして使える点です。
これまで多くのチームは、次のように考えがちでした。
- Foundry リソースに Private Endpoint を作った
- VNet からオンプレミス DNS にフォワードできる
- VM からオンプレミス API にアクセスできる
- だから Foundry agent からも同じ経路でアクセスできるはず
しかし、Microsoft の説明では、この理解が不十分です。Foundry agent のアウトバウンド通信が VNet ルーティング、DNS、セキュリティ制御を継承するには、Capability Host によるサブネットへの配置が重要な前提になります。(TECHCOMMUNITY.MICROSOFT.COM)
最初に確認すべき結論: Capability Host がないと VNet 内で実行されない
Microsoft Foundry Agent Service / private networking の切り分けで最初に確認すべきことは、Project Capability Host または Agent Capability Host が正しく関連付けられているかです。
Microsoft のガイダンスでは、Private Endpoint は基本的にインバウンド接続のための構成であり、Foundry agent の実行時トラフィックを自動的に自社 VNet に流すものではないと説明されています。Agent runtime が VNet の DNS 設定やルーティングを継承するには、Capability Host によって、プロジェクトまたはエージェントが顧客管理のサブネットに関連付けられている必要があります。(TECHCOMMUNITY.MICROSOFT.COM)
つまり、初動で見るべき順序は次のとおりです。
| 優先度 | 確認項目 | 見るべき理由 |
|---|---|---|
| 最優先 | Project / Agent Capability Host が存在するか | Agent runtime が VNet に配置される前提 |
| 最優先 | Capability Host が正しいサブネットを参照しているか | 誤ったサブネットでは DNS・ルート・NSG の前提が崩れる |
| 高 | agent subnet が適切に委任されているか | Microsoft.App/environments への委任が必要になる構成がある |
| 高 | VNet DNS がオンプレミス DNS に到達できるか | Agent が VNet 内に配置された後の名前解決経路を確認するため |
| 中 | HTTP 401/403 がネットワーク問題か認証問題か | 401 は「到達できた後の認証失敗」の可能性がある |
| 中 | 利用している Foundry 体験・SDK・CLI が対象構成をサポートするか | UI や hosted agents の制約で期待通りに動かない場合がある |
特に重要なのは、VM で成功していることは、Foundry agent で成功することの証明にはならないという点です。VM は確実に VNet 内にありますが、Capability Host が未設定の agent runtime は、同じネットワーク境界内で実行されていない可能性があります。
影響を受けやすい構成
今回のガイダンスで影響を受けやすいのは、オンプレミス API、社内 DNS、閉域ネットワーク、AI エージェントを組み合わせている企業環境です。
| 構成 | 影響を受ける理由 | 最初の確認ポイント |
|---|---|---|
| VPN / ExpressRoute 経由でオンプレミス API を呼び出す | Agent runtime が VNet 外にあると閉域経路を使えない | Capability Host とサブネット参照 |
| 社内 DNS で API 名を解決している | Agent が VNet DNS を継承していないと名前解決できない | VNet DNS、条件付きフォワーダー、agent subnet |
| OpenAPI tool で社内 API を呼び出す | API 定義は正しくても実行経路が違うと失敗する | Agent の配置先と認証設定 |
| Azure Firewall / Proxy を経由している | FQDN 許可、TLS inspection、Managed Identity 通信で詰まりやすい | Firewall ログ、許可リスト、TLS inspection 有無 |
| Private Endpoint を複数構成している | Private Endpoint は inbound 前提のため outbound 経路と混同しやすい | Agent runtime の VNet injection |
| 複数 agent を異なる分離境界で運用している | プロジェクト単位と agent 単位の Capability Host 設計が必要 | Project Capability Host と Agent Capability Host の使い分け |
この構成では、ネットワーク担当者だけでなく、AI アーキテクトとセキュリティ担当者が同じ前提を共有していないと、調査が長引きます。たとえば、ネットワーク担当者は「VNet から API に到達できる」と判断し、AI チームは「agent が失敗する」と報告し、認証担当者は「401 なら認証では」と見ます。実際には、agent がどこで実行されているかを確認しない限り、どの判断も途中で止まってしまいます。
Capability Host とは何か
Capability Host は、Foundry の機能がどこで実行されるかを定義する制御点です。private networking では、Foundry project や agent を顧客管理のサブネットに関連付け、プラットフォーム管理のコンテナ実行基盤をそのサブネットに注入するために使われます。これにより、agent のアウトバウンド通信が VNet のルーティング、DNS、セキュリティ制御に従うようになります。(TECHCOMMUNITY.MICROSOFT.COM)
Capability Host には、主に次の考え方があります。
| 種類 | 適用範囲 | 向いているケース |
|---|---|---|
| Project Capability Host | プロジェクト配下の agent 全体 | 同一プロジェクト内の agent を同じネットワーク境界で運用する場合 |
| Agent Capability Host | 個別 agent | agent ごとに異なる分離境界やサブネットを使いたい場合 |
実務では、まず Project Capability Host を基本に考えると整理しやすくなります。全 agent が同じオンプレミス API 群にアクセスするなら、プロジェクト単位で統一した方が運用ミスを減らせます。一方、機密度の高い API と一般業務 API を分けたい場合は、Agent Capability Host による個別設計が候補になります。
「VM から成功するのに agent から失敗する」原因
この問題の本質は、テスト対象の実行場所が違うことです。
VNet 内の VM から nslookup や curl を実行して成功しても、それは「その VM が持つ DNS 設定、ルート、NSG、Firewall ポリシーでは成功する」という意味にすぎません。Foundry agent が同じサブネットに注入されていなければ、同じ条件でテストしたことにはなりません。
Microsoft のガイダンスでも、Capability Host がない場合、agent runtime は VNet DNS サーバー設定、社内 DNS フォワード規則、オンプレミス名前解決経路を継承しないと説明されています。(TECHCOMMUNITY.MICROSOFT.COM)
よくある失敗パターンは次の通りです。
| 症状 | よくある原因 | 初動 |
|---|---|---|
| DNS resolution failure | agent runtime が VNet DNS を使っていない | Capability Host の関連付けを確認 |
| Connection timeout | 閉域ルート、Firewall、NSG のいずれかで遮断 | agent subnet からの経路を確認 |
| HTTP 401 | API には到達しているが認証に失敗 | token、audience、header、接続設定を確認 |
| HTTP 403 | 認可、IP 制限、API Gateway 側ポリシーで拒否 | 送信元経路と認可ルールを確認 |
| 予期しない backend / proxy URL がログに出る | 管理プロキシや経路設計の影響 | request path と proxy hop を確認 |
特に HTTP 401 は、ネットワーク障害と誤解されやすいポイントです。Microsoft は、サブネット注入や DNS が修正された後に 401 が出る場合、API に到達し、プライベート経路でルーティングされている可能性があり、調査対象はネットワークから認証・認可へ移ると説明しています。(TECHCOMMUNITY.MICROSOFT.COM)
すぐ実行すべき初動チェック
Microsoft Foundry Agent Service / private networking の障害対応では、最初から Firewall ログや DNS サーバー設定を深掘りするより、次の順番で確認した方が早く原因に近づけます。
Capability Host の関連付けを確認する
まず、対象の project または agent に Capability Host が関連付けられているかを確認します。未設定であれば、VPN、ExpressRoute、Private Endpoint、社内 DNS が正しくても、agent runtime がそのネットワーク構成を使っていない可能性があります。
確認すべき観点は次の3つです。
- Project Capability Host が作成されているか
- Agent Capability Host を使っている場合、対象 agent に正しく紐づいているか
- Capability Host が意図した customer subnet を参照しているか
構成変更後は、既存 agent の再作成や再デプロイが必要になる場合があります。ネットワーク構成を変更したのに agent の実行環境が古い前提のまま動いていると、調査結果がぶれます。
agent subnet の委任とサイズを確認する
Microsoft Learn の private networking ガイドでは、network-secured environment の検証項目として、agent subnet が Microsoft.App/environments に委任されていることを確認する手順が示されています。また、agent subnet は Foundry リソース間で共有できないこと、推奨サイズとして /24 が示されていることも記載されています。(Microsoft Learn)
実務では、次のような設計ミスが起きやすいです。
- 既存の共有サブネットを流用している
- サブネットサイズが小さく、将来の agent 増加に耐えない
- 委任設定が入っていない
- 別の Foundry リソースと同じ agent subnet を使っている
- Private Endpoint 用サブネットと agent 用サブネットを混同している
agent subnet は「AI エージェントの実行場所」として扱うべきです。単なるネットワーク接続点ではなく、セキュリティ境界、IP アドレス設計、監査ログ設計の対象になります。
VNet DNS とオンプレミス DNS の経路を確認する
Capability Host によって agent がサブネットへ配置された後は、DNS の確認が重要になります。
Microsoft Learn では、Private Endpoint の DNS 解決確認として、VNet に接続されたマシンから対象 FQDN に対して nslookup を実行し、プライベート IP に解決されるかを確認する手順が示されています。また、Private DNS zone が VNet にリンクされているか、条件付きフォワーダーが Azure DNS virtual server IP に向いているかも確認ポイントとして挙げられています。(Microsoft Learn)
オンプレミス API の場合は、さらに次の観点が必要です。
- VNet の DNS 設定が社内 DNS または DNS Forwarder を参照しているか
- 社内 DNS がオンプレミス API の FQDN を解決できるか
- API の FQDN が public IP ではなく、意図した private IP に解決されているか
- split-brain DNS を使っている場合、Azure 側から見た解決結果が正しいか
- DNS TTL が長すぎて古いレコードを引いていないか
ここで重要なのは、「VM で名前解決できる」だけで終わらせないことです。agent が注入されるサブネット、Firewall、DNS Forwarder、オンプレミス DNS までの経路を一続きで確認します。
Private Endpoint と outbound 通信を混同しない
Private Endpoint は、Azure リソースへプライベートに到達するための重要な構成です。ただし、Foundry agent がオンプレミス API を呼び出す outbound 経路を自動的に作るものではありません。
Microsoft Learn の Standard Setup with private networking では、BYO private virtual network、subnet integration、private resource access、no public egress といった考え方が説明されています。つまり、private networking は複数の要素で構成される設計であり、Private Endpoint だけで完結しません。(Microsoft Learn)
実務では、次のように役割を分けて考えると混乱しにくくなります。
| 要素 | 主な役割 |
|---|---|
| Private Endpoint | Azure リソースへのプライベートな inbound 接続 |
| Capability Host | agent runtime を顧客管理サブネットに関連付ける制御点 |
| agent subnet | agent 実行基盤がネットワーク設定を継承する場所 |
| VNet DNS | 名前解決経路を制御 |
| VPN / ExpressRoute | Azure とオンプレミス間の閉域接続 |
| Firewall / NSG | 通信許可、遮断、監査の制御 |
「Private Endpoint があるから安全」ではなく、「どの通信がどの経路を通るのか」を通信方向ごとに整理することが重要です。
権限と依存リソースの確認も早めに行う
Capability Host の作成や network-secured environment の構成では、Azure RBAC と依存リソースの準備も原因になりやすいポイントです。
Microsoft Learn では、private networking の前提として、作成者に Azure AI Account Owner ロールが必要であること、テンプレート展開者には Azure Cosmos DB、Azure AI Search、Azure Storage などに対するロール割り当て権限が必要であることが示されています。また、Role Based Access Administrator または subscription level の Owner が条件を満たす選択肢として説明されています。(Microsoft Learn)
加えて、Standard Setup では Azure Storage、Azure Cosmos DB、Azure AI Search などが files、threads、vector data の保存に使われることが説明されています。これらの依存リソースが private networking の前提に沿って接続されていないと、agent の作成や実行時に別のエラーとして表面化します。(Microsoft Learn)
確認項目は次の通りです。
| 分類 | 確認項目 | 失敗時に起きやすいこと |
|---|---|---|
| RBAC | Foundry account / project 作成者の権限 | Capability Host 作成失敗、設定不完全 |
| Role assignment | 依存リソースへの権限付与 | Storage、Search、Cosmos DB 連携失敗 |
| Resource provider | Microsoft.App、Microsoft.ContainerService など | テンプレート展開失敗 |
| Region | Foundry、VNet、依存リソースのリージョン整合 | private networking 構成不整合 |
| Project connections | Storage、Search、Cosmos DB、AI Services との接続 | agent 実行や retrieval 機能の失敗 |
ネットワークの問題に見えて、実際には RBAC や project connection が原因のこともあります。特にエンタープライズ環境では、ネットワーク管理者、Azure 管理者、AI 開発チームの権限が分かれているため、初動で権限表を共有しておくと手戻りを減らせます。
対応前に知っておきたい制約
Microsoft Foundry Agent Service / private networking には、構成上の制約があります。これを知らずにトラブルシューティングを進めると、正しいネットワーク設計をしているのに「なぜか動かない」と見えてしまいます。
Microsoft Learn では、network-secured environment のセットアップは現時点で Azure portal からの展開ではなく、Bicep または Terraform などのプログラム的な展開が必要と説明されています。また、hosted agents では、VNet 構成を Foundry account 作成時に含める必要があり、既存 Foundry account に後から network injection を追加することはサポートされないとされています。(Microsoft Learn)
さらに、Microsoft のガイダンスでは、end-to-end network isolation は新しい Foundry portal experience ではサポートされず、network-isolated agent scenarios では classic Foundry experience、SDK、CLI が必要になる旨が示されています。(TECHCOMMUNITY.MICROSOFT.COM)
実務上は、次のように判断します。
| 判断ポイント | 実務での扱い |
|---|---|
| 既存 Foundry account に後から閉域化したい | hosted agents では再作成が必要になる可能性を前提に計画する |
| Azure portal だけで完結させたい | network-secured environment では Bicep / Terraform / CLI / SDK の利用を検討する |
| 新しい Foundry portal experience を使っている | network isolation の対象シナリオか確認する |
| 本番環境で複数 agent を扱う | Project / Agent Capability Host の設計方針を先に決める |
| 監査・セキュリティ要件が厳しい | agent subnet、Firewall、DNS、ログ保全を設計書に明記する |
このあたりは、PoC では見落とされやすいポイントです。PoC で「動いた」構成をそのまま本番に持ち込むのではなく、本番では account 作成時点から private networking を前提に設計した方が安全です。
症状別の切り分け手順
DNS resolution failure が出る場合
最初に疑うべきは、DNS サーバーそのものではなく、agent がその DNS 経路を使える場所で実行されているかです。
切り分け手順は次の通りです。
- Project / Agent Capability Host の有無を確認する
- Capability Host が正しい agent subnet を参照しているか確認する
- agent subnet の VNet DNS 設定を確認する
- VNet からオンプレミス DNS へのフォワード経路を確認する
- オンプレミス API の FQDN が期待する private IP に解決されるか確認する
- DNS Forwarder や Firewall のログで query が届いているか確認する
この順序を守ることで、「DNS サーバーは正しいのに agent が使っていない」という見落としを避けられます。
Connection timeout が出る場合
timeout は、名前解決後の経路またはポリシーで止まっている可能性があります。
確認すべき項目は次の通りです。
- agent subnet からオンプレミス API へのルート
- VPN / ExpressRoute の経路広告
- UDR の設定
- NSG の outbound ルール
- Azure Firewall の allow rule
- オンプレミス Firewall の戻り通信
- API 側の送信元 IP 制限
特に、オンプレミス側で「Azure VNet からの通信」を許可しているつもりでも、実際の送信元サブネットが想定と違う場合があります。agent subnet の IP レンジを明示して、オンプレミス側の許可ルールと照合しましょう。
HTTP 401 / 403 が出る場合
HTTP 401 は、必ずしもネットワーク障害ではありません。むしろ、private path 経由で API に到達できるようになった後に、認証・認可の問題として表面化している可能性があります。Microsoft のガイダンスでも、サブネット注入と DNS が修正された後の 401 は、接続性が改善したサインとして扱えると説明されています。(TECHCOMMUNITY.MICROSOFT.COM)
確認すべき項目は次の通りです。
- Foundry connection に設定した credential / token
- API が期待する Authorization header
- token の audience / issuer / scope
- API Gateway や reverse proxy で必要な追加 header
- managed proxy hop による header の変化
- IP 制限と認証エラーのログ区別
403 の場合は、認証は通っているが認可で拒否されている場合もあります。API 側のログで、401 と 403 を分けて確認することが重要です。
予期しない proxy URL や backend URL が出る場合
ログに想定外の backend URL、proxy URL、管理プレーン由来の情報が出る場合は、単純な DNS 障害ではなく、request path の理解が必要です。
この場合は、次の情報をそろえて調査します。
- agent の tool 設定
- OpenAPI 定義内の server URL
- Foundry connection の宛先
- API Gateway / reverse proxy のログ
- Firewall の outbound ログ
- API 側で観測した source IP と header
エンタープライズ環境では、セキュリティ製品や API Gateway が途中で header を付与・削除することがあります。Foundry 側だけでなく、経路全体のログを突き合わせることが大切です。
役割別に見るべきポイント
Microsoft Foundry Agent Service / private networking は、単一チームだけでは完結しにくい領域です。AI、ネットワーク、セキュリティの責任範囲を整理しておくと、障害対応が速くなります。
| 役割 | 主な確認ポイント | 成果物 |
|---|---|---|
| Enterprise AI architect | agent の構成、tool、Capability Host、依存リソース | agent 構成図、project connection 一覧 |
| Network engineer | VNet、subnet、DNS、VPN、ExpressRoute、Firewall | 通信経路図、DNS 経路図、許可ルール |
| Security architect | Private Endpoint、public network access、認証、監査ログ | セキュリティ設計書、監査要件、アクセス制御表 |
| Azure platform engineer | RBAC、resource provider、Bicep / Terraform、リージョン整合 | IaC テンプレート、権限表、展開手順 |
| API owner | API 認証、認可、IP 制限、ログ | API 仕様、認証要件、障害ログ |
おすすめは、障害発生後ではなく、設計段階で「agent からオンプレミス API までの通信経路図」を1枚作ることです。そこに、名前解決、認証、Firewall、Private Endpoint、Capability Host を同じ図に入れると、チーム間の認識違いを減らせます。
本番環境での実装前チェックリスト
本番導入前には、次のチェックリストを使うと抜け漏れを防ぎやすくなります。
| チェック | 確認内容 |
|---|---|
| Foundry account / project | private networking 前提で作成されているか |
| Capability Host | Project または Agent に正しく関連付けられているか |
| agent subnet | 専用サブネット、委任、サイズ、IP レンジが妥当か |
| Private Endpoint | Foundry、Storage、Search、Cosmos DB など必要なリソースに設定されているか |
| DNS | Private DNS zone、条件付きフォワーダー、オンプレミス DNS が整合しているか |
| VPN / ExpressRoute | Azure からオンプレミス API への経路と戻り経路があるか |
| Firewall / NSG | agent subnet から必要な宛先への outbound が許可されているか |
| RBAC | 作成者、運用者、managed identity に必要な権限があるか |
| Project connections | Storage、Search、Cosmos DB、AI Services との接続があるか |
| 認証 | API 側が期待する token、header、audience、scope が設定されているか |
| ログ | Foundry、Firewall、DNS、API Gateway、API サーバーのログを追えるか |
| 運用 | 構成変更時に Capability Host や account 再作成が必要か確認しているか |
このチェックリストで特に見落としやすいのは、Capability Host、agent subnet、DNS の3つです。Private Endpoint や VPN は比較的目立つため設計書に載りやすいですが、agent runtime の配置場所は曖昧なまま進みがちです。
実務での推奨アクション
今回の更新を受けて、Microsoft Foundry Agent Service / private networking を利用しているチームは、次の順番で棚卸しするのが現実的です。
まず、既存の Foundry project と agent を一覧化し、それぞれに Capability Host が関連付いているかを確認します。次に、Capability Host が参照しているサブネット、VNet DNS、オンプレミス DNS へのフォワード経路を確認します。その後、agent が呼び出すオンプレミス API ごとに、FQDN、認証方式、必要 header、許可すべき送信元 IP レンジを整理します。
障害がすでに起きている場合は、次の順番で対応してください。
- Capability Host の有無を確認する
- 正しい agent subnet に関連付いているか確認する
- agent subnet からオンプレミス DNS / API への経路を確認する
- DNS 解決結果が期待する private IP か確認する
- timeout なら Firewall / NSG / UDR / VPN / ExpressRoute を確認する
- 401 / 403 なら認証・認可・header・token を確認する
- portal、SDK、CLI、hosted agents の制約に該当しないか確認する
この順番なら、DNS や Firewall を無駄に深掘りする前に、最も根本的な「agent が VNet 内にいるのか」を確認できます。
まとめ: まず「agent の実行場所」を確認する
Microsoft publishes troubleshooting guidance for Foundry agents reaching on-prem APIs over private networking の要点は、Microsoft Foundry Agent Service / private networking では、Private Endpoint や VPN だけでなく、Capability Host による agent runtime の配置確認が不可欠という点です。
VM からオンプレミス API に接続できても、Foundry agent が同じネットワーク経路を使っているとは限りません。DNS failure、timeout、HTTP 401/403 が出たら、まず Capability Host、agent subnet、DNS 継承、サポートされる Foundry experience を確認しましょう。
次に取るべき行動はシンプルです。既存環境の Foundry project / agent ごとに、Capability Host の有無、参照サブネット、DNS 経路、API 認証設定を棚卸ししてください。これにより、ネットワーク設計、セキュリティ設計、AI agent 実装の認識をそろえたうえで、オンプレミス API 連携を安定して運用しやすくなります。
コメント