Microsoft Foundry / Azure OpenAIで「自社コードのAIエージェントを本番環境に載せたい」と考えているなら、2026年4月更新のDeploy a hosted agentは必ず確認すべき内容です。結論から言うと、今回のポイントは、コンテナー化したエージェントコードをFoundry Agent Serviceへデプロイし、Python SDKまたはREST APIから直接バージョン作成・状態確認・呼び出しまで管理できるように整理されたことです。初回構築はazdやVS Code拡張機能、運用自動化やCI/CD連携はPython SDKまたはREST API、という使い分けが現実的です。(Microsoft Learn)
Hosted agentは、単なるプロンプト設定型のエージェントではありません。LangChain、Microsoft Agent Framework、Semantic Kernel、独自実装などで作った処理ロジックをコンテナーにまとめ、Microsoft Foundryのマネージド基盤上で実行するための仕組みです。モデル呼び出しだけでなく、権限、コンテナー起動、セッション、監視、バージョン管理まで含めて設計する必要があるため、IT管理者・プロダクトオーナー・Microsoftエコシステムの開発チームは、デプロイ前に要件を整理しておくことが重要です。(Microsoft Learn)
Microsoft Foundry / Azure OpenAIの最新動向: Deploy a hosted agentで何が変わったか
2026年4月更新の「Deploy a hosted agent – Microsoft Foundry」は、Hosted Agentsを「どう作るか」ではなく、「作ったエージェントをどう運用に載せるか」に焦点を当てています。
特に重要なのは、次の4点です。
| 更新ポイント | 実務上の意味 |
|---|---|
| Python SDKまたはREST APIによるデプロイ手順が明確化 | CI/CD、社内ポータル、運用ツールからHosted agentを直接作成・更新しやすい |
| コンテナー要件が具体化 | linux/amd64、ポート8088、プロトコルライブラリ、環境変数の扱いを事前に確認できる |
| RBACとエージェントIDの説明が整理 | Azure AI Project Manager、Azure AI User、ACR関連ロールの設計ミスを防ぎやすい |
| Responses / Invocationsプロトコルの使い分けが明確化 | チャット型、Webhook型、非会話処理など、ユースケースに合わせた設計ができる |
Microsoft公式ドキュメントでは、Hosted agentのデプロイは「ビルドとプッシュ」「エージェントバージョン作成」「状態確認」「専用エンドポイント呼び出し」という流れで説明されています。これは、従来のWebアプリやAPIデプロイに近い考え方でAIエージェントを管理できることを意味します。(Microsoft Learn)
Hosted agentとは何か
Hosted agentは、自社で作ったAIエージェントのコードをコンテナーイメージとしてAzure Container Registryに配置し、Foundry Agent Service上で実行する仕組みです。
プロンプトだけで構成するエージェントと違い、Hosted agentでは以下のような実装を持ち込めます。
- 独自のオーケストレーションロジック
- 社内APIや業務システムとの連携
- LangChainやMicrosoft Agent Frameworkなどのフレームワーク
- Webhookや独自JSONを受け取る処理
- CPUやメモリを指定した実行環境
- セッション単位の状態管理やファイル利用
つまり、Hosted agentは「チャットボットを作る機能」ではなく、「コードベースのAIエージェントをMicrosoft Foundry上でホストする機能」と理解すると分かりやすいです。
例えば、社内FAQに答えるだけのボットなら、プロンプト型エージェントで十分な場合があります。一方で、顧客データを参照し、承認フローを確認し、複数APIを呼び分け、処理結果を監査ログに残すような用途では、Hosted agentのほうが向いています。
まず押さえるべきデプロイの全体像
Hosted agentの基本フローは、次の4段階です。
| 手順 | 内容 | 確認すべきポイント |
|---|---|---|
| ビルドとプッシュ | エージェントコードをコンテナー化し、Azure Container Registryへプッシュ | linux/amd64でビルドしているか、タグが一意か |
| バージョン作成 | Foundry Agent Serviceにイメージを登録 | CPU、メモリ、プロトコル、環境変数が正しいか |
| 状態確認 | activeになるまでポーリング | failed時にerrorフィールドを確認する運用にしているか |
| 呼び出し | 専用エンドポイントにリクエストを送信 | ResponsesかInvocationsか、呼び出し方式を統一しているか |
特に運用で重要なのは、「デプロイ=即利用可能」ではない点です。エージェントバージョンを作成した後は、状態がactiveになったことを確認してから呼び出す必要があります。Microsoft公式ドキュメントでも、バージョン作成後に状態をポーリングし、activeになってから呼び出す流れが示されています。(Microsoft Learn)
初回構築はazdまたはVS Code、運用自動化はSDK/APIが向いている
Hosted agentのデプロイ方法は、大きく分けて3つあります。
| 方法 | 向いている読者 | 主な用途 |
|---|---|---|
| Azure Developer CLI（azd） | 初めて試す開発者、PoC担当者 | サンプル作成、ローカルテスト、初回デプロイ |
| VS Code拡張機能 | GUIで作業したい開発者 | プロジェクト作成、デバッグ、Playground確認 |
| Python SDK / REST API | IT管理者、SRE、Platform Engineering、製品チーム | CI/CD、自動デプロイ、社内ツール連携、複数環境管理 |
初めてHosted agentを試すなら、azdまたはVS Code拡張機能を使うほうが早いです。クイックスタートでは、サンプルプロジェクトの作成、ローカルテスト、Foundry Agent Serviceへのデプロイ、Playgroundでの検証までを一連の流れで実行できます。(Microsoft Learn)
一方、プロダクトとして継続運用するなら、Python SDKまたはREST APIを使う設計を検討すべきです。理由は、リリースパイプラインに組み込みやすく、エージェントのバージョン、イメージタグ、リソース割り当て、環境変数をコードで管理できるからです。
たとえば、次のような運用にはSDK/APIが適しています。
- GitHub ActionsやAzure DevOpsから新しいエージェントバージョンを作成する
- ステージング環境で
activeになったことを確認してから本番へ反映する - 複数プロダクトのエージェントを社内ポータルから一元管理する
- 監査のため、どのコンテナーイメージがどのバージョンに紐づくか記録する
Python SDKでのデプロイで確認すべきポイント
Python SDKを使う場合、Microsoft公式ドキュメントではazure-ai-projects>=2.1.0が前提として示されています。コンテナーイメージはAzure Container Registryに配置し、エージェント作成時にイメージURL、CPU、メモリ、プロトコル、環境変数などを指定します。(Microsoft Learn)
実装時に特に見落としやすいのは、次の3点です。
| 確認項目 | 失敗例 | 対策 |
|---|---|---|
| イメージタグ | latestを使い、どのコードが動いているか分からなくなる | my-agent:20260424-001のように一意のタグを使う |
| CPU・メモリ | PoCの設定をそのまま本番に使い、応答遅延や失敗が起きる | 想定リクエスト量と処理内容に応じて検証する |
| 環境変数 | モデル名や外部API設定をコードに直書きする | environment_variablesで明示し、秘密情報は適切な管理方式を検討する |
公式ドキュメントでも、再現可能なデプロイのために:latestではなく一意のイメージタグを使うことが推奨されています。これは、障害発生時の切り戻しや監査対応でも重要です。(Microsoft Learn)
SDK/API運用での実務チェックリスト
デプロイを自動化する場合は、パイプラインに次の確認を入れておくと安全です。
| フェーズ | チェック内容 |
|---|---|
| ビルド前 | 対象ブランチ、モデルデプロイ名、Foundryプロジェクト、ACR名を確認 |
| ビルド時 | linux/amd64でイメージを作成 |
| プッシュ時 | 一意のタグを付け、ACRへのpush権限を確認 |
| バージョン作成時 | cpu、memory、container_protocol_versions、環境変数を検証 |
| デプロイ後 | activeになるまでポーリングし、failedならエラー内容を保存 |
| 呼び出し確認 | ResponsesまたはInvocationsのテストリクエストを送る |
| リリース後 | ログ、メトリック、利用コストを監視 |
このチェックリストを作らずにPoCの手順だけで本番化すると、「コンテナーは作れたがFoundry側でプルできない」「権限不足でモデルを呼べない」「どのバージョンが本番か分からない」といった問題が起きやすくなります。
ResponsesとInvocationsの使い分け
Hosted agentでは、コンテナーがFoundryゲートウェイと通信するためにプロトコルライブラリを使います。主な選択肢はResponsesとInvocationsです。Microsoft公式ドキュメントでは、Responsesは会話型チャットボット、ストリーミング、複数ターンの対話に向き、InvocationsはWebhook、非会話処理、カスタム非同期ワークフローに向くと説明されています。(Microsoft Learn)
| プロトコル | 向いている用途 | 判断基準 |
|---|---|---|
| Responses | チャット、アシスタント、RAG、ストリーミング、複数ターン対話 | OpenAI互換の/responses形式で扱いたい場合 |
| Invocations | Webhook、分類、抽出、バッチ処理、独自JSON | 入出力スキーマを自社側で自由に決めたい場合 |
| 両方 | チャットUIと外部システム連携を同じエージェントで扱う場合 | container_protocol_versionsに両方を指定する |
迷った場合は、会話型アプリならResponsesから始めるのが自然です。GitHub、Jira、Stripeなど外部サービスから独自ペイロードを受けるWebhook型の処理では、Invocationsを選ぶほうが設計しやすくなります。Hosted agentは両方のプロトコルを同時に公開できるため、将来的に用途が増える可能性がある場合は、拡張性も考えて設計しておくとよいでしょう。(Microsoft Learn)
コンテナー要件で失敗しやすいポイント
Hosted agentのデプロイで最初につまずきやすいのは、AIモデルやプロンプトではなくコンテナーです。
Microsoft公式ドキュメントでは、ホスティング基盤がx86_64、つまりlinux/amd64のコンテナーイメージを要求すると説明されています。Apple SiliconなどARMベースの端末でビルドする場合は、docker build --platform linux/amd64 .のように明示しないと、互換性のないARMイメージを作ってしまう可能性があります。(Microsoft Learn)
docker build --platform linux/amd64 -t myagent:v1 .また、コンテナーはローカルではポート8088でトラフィックを処理します。本番環境ではFoundryゲートウェイがルーティングを担うため、コンテナー側でパブリックポートを公開する必要はありません。(Microsoft Learn)
ローカルテストは本番デプロイ前に必ず実施する
Hosted agentでは、ローカルでも本番と同じエンドポイント形式で動作確認できます。Responsesなら/responses、Invocationsなら/invocationsを呼び出します。(Microsoft Learn)
POST http://localhost:8088/responses
Content-Type: application/json
{
"input": "What can you do?",
"stream": false
}POST http://localhost:8088/invocations
Content-Type: application/json
{
"message": "Hello!"
}ローカルテストで確認すべきなのは、単に「返答があるか」だけではありません。次の観点まで見ると、本番移行後のトラブルを減らせます。
| 観点 | 確認内容 |
|---|---|
| 起動 | 依存パッケージのインストール漏れがないか |
| 認証 | Azure認証やモデル呼び出しが失敗しないか |
| 入力形式 | Responses / Invocationsのペイロードが正しいか |
| 例外処理 | 外部API失敗時に適切なエラーを返すか |
| ログ | 障害調査に必要な情報が出ているか |
| レイテンシ | 初回起動や外部API待ちで許容範囲を超えないか |
RBACとID設計はIT管理者が最初に見るべき部分
Hosted agentの本番導入では、RBAC設計が非常に重要です。
Microsoft公式ドキュメントでは、Hosted agentを作成・デプロイするにはプロジェクトスコープのAzure AI Project Managerが必要と説明されています。このロールには、エージェント作成のためのデータプレーン権限と、プラットフォームが作成するエージェントIDにAzure AI Userロールを割り当てる権限が含まれます。(Microsoft Learn)
また、デプロイ時にはHosted agentごとに専用のMicrosoft EntraエージェントIDが作成されます。このIDは、実行中のコンテナーがモデルやツールを呼び出すために使うサービスプリンシパルです。管理者が手動でマネージドIDを構成する必要はありませんが、エージェント作成者にはそのIDへAzure AI Userを割り当てる権限が必要です。(Microsoft Learn)
権限設計の実務例
| ロール・権限 | 主な用途 | 管理上の注意 |
|---|---|---|
| Azure AI Project Manager | Hosted agentの作成・デプロイ | 開発者全員に広く付与せず、デプロイ担当やCI/CD主体に限定する |
| Azure AI User | エージェントIDがモデルやツールへアクセス | 実行時アクセスとして必要 |
| Container Registry Repository Reader | Foundry側がACRからイメージをプル | 付与漏れはimage_pull_failedやACR認証系エラーの原因になる |
| Container Registry Repository Writer / AcrPush | イメージをACRへプッシュ | CI/CDやビルド担当に必要 |
PoCでは自分のアカウントに広い権限を付けて進めがちですが、本番では「誰がデプロイできるか」「どのエージェントがどのモデル・ツールにアクセスできるか」「CI/CDのサービスプリンシパルに何を許可するか」を分けて考える必要があります。
Azure Container Registryはパブリックエンドポイント到達性に注意
2026年4月更新の内容で、特にエンタープライズ環境のIT管理者が注意すべき点があります。Hosted agentのコンテナーイメージを保持するAzure Container Registryは、現時点ではパブリックエンドポイント経由で到達可能である必要があります。プライベートエンドポイントの背後に置き、パブリックネットワークアクセスを無効化したレジストリは、Hosted agentでは現在サポートされていません。Foundry側がイメージをプルできないためです。(Microsoft Learn)
これは、金融、医療、公共、グローバル企業のようにネットワーク分離を重視する環境では大きな設計ポイントです。
ただし、Foundry Agent Service全体としては、Standard Setup with private networkingにより、隔離されたネットワーク環境、サブネット統合、プライベートリソースアクセスを構成できる説明もあります。ネットワーク要件は機能ごとに制約が異なるため、「Foundryはプライベートネットワーク対応だからACRも完全プライベートでよい」と単純に判断しないことが重要です。(Microsoft Learn)
ネットワーク設計で確認すべきこと
| 確認項目 | 判断基準 |
|---|---|
| ACRの到達性 | Hosted agent基盤がイメージをプルできる構成か |
| 社内データソース | プライベート接続が必要なデータベースや検索基盤があるか |
| データ所在地 | エージェントが外部ツールや第三者サービスにデータを送る可能性があるか |
| 監査要件 | どのエージェントがどのリソースへアクセスしたか記録できるか |
| 環境分離 | 開発、検証、本番でACR・Foundryプロジェクト・モデルを分けるか |
エンタープライズ導入では、AIエージェントの性能よりも先に、ACR、Foundryプロジェクト、モデルデプロイ、ログ、ネットワーク、IDをまとめたアーキテクチャ図を作ることをおすすめします。
プラットフォーム注入の環境変数を再定義しない
Hosted agentでは、Foundryプラットフォームが実行時にいくつかの環境変数を自動注入します。たとえば、Foundryプロジェクトエンドポイント、ARMリソースID、エージェント名、エージェントバージョン、セッションID、Application Insights接続文字列などです。FOUNDRY_*プレフィックスはプラットフォーム用途として予約されています。(Microsoft Learn)
実務上の注意点は、これらをagent.yamlやSDKのenvironment_variablesで再定義しないことです。再定義すると、意図しない値の上書きや設定の混乱につながります。
自分で設定すべき環境変数は、たとえば次のようなものです。
| 変数例 | 用途 |
|---|---|
MODEL_DEPLOYMENT_NAME | 利用するモデルデプロイ名 |
APP_ENV | dev、staging、prodなどの環境識別 |
LOG_LEVEL | ログ出力レベル |
TOOL_ENDPOINT | 社内ツールやMCPサーバーのエンドポイント |
FEATURE_FLAG_* | 機能切り替え |
秘密情報を環境変数で扱う場合は、組織のセキュリティ基準に従い、Key VaultやCI/CDのシークレット管理と組み合わせる設計を検討してください。
REST APIはPlatform Engineeringと社内ツール連携に向いている
REST APIによるデプロイは、Python SDKを使わない環境や、既存の社内運用ツールからHosted agentを管理したい場合に便利です。公式ドキュメントでは、Foundry Agent Serviceのエンドポイントに対して、エージェント作成、バージョン状態確認、ResponsesまたはInvocationsの呼び出し、新しいバージョン作成を行う例が示されています。(Microsoft Learn)
REST APIが向いているケースは次の通りです。
- 社内のリリース管理システムからエージェントを作成する
- Azure DevOps、GitHub Actions、GitLab CIなどからHTTPで直接操作する
- 複数言語のチームが共通のAPI仕様で運用する
- 管理画面からエージェントのバージョンや状態を表示する
- Python依存を避けたいPlatform Engineeringチームが利用する
REST APIを使う場合も、SDKと同様に「バージョン作成後にactiveを待つ」「失敗時はerror.codeとerror.messageを記録する」「イメージタグを固定する」という基本は変わりません。
トラブルシューティングで最初に見るべきエラー
Hosted agentのデプロイ失敗は、コンテナー、ACR、RBAC、ネットワークのどれかに原因があることが多いです。Microsoft公式ドキュメントでは、プロビジョニングエラーはバージョンオブジェクトのerror.codeとerror.messageに表示されると説明されています。(Microsoft Learn)
| エラー例 | よくある原因 | 最初に確認すること |
|---|---|---|
image_pull_failed | イメージURI誤り、ACRプル権限不足 | イメージ名、タグ、ACR Reader権限 |
InvalidAcrPullCredentials | マネージドIDまたはレジストリRBACの問題 | Foundryプロジェクトの管理IDとACR権限 |
UnauthorizedAcrPull | 認可不足 | ACR側のロール割り当て |
AcrImageNotFound | タグ未作成、push漏れ、名前違い | ACRに該当イメージが存在するか |
RegistryNotFound | レジストリ名、DNS、到達性の問題 | ACR名、リージョン、ネットワーク設定 |
SubscriptionIsNotRegistered | 必要なAzureリソースプロバイダー未登録 | サブスクリプションのプロバイダー登録 |
トラブル対応では、いきなりコードを直すのではなく、次の順番で切り分けると効率的です。
- ACRに対象タグのイメージが存在するか確認する
- Foundryプロジェクトの管理IDにACR読み取り権限があるか確認する
- エージェント作成者またはCI/CD主体に必要なRBACがあるか確認する
- コンテナーが
linux/amd64でビルドされているか確認する - ローカルで
/responsesまたは/invocationsが動作するか確認する - バージョンの
error.codeとerror.messageを確認する
この順番で見ると、AIモデルやプロンプトの問題ではないインフラ起因の障害を早く見つけられます。
プロダクトオーナーが判断すべき導入基準
Hosted agentは強力ですが、すべてのAI機能に必要なわけではありません。導入判断では、「エージェントをコードとして管理する必要があるか」を基準にすると分かりやすいです。
| 要件 | Hosted agentを使うべきか |
|---|---|
| FAQ回答や単純な社内チャット | 必須ではない。プロンプト型や既存エージェント機能で十分な場合がある |
| 複数APIを呼び分ける業務エージェント | 向いている |
| Webhookを受けて自動処理するAIワークフロー | InvocationsでのHosted agentが向いている |
| RAG、ツール、会話履歴を組み合わせた顧客対応 | ResponsesでのHosted agentを検討 |
| 厳密なリリース管理・監査が必要 | バージョン管理できるHosted agentが向いている |
| ネットワークを完全閉域化したい | ACR到達性などの制約を事前確認すべき |
Hosted agentを採用する価値が高いのは、AIエージェントを「機能」ではなく「プロダクト」として継続改善する場合です。コードレビュー、テスト、CI/CD、バージョン管理、ログ監視、権限設計を含めて運用するなら、Hosted agentは有力な選択肢になります。
本番化前に決めておきたい設計項目
Microsoft Foundry / Azure OpenAIでHosted agentを本番運用する前に、次の設計を決めておくと後戻りを減らせます。
| 設計項目 | 決めること |
|---|---|
| エージェント名 | 環境や用途が分かる命名規則にする |
| イメージタグ | latestを避け、リリースIDや日付を含める |
| プロトコル | Responses、Invocations、または両方 |
| モデルデプロイ名 | 環境ごとに分けるか、共通化するか |
| CPU・メモリ | 初期値ではなく負荷試験で決める |
| ロール割り当て | 人間、CI/CD、エージェントIDを分けて整理する |
| ログ設計 | セッションID、エージェントバージョン、リクエストIDを追跡できるようにする |
| 切り戻し | 旧バージョンを保持するか、再デプロイで戻すか |
| コスト管理 | 不要なリソースやテスト環境を削除する手順を用意する |
特にグローバル向けサービスでは、リージョン、データ保管、外部ツール連携、第三者モデルやサービスの利用条件も確認が必要です。Hosted Agentsを第三者システム、第三者コード、第三者モデルと組み合わせる場合は、データ共有、保持、所在地、責任あるAI対策を利用者側で管理する必要があるとMicrosoftは説明しています。(Microsoft Learn)
2026年4月更新を踏まえた実務アクション
今回のDeploy a hosted agent更新は、Microsoft Foundry / Azure OpenAIを使うチームにとって、Hosted agentをPoCから運用へ進めるための実装ガイドとして重要です。
次に取るべき行動は、チームの立場によって変わります。
| 立場 | 次にやること |
|---|---|
| IT管理者 | RBAC、ACR到達性、ネットワーク、監査ログの要件を確認する |
| 開発者 | azdまたはVS Codeでサンプルを動かし、Responses / Invocationsの違いを試す |
| Platform Engineering | Python SDKまたはREST APIでバージョン作成と状態確認をCI/CDに組み込む |
| プロダクトオーナー | Hosted agentが必要なユースケースか、プロンプト型で足りるかを判断する |
| セキュリティ担当 | エージェントID、外部ツール連携、データ境界、責任あるAI対策を確認する |
最初の一歩としては、1つの小さな業務ユースケースを選び、ローカルテスト、ACRプッシュ、バージョン作成、active確認、専用エンドポイント呼び出しまでを一度通してみるのが効果的です。そのうえで、本番化するエージェントだけをSDK/API管理に移行すると、無理なく運用設計を固められます。
Microsoft Foundry / Azure OpenAIのHosted agentは、AIエージェントを「試作」から「運用可能なソフトウェア」へ近づけるための仕組みです。2026年4月更新の要点は、コンテナー、バージョン、RBAC、プロトコル、API管理を明確に押さえること。まずは初回デプロイをazdまたはVS Codeで確認し、その後にPython SDKやREST APIで自動化する流れが、実務では最も失敗しにくい進め方です。
コメント