1. はじめに

ローカルで動くエージェントをクラウドへ移すと、コード以外の課題が現れます。例えば「社内文書を検索し、必要なら申請を登録するエージェント」では、回答できるだけでなく、他人の文書を見せないこと、申請を二重登録しないこと、障害時に原因を追えることが求められます。

Microsoft Foundry の Hosted Agents は、独自コードをマネージドな実行基盤に載せる仕組みです。Foundry がエンドポイント、エージェント ID、セッション単位の実行環境などを管理する一方、コードの振る舞い、外部サービスの権限、データの扱い、安全対策は利用側の設計に残ります。[^hosted-concepts]

本記事では、初回デプロイの操作手順ではなく、「動いた」から「継続して任せられる」へ進むための確認ポイントを整理します。製品仕様は出典で示し、そこから導く設計上の推奨とは区別して説明します。

2. 最初に、旧プレビューと現行方式を切り分ける

確認基準日: 2026-09-07。 移行ガイドは、初期パブリックプレビューの旧ホスティング基盤について、サポート期限を 2026-08-20 と案内しています。旧環境は自動移行されず、現行方式での再デプロイが必要です。この記事の確認時点では、その期限を過ぎています。[^hosted-migration]

特に、次の前提が残っていないかを確認してください。

旧方式で見かける前提現行方式で確認すること
start / stop やレプリカ台数を管理するセッション単位の自動起動・アイドル時解放
フレームワーク専用 Hosting Adapter を使うResponses / Invocations などのプロトコル別ライブラリ
プロジェクトのマネージド ID を実行時にも使うエージェント固有の Microsoft Entra ID
共有エンドポイントへ agent_reference を送るエージェント専用エンドポイント
Hosted Agents 用のアカウントレベル Capability Host を手作業で作る現行ホスティング基盤ではプラットフォームが自動構成

この表は Hosted Agents の旧ホスティング方式からの変更点であり、他の用途の Capability Host まで不要とするものではありません。[^hosted-migration]

さらに、コンテナープロトコル 1.0.0 は別の移行対象です。利用者分離の公式文書では、1.0.0 は 2026-07-31 まで動作し、その後は要求をブロックすると説明しています。2.0.0 と、それをサポートする AgentServer SDK を組み合わせてください。[^user-isolation]

公式サンプルにも世代差が残っています。 デプロイ・管理ページには 1.0.0 の例がある一方、利用者分離ページは 2.0.0 への移行を求めています。本記事では後者の廃止告知を優先し、古い例の数字だけをコピーしない方針とします。SDK のパッケージバージョンとコンテナープロトコルのバージョンは別々に管理します。[^hosted-deploy][^hosted-lifecycle][^user-isolation]

3. プロトコルとデプロイ方式を先に決める

3.1 HTTP サーバーが動けばよい、ではない

Foundry とコンテナーの間には実行契約があります。公式のプロトコルライブラリを使い、クライアントが期待する入出力形式と揃えるのが基本です。[^hosted-deploy]

用途選ぶプロトコル注意点
会話型 UI、RAG、複数ターンの対話Responses会話履歴や応答ライフサイクルをプラットフォームと連携できる
Webhook、独自 JSON、独自 SSEInvocations入出力スキーマや会話履歴の管理をアプリが担う
音声などの双方向ストリーミングInvocations（WebSocket）WebSocket 用の invocations_ws を宣言する

例えば Responses 用の Python ライブラリは azure-ai-agentserver-responses、Invocations 用は azure-ai-agentserver-invocations です。複数プロトコルを同じコンテナーで提供することもできますが、実装したルートと、エージェント定義・エンドポイント側の設定を一致させる必要があります。[^hosted-deploy][^hosted-lifecycle]

独自 JSON を扱えることと、外部サービスが認証なしで直接呼び出せることは別です。Webhook の送信元が必要な認証に対応するかを確認し、必要なら認証・検証を担う受信サービスを間に置く設計にします。呼び出し主体にはエンドポイントの利用権限が必要です。[^hosted-permissions]

3.2 コンテナー方式とソースコード方式を混ぜない

