Azure AI Foundryで独自コードのAIエージェントを運用したい場合、今回確認すべきポイントは明確です。Deploy a hosted agent - Microsoft Foundry は、コンテナー化したエージェントコードを Foundry Agent Service にデプロイし、Python SDKまたはREST APIからバージョン作成・状態確認・呼び出しまで管理するための公式手順です。
結論として、管理者は RBAC、エージェントID、Azure Container Registry、ネットワーク制約、監視、コスト管理 を先に確認する必要があります。開発者は linux/amd64イメージ、Responses／Invocationsプロトコル、環境変数、バージョン管理、active 状態確認 を押さえてから展開するのが安全です。本記事は、2026年5月9日時点で確認した公式情報をもとに整理しています。なお、対象のMicrosoft Learnページ上では最終更新日が2026-05-08と表示されています。(Microsoft Learn)
Azure AI FoundryのHosted Agentデプロイで何が変わるのか
Azure AI FoundryのHosted Agentは、プロンプトだけで定義するエージェントではなく、開発者が書いたコードをコンテナーとして実行する方式です。エージェントコードをAzure Container Registryへプッシュし、Foundry Agent Serviceにエージェントバージョンとして登録すると、プラットフォーム側がインフラのプロビジョニング、専用のMicrosoft EntraエージェントID、専用エンドポイントを用意します。(Microsoft Learn)
これにより、開発者はAzure Container Appsや独自Webサーバーを細かく組み立てるよりも、エージェントのロジックに集中しやすくなります。一方で、デプロイ前に確認すべき設定は増えます。特にACRの到達性、プロジェクトのマネージドID、エージェントIDへのロール割り当て、プロトコル選択を誤ると、デプロイは成功しても実行時にモデルやツールへアクセスできない可能性があります。
| 観点 | これまで意識しがちな作業 | Hosted Agentで重要になる作業 |
|---|---|---|
| 実行環境 | Webアプリ、Container Apps、Functionsなどを個別に設計 | Foundry Agent Serviceにコンテナーを登録 |
| 認証 | アプリ側のマネージドIDやシークレットを個別管理 | 専用のEntraエージェントIDとRBACを確認 |
| デプロイ | アプリケーション単位のリリース管理 | エージェントバージョン単位で管理 |
| 呼び出し | 自前のAPIエンドポイント | Foundryの専用エンドポイント |
| 監視 | アプリ側でApplication Insightsを構成 | プラットフォーム注入の接続情報とトレースを活用 |
| 注意点 | インフラ構成の自由度が高い | ACR、プロトコル、ネットワーク制約を守る必要がある |
デプロイの基本フローは「Build → Version → Active → Invoke」
公式手順で示されているHosted Agentのライフサイクルは、次の4段階です。
| 手順 | 内容 | 実務での確認ポイント |
|---|---|---|
| Build and push | エージェントコードをコンテナー化し、ACRへプッシュ | linux/amd64でビルドし、:latestではなく一意のタグを使う |
| Create an agent version | イメージをFoundry Agent Serviceに登録 | CPU、メモリ、プロトコル、環境変数を正しく指定 |
| Poll for status | バージョンがactiveになるまで待つ | failed時はerror.codeとerror.messageを確認 |
| Invoke | 専用エンドポイントへリクエスト | ResponsesまたはInvocationsのエンドポイントを使い分ける |
初回デプロイや検証目的であれば、Azure Developer CLI（azd）やVS Code拡張機能を使うルートが最短です。これらはビルド、プッシュ、バージョン管理、基本的なRBAC構成を自動化します。一方、自社のCI/CDや管理システムから直接デプロイを制御したい場合は、Python SDKまたはREST APIを使うのが適しています。(Microsoft Learn)
管理者が最初に確認すべき設定
Hosted Agentの展開で失敗しやすいのは、コードそのものよりも権限とネットワークです。特にAzure AI Foundryでは、Azure Resource Managerの権限とFoundryデータプレーンの権限が分かれるため、「Ownerだから全部できる」「Contributorだからエージェントも作れる」と考えると詰まりやすくなります。
| 確認項目 | 必要な内容 | 失敗しやすいポイント |
|---|---|---|
| エージェント作成者の権限 | プロジェクトスコープでAzure AI Project Managerが推奨 | Azure AI Userだけでは、エージェントIDへAzure AI Userを割り当てる権限が不足する場合がある |
| ACRへのプッシュ | デプロイ担当者にContainer Registry Repository WriterまたはAcrPush | CI/CDのサービスプリンシパルに権限を付け忘れる |
| ACRからのプル | FoundryプロジェクトのマネージドIDにContainer Registry Repository ReaderまたはAcrPull | エージェントIDではなく、プロジェクトのマネージドIDに付与する点を間違える |
| エージェント実行時のアクセス | プラットフォーム作成のエージェントIDにAzure AI User | モデルやツールを呼べず、実行時エラーになる |
| 外部サービス利用 | Storage、Azure AI Search、Key Vaultなどに必要な追加権限 | コア設定だけで下流リソースも使えると誤解する |
| ACRのネットワーク | ACRはパブリックエンドポイントで到達可能にする必要がある | Private Endpointのみ、Public Network Access無効のACRは現在サポート外 |
Microsoftの権限リファレンスでは、Hosted Agentの開発にはユーザー、Foundryプロジェクト、エージェントそれぞれに異なる権限が関係すると説明されています。また、Azure AI DeveloperロールはHosted Agentシナリオでは不十分とされているため、既存のAI開発者向けロールをそのまま流用する前に見直しが必要です。(Microsoft Learn)
開発者が押さえるべきコンテナー要件
Hosted Agentのコンテナーは、通常のWebアプリ用コンテナーと同じ感覚で作ると失敗することがあります。特に重要なのは、アーキテクチャ、ポート、プロトコルライブラリ、環境変数です。
linux/amd64イメージでビルドする
ホスティングプラットフォームでは、x86_64、つまりlinux/amd64のコンテナーイメージが必要です。Apple Silicon搭載MacなどARMベースのマシンでビルドする場合は、次のようにプラットフォームを明示します。(Microsoft Learn)
docker build --platform linux/amd64 -t myagent:v1 .実務では、CI/CD側でも同じ指定を入れておくべきです。ローカルでは動くのにFoundry上で起動しない場合、ARMイメージを誤ってプッシュしているケースがあります。
:latestではなく一意のタグを使う
再現可能なデプロイにするには、myagent:v1、myagent:20260509-001、GitコミットSHAなど、一意のイメージタグを使います。公式手順でも、:latestではなく一意のタグの利用が推奨されています。(Microsoft Learn)
latestを使うと、どのコードがどのエージェントバージョンで動いているか追跡しづらくなります。障害発生時の切り戻しや監査にも不向きです。
ローカルでは8088番ポートで検証する
Hosted Agentのコンテナーはローカルでは8088番ポートでトラフィックを処理します。本番環境ではFoundryゲートウェイがルーティングするため、コンテナー側でパブリックポートを公開する必要はありません。(Microsoft Learn)
ローカル検証では、Responsesプロトコルなら/responses、Invocationsプロトコルなら/invocationsを叩きます。デプロイ前にここで入出力、ストリーミング、エラー処理を確認しておくと、クラウド側の切り分けが楽になります。
ResponsesとInvocationsは用途で選ぶ
Hosted Agentでは、Foundryゲートウェイと通信するためにプロトコルライブラリを使います。主な選択肢は、ResponsesプロトコルとInvocationsプロトコルです。1つのコンテナーで両方を公開することもできます。(Microsoft Learn)
| プロトコル | 向いている用途 | 特徴 |
|---|---|---|
| Responses | 会話型チャットボット、ストリーミング、マルチターン会話 | OpenAI互換の/responsesコントラクトを使える。会話履歴、ストリーミング、バックグラウンド実行をプラットフォームに任せやすい |
| Invocations | Webhook、非会話処理、独自JSON、長時間の非同期処理 | /invocationsで任意のJSONを受け取れる。スキーマ、状態管理、ポーリングなどを自分で設計しやすい |
迷った場合はResponsesから始めるのが現実的です。会話型UI、ストリーミング、履歴管理を使う多くのエージェントではResponsesが扱いやすいからです。一方、GitHub、Jira、社内システムのWebhookを受ける処理や、分類・抽出・バッチ処理のような非チャット用途ではInvocationsが合います。
Python SDKでデプロイする場合の要点
Python SDKを使う場合は、Azure AI Projects SDK 2.1.0以降が必要です。コードから直接エージェントバージョンを作成し、プロビジョニング状態を確認し、activeになってから呼び出します。(Microsoft Learn)
最小構成の考え方は次のとおりです。
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential
PROJECT_ENDPOINT = "https://resource_name.services.ai.azure.com/api/projects/project_name"
credential = DefaultAzureCredential()
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=credential,
allow_preview=True,
)
agent = project.agents.create_version(
agent_name="my-agent",
definition=HostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(
protocol=AgentProtocol.RESPONSES,
version="1.0.0"
)
],
cpu="1",
memory="2Gi",
image="myregistry.azurecr.io/myagent:v1",
environment_variables={
"MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
}
)
)ここで重要なのは、create_versionが単なるメタデータ登録ではなく、エージェントのプロビジョニングを開始する操作であることです。別途「起動」コマンドを実行するのではなく、バージョン作成後にcreatingからactiveへ遷移するのを待ちます。(Microsoft Learn)
REST APIでデプロイする場合の要点
REST APIは、HTTPベースの独自ツールやCI/CDに組み込みたい場合に向いています。エージェント作成時にdefinition.kindをhostedにし、イメージ、CPU、メモリ、プロトコル、環境変数を指定します。エージェント作成時にはバージョン1も作られ、プロビジョニングが始まります。(Microsoft Learn)
curl -X POST "$BASE_URL/agents?api-version=v1" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "my-agent",
"definition": {
"kind": "hosted",
"image": "myacr.azurecr.io/my-agent:v1",
"cpu": "1",
"memory": "2Gi",
"container_protocol_versions": [
{"protocol": "responses", "version": "1.0.0"}
],
"environment_variables": {
"MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
}
}
}'REST APIでInvocationsを呼ぶ場合は、専用エンドポイントに対してリクエストします。公式例ではFoundry-Features: HostedAgents=V1Previewヘッダーが使われています。プレビュー機能を扱うため、APIバージョンや必要ヘッダーは本番導入前に必ず最新の公式情報で確認してください。(Microsoft Learn)
環境変数は「自動注入」と「自分で定義」を分ける
Hosted Agentでは、プラットフォームが実行時に一部の環境変数を自動注入します。代表的なものは、Foundryプロジェクトのエンドポイント、プロジェクトARM ID、エージェント名、バージョン、セッションID、Application Insights接続文字列です。FOUNDRY_*プレフィックスはプラットフォーム用に予約されています。(Microsoft Learn)
| 種類 | 例 | 扱い方 |
|---|---|---|
| プラットフォーム注入 | FOUNDRY_PROJECT_ENDPOINT、FOUNDRY_AGENT_NAME、APPLICATIONINSIGHTS_CONNECTION_STRING | agent.yamlやSDKのenvironment_variablesで再宣言しない |
| アプリ側で定義 | MODEL_DEPLOYMENT_NAME、MCPエンドポイント、業務用設定値 | agent.yamlまたはSDK／RESTの環境変数として指定 |
| シークレット系 | APIキー、接続文字列など | 平文で埋め込まず、必要に応じてKey VaultやIDベース認証を検討 |
よくあるミスは、FOUNDRY_*系の値を自分で上書きしようとすることです。Foundryが注入する値とアプリ固有の設定値を分けて管理すると、環境差分のトラブルを減らせます。
移行・展開時に注意すべきポイント
Hosted Agentはプレビュー段階の機能です。既存のAzure Container Appsベースの構成や、旧バージョンのazd ai agent拡張を使っている場合は、新しいバックエンド向けの手順と混同しないようにしてください。クイックスタートでは、新しいバックエンドのHosted Agentsにはazd ai agent 0.1.27-preview以降が必要で、Azure Container Appsを使うレガシー体験では0.1.25-previewを使うよう案内されています。(Microsoft Learn)
| 状況 | 確認すべきこと |
|---|---|
| 既存のContainer Appsベース構成がある | 新バックエンドへ移すのか、既存構成を維持するのかを決める |
azdやVS Codeで初回構築する | 拡張機能のバージョン、権限、作成されるリソースを確認する |
| Python SDK／RESTで自動化する | SDKバージョン、APIバージョン、プレビュー指定、ステータスポーリングをCI/CDに組み込む |
| 社内ネットワーク制約が厳しい | ACRがパブリックエンドポイントで到達可能である必要がある点を事前にレビューする |
| 本番運用に入れる | プレビュー機能であること、リージョン、クォータ、SLA要件を確認する |
特にセキュリティ部門との調整では、「ACRを完全にプライベート化できるか」が論点になりやすいです。現時点では、Hosted Agentのコンテナーイメージを保持するACRはパブリックエンドポイント経由で到達可能である必要があります。プライベートエンドポイントかつパブリックネットワークアクセス無効のACRはサポートされていません。(Microsoft Learn)
ネットワークとリージョンの確認は後回しにしない
Hosted Agentは、ネットワーク分離されたFoundryリソース内でのデプロイや、送信トラフィックに顧客提供のAzure Virtual Networkを使う構成をサポートします。ただし、ACRのパブリック到達性の制約は別問題です。また、ホストされたエージェントでネットワークインジェクションを使う場合、Foundryアカウント作成時に仮想ネットワーク構成を含める必要があり、作成後に既存アカウントへ追加することはサポートされていません。(Microsoft Learn)
リージョンも重要です。公式ドキュメントではHosted Agentはプレビュー段階とされ、利用可能リージョンの一覧には東日本も含まれています。ただし、この一覧は更新される前提のため、本番設計では対象リージョン、モデル可用性、社内データ所在要件をあわせて確認してください。(Microsoft Learn)
監視とコスト管理で見るべきところ
Hosted AgentはApplication Insightsとの連携を前提にしやすい構成です。プラットフォームはApplication Insights接続文字列を環境変数として注入し、プロトコルライブラリを使うエージェントはOpenTelemetryトレースを出力できます。トラブルシューティングでは、エージェントのログ、プロビジョニング状態、リクエスト単位のトレースを合わせて確認します。(Microsoft Learn)
コスト面では、アイドル状態の扱いを理解しておく必要があります。公式手順では、エージェントコンピューティングは非アクティブ状態が15分続くとプロビジョニング解除され、要求を処理していない場合はコンピューティングコストが発生しないと説明されています。一方で、モデル利用、ACR、Log Analytics、Application Insightsなど周辺リソースのコストは別途発生し得ます。(Microsoft Learn)
よくある失敗と対処法
デプロイで詰まった場合は、まずバージョンオブジェクトのstatus、error.code、error.messageを確認します。公式手順では、代表的なプロビジョニングエラーと対処が示されています。(Microsoft Learn)
| エラー・症状 | 主な原因 | 対処 |
|---|---|---|
image_pull_failed | イメージURI誤り、ACRプル権限不足 | イメージ名・タグを確認し、プロジェクトのマネージドIDにContainer Registry Repository Readerを付与 |
InvalidAcrPullCredentials | マネージドIDまたはレジストリRBACの問題 | ACR側のロール割り当てとスコープを確認 |
UnauthorizedAcrPull | 認証または権限不足 | 正しいIDに正しいACR権限を付与 |
AcrImageNotFound | イメージ名・タグが存在しない | ACRに対象タグがプッシュ済みか確認 |
RegistryNotFound | レジストリ名、DNS、ネットワーク到達性の問題 | ACRの存在、ログインサーバー名、パブリック到達性を確認 |
| 呼び出し前に失敗する | バージョンがまだactiveでない | creating中は呼び出さず、ポーリングでactiveを待つ |
| モデルやツールにアクセスできない | エージェントIDや下流リソースの権限不足 | Azure AI UserやStorage/Search/Key Vault側のデータプレーン権限を確認 |
| ローカルでは動くがクラウドで起動しない | ARMイメージ、プロトコル不一致、環境変数不足 | linux/amd64、container_protocol_versions、自動注入変数の扱いを確認 |
管理者・開発者が今すぐやるべきチェックリスト
Azure AI FoundryでHosted Agentを試す前に、次の順で確認すると手戻りを減らせます。
| 優先度 | チェック項目 | 担当 |
|---|---|---|
| 高 | Hosted Agentを使うリージョンとプレビュー利用可否を確認する | 管理者 |
| 高 | Foundryプロジェクト、モデルデプロイ、ACR、Application Insightsの構成を整理する | 管理者・DevOps |
| 高 | エージェント作成者、CI/CD、プロジェクトのマネージドID、エージェントIDのRBACを設計する | 管理者 |
| 高 | ACRがHosted Agentから到達可能か確認する | 管理者・ネットワーク担当 |
| 高 | linux/amd64、一意のイメージタグ、ローカル8088番ポートでの検証をCI/CDに入れる | 開発者 |
| 中 | ResponsesとInvocationsのどちらを使うか決める | 開発者 |
| 中 | FOUNDRY_*自動注入変数とアプリ独自環境変数を分ける | 開発者 |
| 中 | バージョン作成後のactiveポーリングとfailed時のログ取得を自動化する | DevOps |
| 中 | Application InsightsとOpenTelemetryトレースの確認方法を決める | DevOps |
| 中 | 検証後の削除手順とコスト監視を用意する | 管理者 |
まずは小さなHosted Agentで検証する
今回のDeploy a hosted agent - Microsoft Foundry更新で重要なのは、Azure AI Foundry上で独自コードのエージェントをマネージドに実行できる一方、デプロイは「コンテナーを置けば終わり」ではないという点です。ACR、RBAC、エージェントID、プロトコル、環境変数、バージョン状態の確認まで含めて設計する必要があります。
最初の一歩としては、非本番のFoundryプロジェクトでResponsesプロトコルの小さなエージェントを作り、linux/amd64でビルドし、ACRへ一意タグでプッシュし、Python SDKまたはREST APIでバージョン作成からactive確認、呼び出しまでを通すのがよいでしょう。そのうえで、社内CI/CD、監視、権限、ネットワーク要件に合わせて本番展開の設計へ進めるのが安全です。
コメント