Microsoft Foundry Agent Service / private networking で「VM ではオンプレ API に届くのに、Foundry エージェントだけ失敗する」という状況なら、最優先で確認すべきは private endpoint の数ではありません。2026年4月20日に公開された Microsoft のトラブルシューティングガイダンスでは、典型原因として Capability Host と VNet injection の見落とし が強調されており、private endpoint は受信側の仕組みであって、エージェントの outbound 通信が自動で自社 VNet に入るわけではない、と整理されています。(TECHCOMMUNITY.MICROSOFT.COM)
つまり、VPN や ExpressRoute、社内 DNS が正しくても、Foundry エージェントが正しいサブネットに結び付いていなければ、VM と同じ名前解決や経路を継承できません。この記事では、2026年4月時点の公開情報を踏まえ、Microsoft Foundry Agent Service / private networking の導入前確認、設定差分、展開順序、周知項目を、管理者向けの実務チェックリストとしてまとめます。(TECHCOMMUNITY.MICROSOFT.COM)
2026年4月20日の更新で管理者が最初に押さえること
- private endpoint は inbound 用 であり、エージェントの outbound が自動で自社 VNet を通ることを保証しません。オンプレ API 到達性の成否は、VNet injection と Capability Host の成立を先に見るべきです。(TECHCOMMUNITY.MICROSOFT.COM)
- 「VNet 内の VM から名前解決と疎通が成功した」は、「Foundry エージェントも同じ DNS と経路を使っている」の証明にはなりません。今回のブログは、VM は確実に VNet 内だが、エージェントはそうとは限らない ことを失敗の起点として説明しています。(TECHCOMMUNITY.MICROSOFT.COM)
- サブネット注入と DNS が正しくなった後に 401 が出る場合は、ネットワークより 認証・認可 の確認に切り替えるべきです。Microsoft はこの状態を「到達できている証拠」と位置づけています。(TECHCOMMUNITY.MICROSOFT.COM)
- private networking でも、すべてのツールが閉域通信になるわけではありません。OpenAPI、Azure Functions、A2A、Private MCP は VNet 経由ですが、Bing Grounding、Websearch、SharePoint Grounding は public endpoint 通信です。(Microsoft Learn)
2026年4月時点で先に固定したい「設定差分」
2026年4月時点の Microsoft 公開情報は、重要ポイントは一貫していますが、構築経路とポータル差分はまだ揺れています。3月13日の「Set up private networking for Foundry Agent Service」は network-secured environment の構築を Bicep/Terraform 前提で案内しています。一方、4月22日の network isolation 記事は、BYO Storage / Search / Cosmos を選び、public network access を Disabled にした場合に限り、Azure portal から VNet injection を作成できる 手順も掲載しています。さらに、tool support 表は new Responses API agents を new Foundry portal または SDK/CLI で作る前提 で、classic portal 生成のエージェントは対象外です。実務では「どのポータル・どの API 世代・どのツール構成で作るか」を最初に固定しないと、設定漏れではなく サポート外の組み合わせ でハマります。(Microsoft Learn)
特に注意したいのは、private AI Search を network-isolated Foundry の agent tool として使うケースです。4月22日時点の公式ドキュメントでは、このシナリオは new Foundry Portal で新しいエージェントを構築すること が前提で、classic portal 側は非対応と明記されています。ブログ要約だけで古いポータル手順を踏襲すると、設計自体が合っていても再現できません。(Microsoft Learn)
導入前チェックリスト
アーキテクチャ前提
- private networking を本気で使うなら、前提は Standard agent setup / BYO resources です。Basic agent setup や managed resources のままでは、VNet injection は使えません。(Microsoft Learn)
- Foundry account、project、Azure Storage、Azure Cosmos DB、Azure AI Search、managed identity、モデル関連リソースは、原則として VNet と同一リージョン にそろえます。リージョン不一致は後からの切り分けを難しくします。(Microsoft Learn)
- Standard と Basic を同じ Foundry account に混在させるより、アカウントを分ける 方が安全です。Capability Host の既定値や運用責任範囲が混ざると、変更時に事故が起きやすくなります。(Microsoft Learn)
- 運用担当や管理者が private Foundry に入る方法は、VPN Gateway、ExpressRoute、Azure Bastion のいずれかで先に決めておきます。ここが未決定だと、構築できても検証が止まります。(Microsoft Learn)
権限とサブスクリプション
- テンプレート展開側には、少なくとも Azure AI Account Owner と、必要リソースへロール割り当てを行える Role Based Access Administrator または Owner が必要です。(Microsoft Learn)
- Capability Host 作成では、Foundry account 側の Contributor と、下流 Azure リソースへのアクセス付与に使う User Access Administrator または Owner が前提です。(TECHCOMMUNITY.MICROSOFT.COM)
- エージェントを作成・編集する運用メンバーには Azure AI User を割り当てます。Owner や Contributor だけで現場運用を回すと、権限が広すぎます。(Microsoft Learn)
- 事前に
Microsoft.KeyVault、Microsoft.CognitiveServices、Microsoft.Storage、Microsoft.MachineLearningServices、Microsoft.Search、Microsoft.Network、Microsoft.App、Microsoft.ContainerServiceを登録します。Bing Search を使うならMicrosoft.Bingも必要です。(Microsoft Learn)
ネットワーク設計
- Agent subnet は
Microsoft.App/environmentsに委任 し、Foundry resource ごとに専用化します。最小は /27、推奨は /24 です。(Microsoft Learn) - 使用できるアドレス帯は RFC1918 の private IPv4 です。特に 172.17.0.0/16 は使わない でください。Docker bridge 予約との衝突要因になります。(Microsoft Learn)
- Firewall を挟む場合は、Managed Identity 関連 FQDN の許可、または
AzureActiveDirectoryサービスタグ追加を検討します。TLS inspection による自己署名証明書の差し込みも失敗原因になります。(Microsoft Learn) - ネットワーク変更を後から吸収する前提で設計しないことが重要です。Capability Host は 更新不可 なので、サブネットや接続先を変える場合は削除して再作成になります。(TECHCOMMUNITY.MICROSOFT.COM)
設定チェックリスト
Foundry resource と inbound 設定
- Foundry resource / project 側の public network access は、private networking 前提なら Disabled を基本にします。inbound private endpoint も合わせて作成します。(Microsoft Learn)
- Azure portal で VNet injection を使う場合、先に BYO Storage / Search / Cosmos を選択 し、public network access を Disabled にしておかないと、VNet injection の UI 自体が出ません。(Microsoft Learn)
- Foundry resource を作っただけでは、Azure AI Search、Azure Storage、Azure Cosmos DB の private endpoint は 自動作成されません。個別に作成して承認状態まで確認します。(Microsoft Learn)
Connections と Capability Host
- Standard setup では、Azure Cosmos DB、Azure Storage、Azure AI Search の project connection を先に作ります。必要なら Azure OpenAI connection も追加します。Capability Host は raw resource ID ではなく、connection name を参照します。(Microsoft Learn)
- Capability Host は account と project の両スコープで使い、project 側が account 側の既定値を上書きします。1 スコープにつき 1 つだけ active にでき、変更時は削除・再作成です。(Microsoft Learn)
- Capability Host の管理は現時点では REST API ベース です。SDK での管理は未提供なので、IaC や運用 runbook 側に GET / PUT / DELETE の確認手順を残しておくべきです。(Microsoft Learn)
Capability Host の存在確認は、会話やポータル画面の記憶ではなく、API で確認した方が早いです。(Microsoft Learn)
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts?api-version=2025-06-01DNS とオンプレ経路
- private DNS zone は、最低でも Foundry、Search、Cosmos、Storage の解決に必要な zone を VNet にリンクします。custom / on-prem DNS を使う場合は、
privatelinkサブドメインを 168.63.129.16 に条件付きフォワードします。(Microsoft Learn) - 検証は「VNet 内のどこか」ではなく、実際に使う agent subnet と同じ DNS 振る舞いを持つ場所 で行います。ブログでも、同じ VNet の VM ではなく 同じサブネット相当の継承関係 を見るべきだと示唆されています。(TECHCOMMUNITY.MICROSOFT.COM)
nslookupが public IP を返すなら、private DNS zone のリンク不足か、条件付きフォワーダー不足を疑います。private endpoint が Approved かどうかも同時に確認します。(Microsoft Learn)
名前解決と 443 疎通の検証は、VNet に接続済みの VM から最低限これだけは実施したいところです。(Microsoft Learn)
nslookup <your-foundry-endpoint-hostname>
Test-NetConnection <private-endpoint-ip-address> -Port 443ツール通信経路とコンプライアンス
- OpenAPI tool、Azure Functions、A2A、Private MCP は your VNet 経由、Azure AI Search は private endpoint 経由です。オンプレ API 接続がテーマなら、まずここに使うツールを寄せるのが基本です。(Microsoft Learn)
- Code Interpreter と Function Calling は Microsoft backbone network を使うため、private endpoint は不要です。逆に、Bing Grounding、Websearch、SharePoint Grounding は public endpoint 通信なので、「すべて閉域」の要件にはそのままでは合いません。(Microsoft Learn)
- Logic Apps、File Search、Browser Automation、Computer Use、Image Generation は、4月22日時点で network-isolated environment では未サポートです。Workflow Agents も outbound の virtual network injection は部分対応に留まります。(Microsoft Learn)
認証設定
- OpenAPI tool の認証方式は
anonymous、API key、managed identityの 3 つです。Bearer token を使う場合も、project connection にAuthorization: Bearer <token>を持たせる構成が取れます。(Microsoft Learn) - API key 認証では、OpenAPI spec に
securitySchemesとsecurityが必要です。managed identity では、対象サービス側のロール割り当てと audience URI が一致していないと 401 になりやすいです。(Microsoft Learn) - したがって、401 はネットワーク確認の終点 であり、認証設定確認の始点です。「まだ閉域化が壊れている」と判断してネットワーク班に戻すと、切り分けが長引きます。(TECHCOMMUNITY.MICROSOFT.COM)
展開順序チェックリスト
- 対象シナリオを固定する。 new portal / SDK / CLI のどれで作るか、Responses API ベースか、使うツールは private 対応かを先に決めます。ここが曖昧だと、後工程の検証結果を読めません。(Microsoft Learn)
- VNet とサブネットを先に設計する。 Agent subnet の委任、アドレス帯、Firewall 経由有無、オンプレ DNS の条件付きフォワード先をここで固めます。(Microsoft Learn)
- BYO リソースを同一リージョンで確保する。 Azure Storage、Cosmos DB、AI Search、必要なら Azure OpenAI を先に決め、private endpoint 方針も同時に設計します。(Microsoft Learn)
- RBAC と provider registration を完了する。 権限不足のまま進めると、Capability Host や private endpoint が Pending / Failed になり、原因が見えにくくなります。(Microsoft Learn)
- Foundry resource / project を作成する。 public network access は Disabled、必要なら inbound private endpoint を作成し、ポータル利用時は BYO resources 選択後に VNet injection を有効化します。(Microsoft Learn)
- Search / Storage / Cosmos の private endpoint を個別作成して承認する。 ここは自動化任せにせず、Approved 状態まで確認します。(Microsoft Learn)
- project connection を作成してから Capability Host を作る。 Connection name を正しく参照しているかを確認し、変更余地が残る項目はこの段階で潰します。更新不可だからです。(Microsoft Learn)
- same-subnet 相当の VM から DNS と 443 を確認する。
nslookupとTest-NetConnectionを通してから、初めて agent 側テストに進みます。(Microsoft Learn) - オンプレ API を呼ぶ OpenAPI tool で疎通試験を行う。 ここで timeout なら経路、401 なら認証、403 なら RBAC / policy を中心に見ます。(TECHCOMMUNITY.MICROSOFT.COM)
- 切り戻し条件も先に決める。 サブネットや接続先変更が入った場合は Capability Host 再作成が必要なので、メンテナンス扱いにする方が安全です。(Microsoft Learn)
周知チェックリスト
ネットワーク担当に伝えること
- 「VM で成功 = agent でも成功」ではありません。Foundry エージェントが subnet injection 済みかを別軸で確認する必要があります。(TECHCOMMUNITY.MICROSOFT.COM)
- private endpoint だけで終わりではなく、Search / Storage / Cosmos の private endpoint、private DNS zone リンク、168.63.129.16 への条件付きフォワーダーまでが 1 セットです。(Microsoft Learn)
- Public endpoint ツールは network isolation 環境でも外向き通信を使います。利用可否をセキュリティレビュー対象に入れておくべきです。(Microsoft Learn)
運用担当に伝えること
- 401 は「まだ届いていない」ではなく、「届いた先で認証に失敗している」可能性が高いです。一次切り分けでネットワーク班に戻しすぎないことが重要です。(TECHCOMMUNITY.MICROSOFT.COM)
- Capability Host は 1 スコープ 1 つで、重複作成は 409 になります。自動化ジョブの再実行設計を入れておかないと、運用で false alarm が増えます。(Microsoft Learn)
- secure setup を削除するときは、Foundry resource を purge してから VNet を消す順序が推奨です。削除順序を誤ると、service association link まわりで後片付けが残ることがあります。(Microsoft Learn)
開発・アプリ担当に伝えること
- OpenAPI spec には
operationIdが必須です。API key を使うならsecuritySchemesとsecurityも必要です。(Microsoft Learn) - 秘密情報はコードや prompt に埋め込まず、project connection に寄せます。Bearer token も connection 管理できます。(Microsoft Learn)
- managed identity を使うなら、対象サービスが Entra ID トークンを受け付けるか、必要ロールが付与されているか、
audが期待値と一致するかまで確認します。(Microsoft Learn)
障害時の切り分けチェックリスト
VM では成功するのに agent だけ失敗する
最初に疑うべきは Capability Host と subnet injection です。社内 DNS、VPN、ExpressRoute の設計そのものが正しくても、agent runtime が対象サブネットに入っていなければ、同じ名前解決経路を継承しません。(TECHCOMMUNITY.MICROSOFT.COM)
nslookup が public IP を返す
private DNS zone の未リンク、custom DNS の条件付きフォワーダー不足、または private endpoint 未承認を疑います。custom DNS なら privatelink サブドメインを 168.63.129.16 に転送しているかを確認します。(Microsoft Learn)
401 / 403 が出る
401 は認証ヘッダー、token audience、project connection の値を優先確認します。403 は RBAC や承認状態、Azure Policy の影響も確認対象です。network issue と決め打ちしないことが重要です。(TECHCOMMUNITY.MICROSOFT.COM)
Capability Host 作成が失敗する
Cosmos / Storage / AI Search の connection 不足、権限不足、provider 未登録、既存 host との競合が主因です。特に secure standard agent では、3 つの BYO resource connection がそろっていないと作成できません。(Microsoft Learn)
Agent 画面の読み込みや作成が異常に遅い
Cosmos DB の private endpoint / DNS / Firewall を見直します。Microsoft のトラブルシューティングでも、Agent pages の timeout は Cosmos 側到達性や Managed Identity 関連 FQDN の許可不足が原因候補として挙げられています。(Microsoft Learn)
最後に、今すぐやるべきこと
まずやるべきことは 4 つです。
1つ目は、対象プロジェクトが Standard / BYO resources 前提 になっているかを棚卸しすること。
2つ目は、account / project の Capability Host が存在し、期待する connection name を参照しているか を API で確認すること。
3つ目は、same-subnet 相当の VM から DNS と 443 を確認すること。
4つ目は、利用予定ツールを VNet 経由・private endpoint 経由・public endpoint 経由 に分類し、公開通信を許容しないツールを先に除外することです。これを済ませてから展開順序どおりに進めれば、発表直後の情報差分があっても、導入判断と切り分けの精度をかなり上げられます。(Microsoft Learn)
コメント