現行方式には、ACR へイメージを配置する コンテナー方式と、ZIP をアップロードする ソースコード方式があります。後者は Python / .NET が対象で、依存関係のリモート解決と、ビルド済み依存関係を同梱する方式を選べます。JavaScript/TypeScript SDK からデプロイできることは、ソースコード方式に Node.js のホストランタイムがあることを意味しません。[^source-deployment]

コンテナー方式では、次をデプロイ前に揃えます。[^hosted-deploy]

  • イメージは Linux x86_64（linux/amd64）。ARM マシンでのビルド結果をそのまま使わない
  • ローカルの待ち受けポートは 8088。本番では Foundry のゲートウェイがルーティングする
  • 公式プロトコルライブラリが提供する /readiness を含め、起動と応答を確認する
  • FOUNDRY_PROJECT_ENDPOINT などのプラットフォーム注入変数を再定義しない。FOUNDRY_* は予約済み

設計上は、ソースコード・依存関係・ベースイメージをまとめて再現可能にし、リリースに使ったイメージのダイジェストや ZIP のハッシュを記録することを勧めます。ソースコード方式でも、ネイティブ依存関係の OS・CPU アーキテクチャを意識する必要があります。[^source-deployment]

秘密情報はイメージや設定ファイルへ値のまま埋め込まず、ID 認証や Foundry の接続情報を利用します。接続情報の参照が起動時に解決できないと環境変数が空になる場合があるため、必須設定は起動時に検証し、秘密値をログへ出さずに失敗を通知する実装にします。[^hosted-deploy]

4. ID・権限・利用者の分離を別々に設計する

4.1 「誰が・何を・どこで行うか」を表にする

確認基準日: 2026-09-07。 Foundry のロール名は改称中です。例えば Foundry User は旧 Azure AI User、Foundry Project Manager は旧 Azure AI Project Manager に相当し、改称によってロール ID と中核の権限は変わりません。表示名だけで判断せず、操作とスコープを照合してください。[^hosted-permissions]

主体役割主な権限・スコープの確認点
開発者・デプロイ用 CIエージェントや接続の作成・更新ガイドの代表構成はプロジェクトの Foundry Project Manager。リソース新設やロール割り当ては別途確認
イメージを push する主体ACR へ成果物を登録ACR 上の push 権限。ABAC 対応ロールでは Container Registry Repository Writer
プロジェクトのマネージド ID基盤側のイメージ pullACR 上の pull 権限。実行時のエージェント ID とは別
エージェント固有の Entra IDモデル・ツール・業務データへアクセスプロジェクト経由のモデル推論・セッションストレージは既定アクセスあり。外部リソースは個別に認可
利用者・呼び出し用バックエンドエージェントを呼び出す専用エンドポイントの利用だけなら、プロジェクトまたは個別エージェントの Foundry Agent Consumer を検討

これは代表的な役割分担であり、全操作に対する最小権限の一式ではありません。例えば、構成済み環境でのエージェント作成・更新は Foundry User でも可能ですが、接続作成などは別の権限が必要です。Azure の汎用 Owner / Contributor だけで Foundry のデータプレーン操作まで許可されるわけでもありません。[^hosted-permissions]

ACR では 権限モードも確認します。ABAC 有効のレジストリでは AcrPull / AcrPush は有効にならず、Container Registry Repository Reader / Writer などを使います。リポジトリを限定するには ABAC 条件が必要です。また、Hosted Agents の権限ガイドは ACR の azureADAuthenticationAsArmPolicy が enabled であることを求めています。[^acr-abac][^hosted-permissions]

管理ページの一部には Azure AI Developer を割り当てる例も残っていますが、権限リファレンスは同ロールが Hosted Agents のシナリオに不十分であると明記しています。名前から「開発者ならこれ」と選ばず、権限リファレンスの操作別マトリクスに合わせます。[^hosted-lifecycle][^hosted-permissions]

4.2 共通バックエンド経由では、ユーザー ID だけで分離を保証しない

プロトコル 2.0.0 では、通常の呼び出しは Microsoft Entra トークンの主体を基に利用者が分離されます。ただし、Foundry User を持つ管理・自動化主体は他の利用者のセッションも管理できます。一般利用者へ開発・管理用ロールを配らないことが重要です。[^user-isolation]

自社アプリのバックエンドが一つの資格情報で代理呼び出しする場合、x-ms-user-identity で利用者を識別する仕組みがあります。このヘッダーの利用には、既定の組み込みロールに含まれない UserIdentityImpersonation/action のデータ権限をカスタムロールで付与する必要があります。[^user-isolation]

特に重要なのは、公式文書が、委任された利用者同士の境界をプラットフォームだけでは強制しないと警告している点です。二人を同じセッションへルーティングすると、データを共有してしまいます。[^user-isolation]

そのため、バックエンド側で次を実装します。

  • 認証済みのサーバー側情報から利用者識別子を作る。ブラウザーが送った値をそのまま信用しない
  • テナント・利用者とセッション ID の対応を保持し、既存セッションを使うたびに所有権を検証する
  • 別の利用者のセッション ID を指定した要求や、ファイルの取得要求が拒否されることを確認する

ローカル実行では利用者分離が強制されないため、分離の確認はデプロイ済み環境でも行います。なお、セッションを利用者に関連付けることと、下流の業務 API にユーザー委任権限でアクセスすることは分けて設計してください。[^user-isolation][^hosted-concepts]

5. 会話履歴・ファイル・処理途中の進捗を分ける

5.1 同じセッション ID だけでは会話履歴を引き継がない

セッションは実行環境とファイル、Conversation は対話履歴です。Responses では次の違いがあります。[^hosted-sessions]

指定するもの引き継ぐ対象・注意点
conversation会話履歴を保持し、対応するセッションも自動的に関連付ける
previous_response_id前の応答から対話を継続する。ファイルも再利用するなら agent_session_id を別途渡す
agent_session_id だけ同じセッションのファイル・作業状態を利用する。過去のメッセージをモデルへ自動再投入する指定ではない

Invocations にはプラットフォーム管理の会話履歴がありません。また、セッション ID の指定場所は Responses ではリクエスト本文、Invocations ではクエリパラメーターです。Invocations の JSON 本文に同名フィールドを書くだけでは、基盤側のルーティング指定になりません。[^hosted-sessions]

5.2 永続化される場所と保持期限を確認する

確認基準日: 2026-09-07。 現行方式では、$HOME と /files 経由でアップロードした内容がターン間・アイドル期間をまたいで保持されます。計算リソースが解放されても、同じセッションの再開時に復元されます。一方、30 日間操作がないセッションは削除されると説明されています。[^hosted-concepts]

「コンテナーだから全ファイルが毎回消える」も、「ファイルが残るからメモリー上の変数や処理スタックも残る」も正しくありません。重要な業務データの保管先と、セッションの作業領域は分ける設計にします。[^hosted-concepts][^long-running-resilience]

容量にも注意が必要です。1 vCPU 以上のセッションではディスク予算は最大 20 GiB ですが、約 20% はシステム用で、残りをイメージ・$HOME・その他の書き込み領域が共有します。小さい CPU 区分では予算も比例して小さくなります。20 GiB 全量をユーザーファイルに使える前提にはできません。[^hosted-concepts]

5.3 バックグラウンド実行と耐障害実行は別

background: true は、最初の HTTP 接続を保持せずに処理を続けるための仕組みです。プロセス停止後の復旧まで自動的に保証する指定ではありません。Responses の耐障害実行は、保存されるバックグラウンド応答に対し、サーバー側で対応機能を有効にする条件があります。[^long-running-resilience]

復旧時はハンドラーの先頭から再び入るため、途中のローカル変数は復元されません。設計上は、完了した工程のチェックポイントを永続化し、申請登録・メール送信などの副作用には冪等性キーや処理済み記録を持たせます。例えば申請登録の応答を受け取れずに中断した場合、再開時には同じ申請番号で登録済みかを照会し、無条件にもう一度登録しないようにします。[^long-running-resilience]

提供状態の注意（確認基準日: 2026-09-07）: 長時間処理の耐障害実行は Preview として説明され、SLA なし・本番ワークロード非推奨の注記があります。Agent Service 全体の提供状態から、この機能まで同じ保証があると判断しないでください。[^long-running-resilience]

6. 閉域化は Foundry アカウントを作る前に決める

確認基準日: 2026-09-07。 Hosted Agents はネットワーク分離された Foundry リソースと、利用者が用意する VNet を使った通信に対応しています。ただし、Hosted Agents の VNet injection は Foundry アカウントの初回作成時に指定する必要があり、既存アカウントへの後付けはサポートされません。[^hosted-concepts][^private-networking]

「まず公開ネットワークで PoC を作り、同じアカウントを後で閉域化する」ことを前提にしないでください。閉域化が必須なら、その条件を満たす環境を先に作るか、別環境への移行を計画します。

ACR にも作成時期による条件があります。公式文書では、2026-06-25 より後に作成された Foundry プロジェクトは private ACR をサポートし、それより前のプロジェクトは ACR の public endpoint への到達性が必要とされています。ACR の作成日ではなく、Foundry プロジェクトの作成時期が条件である点に注意します。[^private-networking]

通信経路は少なくとも次の四つに分けて確認します。

経路設計・確認すること
クライアント・CI → Foundry入口の Private Endpoint、接続元のネットワーク、DNS
基盤 → ACRイメージ pull の到達性、プロジェクト ID の権限、作成時期による制約
エージェント → モデル・ツール・業務データ出口の VNet 統合、宛先の Private Endpoint・DNS・認可
エージェント → 認証・監視・依存サービスFirewall / NSG の許可先と、デプロイ時に必要な通信

Foundry の入口を Private Endpoint にしただけでは、出口側の通信設定は完成しません。ソースコード方式にも mcr.microsoft.com などの必要な送信先があるため、採用方式に応じた許可先を確認します。公式ネットワーク手順は、DNS、Firewall / NSG、依存リソースごとの Private Endpoint を個別に扱っています。[^private-networking][^source-deployment]

また、ホスティングできるリージョンと、使いたいモデル・ツール・データの配置条件は別々に確認します。Hosted Agents の現行提供一覧には Japan East / Japan West が含まれますが、それだけでシステム全体のデータ処理が国内に収まると判断せず、外部連携先までデータ経路を確認する設計にします。[^hosted-concepts]

7. 性能と料金は「同時セッション × 稼働時間」で考える

7.1 CPU・メモリーはセッション単位の割り当て

確認基準日: 2026-09-07。 設定値はエージェント全体ではなく 一つのセッションのサイズを表します。現行の設定と、容量・費用設計で見るべき点を分けると次のようになります。[^hosted-concepts][^hosted-sessions]

設定・単位現行仕様設計上の確認点
セッションの CPU・メモリー0.5 vCPU / 1 GiB、1 vCPU / 2 GiB、2 vCPU / 4 GiB同時セッション分の割り当てになる
アイドルタイムアウト5〜60 分、既定 15 分。各要求でタイマーをリセット最後の要求から計算リソースを解放するまでの時間
レプリカ・ウォームプール台数を指定する方式ではない固定台数ではなくセッションの発生・継続時間で見積もる

idle_timeout_seconds を変える場合は、新しいエージェントバージョンを作ります。[^hosted-sessions]

容量設計では、CPU・メモリーを大きくする前に、代表的な入力で使用量を測ります。さらに、次を切り分けて測定することを勧めます。

  • 初回・アイドル後の再開にかかる時間と、継続中の応答時間
  • 同時セッション数と、セッション内でのモデル・ツール呼び出し数
  • 大きな添付ファイル、長い会話、遅い外部 API がある場合の使用量
  • モデルのクォータや外部 API のレート制限に達した場合の再試行・利用者への通知

タイムアウトを短くすれば再開の頻度が増え、長くすれば要求の合間も計算リソースを保持する時間が増えます。応答時間と費用の両面で、利用間隔に合う値を決めます。[^hosted-concepts]

7.2 ホスティング料金とモデル料金を分ける

Hosted Agents には、モデル・ツールの利用料に加え、コンテナー計算リソースの料金があります。料金ページはコンテナー compute の時間単位課金、概念ページはアクティブなセッションの CPU・メモリー消費に基づく課金を説明しています。「マネージドだから無料」「モデルのトークン代だけ」という見積もりにはできません。[^agent-pricing][^hosted-concepts]

見積もりは、次の項目を分けて作ると漏れを減らせます。

  • 各セッションの CPU・メモリーと稼働時間の合計
  • モデルの入出力トークン、ツール利用料、接続先のライセンス
  • 採用構成に含まれる ACR、ストレージ、ネットワークなどの関連リソース
  • Application Insights / Log Analytics などの監視費用

モデル・ツールと compute が別項目であることは料金ページ、Application Insights に追加費用が発生し得ることはデプロイガイドで確認できます。地域・契約別の単価や、Hosted ランタイムに適用される契約上の SLA の具体値は本記事では未確認のため、採用機能を含む価格票・契約条件で最終確認してください。[^agent-pricing][^hosted-deploy]

8. バージョン更新・監視・安全対策を運用に組み込む

8.1 新しいバージョンの作成と、利用者への切り替えを分ける

更新、切り替え、一時停止、削除は同じ操作ではありません。管理仕様を次のように分けて運用手順に落とし込みます。[^hosted-concepts][^hosted-lifecycle]

操作変更されるもの注意点
新バージョンの作成イメージ・計算リソース・環境変数・プロトコル設定の新しいスナップショット通常バージョンはイミュータブル。active 到達とルーティングを別々に確認する
エンドポイントのバージョン選択要求を送る先一度に一つのバージョンへ 100%。バージョン間のトラフィック分割は非対応
disableエンドポイントを無効化し、要求を拒否構成・バージョンは残る。計算リソースのアイドル時解放とは別
エージェント全体の削除エージェントと全バージョンを削除し、アクティブなセッションを終了元に戻せない。一時的に利用を止める操作とは分ける

設計上は検証用のエージェントまたは環境で動作を確認し、切り替え対象と戻し先のバージョンを記録します。5% ずつ流すカナリア配信が標準機能として使える前提にはしません。azd deploy はルーティングも自動構成するため、「バージョンを追加するだけ」の操作と見なさず、デプロイの影響範囲を確認します。[^hosted-lifecycle]

公式 Quickstart の Python SDK の例にも注意が必要です。この例は試験用バージョンへ一時的にルーティングし、終了処理で元の設定に戻して、作成したバージョンを削除します。常設ホスト用に使う場合は、後片付けを含む例の目的を理解してから、リリース・切り戻し・削除の手順を分離してください。[^hosted-quickstart]

現行方式に旧来の compute の手動 start / stop を持ち込んだり、エンドポイントを無効化した瞬間に関連費用がすべて止まると見積もったりしないでください。[^hosted-lifecycle][^hosted-migration]

8.2 コンテナーログと分散トレースを使い分ける

起動失敗や標準出力の確認にはコンテナーログ、モデル・ツール呼び出しをまたぐ処理の追跡には Application Insights のトレースを使います。プラットフォームは接続文字列を注入し、公式プロトコルライブラリを利用するエージェントは既定で OpenTelemetry トレースを出力します。独自処理のどこまで記録されるかは、実際のトレースで確認します。[^hosted-concepts][^hosted-deploy][^hosted-lifecycle]

運用上は、エージェント名・バージョン・セッション・要求の対応を追えるようにし、少なくとも次を区別できる構成を勧めます。

  • イメージ取得・起動・readiness の失敗
  • エンドポイントの呼び出し拒否と、下流リソースのアクセス拒否
  • モデル待ち・ツール待ち・処理中断・キャンセル
  • 新バージョンへの切り替え後に起きた品質・応答時間の変化

トレースには個人情報や顧客コンテンツが含まれ得ます。記録対象、マスキング、保存期間、閲覧権限を先に決め、トークン・接続シークレット・業務文書全文を無条件に出力しない実装にします。[^hosted-deploy]

8.3 ホストされたことと、ガードレールが適用されたことは別

Hosted Agents のコンテンツ安全性ガードレールは、エージェント定義の rai_config で設定します。公式文書では、rai_config 自体を省略するとエージェントのコンテンツ安全性ガードレールは付かず、rai_config はあるが rai_policy_name がない場合は既定ポリシーが使われます。組織のポリシーを使うなら、対象 RAI ポリシーの完全な ARM リソース ID を指定して適用を確認します。[^hosted-guardrails]

それでも、業務ツールの実行を文章の安全性フィルターだけに任せない設計が必要です。例えば申請登録なら、引数検証、利用者の業務権限確認、重要操作の承認、重複実行防止をツール側に実装します。外部の MCP サーバーやモデルへ送る情報についても、保存・利用・所在地の条件を確認する責任が利用側に残ります。[^hosted-concepts]

なお、同じ RAI ポリシーで扱う Network egress controls は Preview です。2026-09-07 時点の公式文書には SLA なし・本番利用を意図しない旨が明記されています。VNet の対応状況やコンテンツ安全性の設定と一括りにせず、機能単位で導入可否を判断してください。[^hosted-guardrails]

9. 導入前チェックリスト

前章までの確認を、設計レビューやリリース判定では次の形にまとめられます。

  • 旧ホスティング基盤・廃止プロトコルを前提にせず、採用 SDK とプロトコルの組み合わせを固定した
  • デプロイ方式、起動処理、readiness、依存関係、秘密情報の渡し方を確認した
  • デプロイ主体・プロジェクトのマネージド ID・エージェント ID・呼び出し主体を区別し、対象スコープへ必要な権限だけを与えた
  • 共通バックエンドで利用者とセッションの所有権を検証し、他人のセッション・ファイルへのアクセスを拒否した
  • 会話継続とファイル継続を分け、アイドル後の再開、保持期限、容量不足時の扱いを確認した
  • 長時間処理の中断・再実行・キャンセルと、副作用の重複防止を確認した
  • VNet の作成時制約、private ACR の適用条件、入口・出口・DNS・CI の接続経路を確認した
  • 同時セッション数とアイドル時間を含む負荷・費用を見積もり、モデルや外部 API の制限も確認した
  • 新バージョンのルーティング、切り戻し、エンドポイント無効化、不要リソースの後片付けを手順化した
  • ガードレール、トレースの機密情報、閲覧権限、品質評価、および機能別の Preview・SLA 条件を確認した

10. まとめ

Hosted Agents を使うときの要点は、ホスティング基盤が管理する範囲と、アプリが保証する範囲を切り分けることです。現行のセッション型モデルを前提に、ID と利用者境界、状態の保持、ネットワーク、稼働時間に応じた費用を設計します。

そのうえで、復旧時に安全に再実行できること、バージョンを戻せること、必要なログを機密情報を守りながら追えることまで揃えると、デプロイ後の運用判断がしやすくなります。過去のサンプルを使う際は、特にプロトコル・権限・ライフサイクルの世代差を確認してください。

11. 参考情報

[^hosted-concepts]: What are hosted agents? — Microsoft Learn（確認日: 2026-09-07）

[^hosted-migration]: Migrate hosted agents to the latest version — Microsoft Learn（確認日: 2026-09-07）

[^hosted-deploy]: Deploy a hosted agent — Microsoft Learn（確認日: 2026-09-07）

[^source-deployment]: Deploy a hosted agent from source code — Microsoft Learn（確認日: 2026-09-07）

[^hosted-permissions]: Hosted agent permissions reference — Microsoft Learn（確認日: 2026-09-07）

[^acr-abac]: Azure attribute-based access control (Azure ABAC) repository permissions in Azure Container Registry — Microsoft Learn（確認日: 2026-09-07）

[^user-isolation]: Isolate hosted agent sessions per user — Microsoft Learn（確認日: 2026-09-07）

[^hosted-sessions]: Manage hosted agent sessions — Microsoft Learn（確認日: 2026-09-07）

[^long-running-resilience]: Resilience for long-running Microsoft Foundry hosted agents (preview) — Microsoft Learn（確認日: 2026-09-07）

[^private-networking]: Set up private networking for Foundry Agent Service — Microsoft Learn（確認日: 2026-09-07）

[^agent-pricing]: Foundry Agent Service pricing — Microsoft Azure（確認日: 2026-09-07）

[^hosted-lifecycle]: Manage hosted agents — Microsoft Learn（確認日: 2026-09-07）

[^hosted-quickstart]: Quickstart: Deploy your first hosted agent — Microsoft Learn（確認日: 2026-09-07）

[^hosted-guardrails]: Add guardrails to a hosted agent — Microsoft Learn（確認日: 2026-09-07）