Azure AI Foundryでエージェント開発を始めるなら、今回押さえるべきポイントは「Hosted Agentをコンテナ化してFoundry Agent Serviceへデプロイする流れ」と「権限・ACR・監視・プレビュー機能の扱い」です。Microsoft Learnの2026年5月8日更新の「What’s new」では、Quickstart: Deploy your first hosted agent が更新記事として掲載されています。一方、該当クイックスタート本文のページ表示上の最終更新日は2026年4月23日です。そのため本稿では、2026年5月8日更新一覧に含まれた公式情報として、実務で確認すべき変更点と影響範囲を整理します。(Microsoft Learn)
結論から言うと、このQuickstartは「Azure AI Foundry上で、独自コードを含むAIエージェントをHosted Agentとして動かすための最短手順」です。開発者はAzure Developer CLIまたはVS Code拡張機能を使って、サンプル作成、ローカルテスト、Azureへのデプロイ、Playgroundでの確認まで進められます。管理者は、Azure AI Project Manager、Azure AI User、Azure Container Registryのプル権限、Application Insightsの監視設定を事前に確認しておく必要があります。(Microsoft Learn)
Azure AI FoundryのHosted Agentとは
Azure AI FoundryのHosted Agentは、独自のエージェントコードをコンテナイメージとしてパッケージし、Foundry Agent Service上で実行する仕組みです。プロンプトだけで定義するエージェントとは異なり、PythonやC#のコード、任意のフレームワーク、外部ツール連携、カスタム処理を含められる点が特徴です。(Microsoft Learn)
Hosted Agentを使うと、開発者は次のようなエージェントをAzure AI Foundry上で運用しやすくなります。
- Web検索やMCPツールを呼び出す業務支援エージェント
- LangGraph、Semantic Kernel、Microsoft Agent Frameworkなどを使った独自ワークフロー
- TeamsやMicrosoft 365 Copilot連携を見据えた対話型エージェント
- Webhook、分類、抽出、バッチ処理など、チャット以外の入力を扱うエージェント
公式Quickstartでは、Foundryモデルを呼び出し、Foundryツールを利用するコンテナ化AIエージェントをデプロイします。最終的にはFoundry Playgroundからエージェントと対話できる状態になります。(Microsoft Learn)
何が変わったのか：今回の更新で見るべきポイント
今回の更新で重要なのは、単に「新しいクイックスタートがある」という点ではありません。管理者と開発者にとっては、Hosted Agentのデプロイ体験、権限設計、ランタイムの前提が明確になったことが実務上のポイントです。
| 観点 | 確認すべき内容 | 実務への影響 |
|---|---|---|
| デプロイ方法 | Azure Developer CLIまたはVS Code拡張機能からHosted Agentを作成・デプロイできる | 初回検証はIaCやSDKよりもQuickstartが速い |
| ランタイム | Hosted Agentはscale-to-zeroを使い、アイドル時は一定時間後にコンピュートが解除される | コールドスタートやセッション保持を考慮した設計が必要 |
| 権限 | 作成・デプロイにはAzure AI Project Managerが推奨される | Contributorだけではデータプレーン操作やロール割り当てで詰まりやすい |
| ACR | エージェントのコンテナイメージはAzure Container Registryに置く | ACRのプル権限とネットワーク到達性が重要 |
| 監視 | Application InsightsとOpenTelemetryトレースが利用される | 本番化前にログ・トレース確認の運用を決める必要がある |
| プレビュー | Hosted Agentsはプレビュー機能として扱われている | 本番導入では変更リスク、制限、サポート範囲を確認する |
特に注意したいのは、Quickstartが「Hosted Agents on the new backend」を対象としており、azd ai agent の 0.1.27-preview 以降が必要とされている点です。レガシー体験としてAzure Container Appsを使う場合は 0.1.25-preview を継続利用する案内になっているため、既存検証環境を持つチームはバージョンを混在させないようにしましょう。(Microsoft Learn)
影響を受ける利用者とシステム範囲
今回のQuickstartは、Azure AI Foundryを使うすべての利用者に直ちに影響するものではありません。影響が大きいのは、エージェントを単なるプロンプト設定ではなく、独自コードを含むアプリケーションとして運用したいチームです。
影響が大きいチーム
次のいずれかに当てはまる場合は、今回の内容を確認する価値があります。
- Azure AI FoundryでAIエージェントを試作している
- Azure OpenAIやFoundryモデルを使った社内AIアプリを開発している
- LangChain、LangGraph、Semantic KernelなどのフレームワークをAzure上で動かしたい
- MCP、Web Search、File Search、Code Interpreterなどのツール連携を検討している
- TeamsやMicrosoft 365 Copilotへの将来展開を見据えている
- Azure Container AppsやApp Serviceで個別にエージェント基盤を作るか迷っている
影響が限定的なケース
一方で、次のようなケースでは急いで移行する必要はありません。
- Prompt Agentだけで十分な用途
- 既存のAzure FunctionsやApp Serviceで安定稼働している簡易API
- コンテナ化やRBAC設計をまだ検討していないPoC初期段階
- プレビュー機能を本番利用できない社内ルールがある環境
Hosted Agentは強力ですが、コンテナ、権限、監視、ネットワークを含む運用対象になります。プロンプトだけで完結する用途にまで無理に適用すると、構成が複雑になりすぎることがあります。
管理者が最初に確認すべき設定
Azure AI FoundryのHosted Agentで失敗しやすいのは、コードそのものよりも権限とリソース構成です。特に企業環境では、開発者がAzureサブスクリプションのOwner権限を持っていないことが多いため、Quickstartを始める前に管理者側で準備しておくとスムーズです。
必須ロールと権限の確認
公式ドキュメントでは、Hosted Agentの作成とデプロイにはプロジェクトスコープのAzure AI Project Managerが必要とされています。このロールには、エージェント作成に必要なデータプレーン権限と、プラットフォームが作成するエージェントIDにAzure AI Userロールを割り当てるための権限が含まれます。(Microsoft Learn)
| 対象 | 推奨される確認内容 | よくある失敗 |
|---|---|---|
| 開発者ユーザー | FoundryプロジェクトスコープでAzure AI Project Managerを付与 | Contributorだけ付与していてエージェント作成に失敗する |
| エージェントID | Foundryプロジェクトに対してAzure AI Userが必要 | デプロイ後にモデルやツールへアクセスできない |
| FoundryプロジェクトのマネージドID | ACRに対するContainer Registry Repository ReaderまたはAcrPullが必要 | AcrPullUnauthorized や image pull failed が発生する |
| デプロイ担当のユーザーまたはサービスプリンシパル | ACRへイメージをpushできる権限が必要 | コンテナイメージを登録できない |
| 監視担当者 | Application InsightsまたはLog Analyticsの閲覧権限が必要 | メトリックは見えてもトレースを確認できない |
ここで重要なのは、AzureのOwnerやContributorが万能ではないことです。Microsoft FoundryではARMの管理プレーンだけでなく、Foundryのデータプレーン権限も関係します。たとえば、Contributorがあってもエージェントの作成や対話に必要なデータプレーン権限が不足する場合があります。(Microsoft Learn)
Azure Container Registryの到達性を確認する
Hosted Agentでは、コンテナイメージをAzure Container Registryに格納します。公式ドキュメントでは、Hosted Agentが利用するACRは現時点でパブリックエンドポイントから到達可能である必要があり、プライベートエンドポイントでパブリックネットワークアクセスを無効化したACRはサポートされないと説明されています。(Microsoft Learn)
セキュリティを重視する組織ほど、ACRをプライベートネットワーク内に閉じる設計を採用している場合があります。その場合、Hosted Agentの検証では次のどちらかを判断してください。
| 選択肢 | 向いているケース | 注意点 |
|---|---|---|
| Hosted Agent用に到達可能なACRを用意する | QuickstartやPoCを進めたい | ネットワーク制限と社内ポリシーの整合性を確認する |
| 既存のプライベートACR設計を維持する | 本番セキュリティ要件が厳しい | Hosted Agentの現行制限により利用できない可能性がある |
| Azure Container Appsなど別基盤を継続する | 既存運用が安定している | Foundry Agent Serviceの管理機能は使えない |
開発者が確認すべき前提条件
Quickstartを実行する開発者は、ローカル環境とAzure側の準備を分けて確認しましょう。特に、CLIや拡張機能のバージョン違いは原因特定に時間がかかります。
ローカル環境の前提
公式Quickstartでは、Python 3.10以降、Azure Developer CLI 1.24.0以降、Visual Studio Code、Microsoft Foundry Toolkit for VS Code拡張機能が前提として挙げられています。(Microsoft Learn)
| 項目 | 確認コマンド・確認方法 | 注意点 |
|---|---|---|
| Python | python --version | 3.10以上を使う |
| Azure Developer CLI | azd version | 1.24.0以上が必要 |
| azd agent extension | azd ext list | azure.ai.agents が入っているか確認 |
| VS Code拡張機能 | Extensions画面で確認 | プレビュー版への切り替えが必要な場合がある |
| Azure認証 | azd auth login | 認証エラー時はログアウト・再ログインする |
azd ai agent init が失敗する場合は、まず azd version と azd ext list を確認します。公式ドキュメントでは、azure.ai.agents 拡張機能を 0.1.27-preview 以降へ更新することも案内されています。(Microsoft Learn)
azd version
azd ext list
azd ext upgrade azure.ai.agentsサンプルにMCPツールを使わない場合の注意
Quickstartでは、Web Searchや任意のMCPツールを使うサンプルが扱われます。MCPサーバーを使わないのにツール付きサンプルを選んだ場合、agent.yaml の接続ID設定を残したままにすると構成不整合の原因になります。
公式手順では、MCPサーバーを使わない場合、agent.yaml にある AZURE_AI_PROJECT_TOOL_CONNECTION_ID の行をコメントアウトまたは削除するよう案内されています。(Microsoft Learn)
- name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
value: <CONNECTION_ID_PLACEHOLDER>この設定が残っていると、「ツール接続を使う前提のサンプルなのに接続先が存在しない」という状態になります。初回検証では、まずWeb Searchだけ、またはツールなしの最小構成で動作確認し、その後MCPや社内API連携を追加するのが安全です。
デプロイ手順の全体像
Quickstartの基本的な流れは、サンプル作成、リソースプロビジョニング、ローカルテスト、デプロイ、Playground確認、クリーンアップです。
Azure Developer CLIで進める場合
Azure Developer CLIを使う場合は、空のディレクトリでHosted Agentプロジェクトを初期化します。
azd ext install azure.ai.agents
azd ai agent init
azd provision
azd ai agent run
azd ai agent invoke --local "What is Microsoft Foundry?"
azd deployazd provision では、Foundryプロジェクト、モデルデプロイ、Azure Container Registry、Application Insights、Log Analytics Workspace、マネージドIDなどが作成されます。公式Quickstartでは、検証後に azd down でリソースを削除し、課金を止めることが案内されています。(Microsoft Learn)
azd downただし、既存のリソースグループを使っている場合は注意が必要です。azd down はQuickstartで作ったものだけでなく、対象リソースグループ内の関連リソースを削除する可能性があります。検証では専用のリソースグループを使うのが安全です。
VS Codeから進める場合
VS Code拡張機能を使う場合は、コマンドパレットからFoundryプロジェクトの作成、モデルデプロイ、Hosted Agentプロジェクト作成、ローカルテスト、デプロイまで進められます。公式Quickstartでは、Microsoft Foundry ToolkitとFoundry拡張機能のプレリリース版を使うよう案内されています。(Microsoft Learn)
VS Codeから進める場合の流れは次の通りです。
| 手順 | 操作 | 確認ポイント |
|---|---|---|
| Foundryプロジェクト作成 | Microsoft Foundry: Create Project | サブスクリプションとリソースグループを確認 |
| モデルデプロイ | Microsoft Foundry: Open Model Catalog | 対象リージョンで利用可能なモデルを選ぶ |
| Hosted Agent作成 | Microsoft Foundry: Create new Hosted Agent | Python/C#、Responses/Invocationsを選択 |
| ローカルテスト | F5または python main.py | http://localhost:8088/ で起動するか確認 |
| Azureへデプロイ | Microsoft Foundry: Deploy Hosted Agent | ACR、CPU、メモリ構成を選ぶ |
| Playground確認 | Hosted AgentsツリーからPlaygroundを開く | 応答とログを確認する |
GUI中心で試せるため、初回検証や開発者向けハンズオンにはVS Code方式が向いています。一方、CI/CDや再現性を重視する場合は、Azure Developer CLIやSDK、REST APIによる管理を検討しましょう。
ResponsesとInvocationsはどちらを選ぶべきか
Hosted Agentでは、コンテナがResponsesまたはInvocationsのプロトコルを公開します。どちらを選ぶかで、クライアント設計や状態管理が変わります。
| プロトコル | 向いている用途 | 判断基準 |
|---|---|---|
| Responses | チャットボット、アシスタント、RAG、ストリーミング、複数ターン対話 | OpenAI互換のResponses APIとして扱いたい場合 |
| Invocations | Webhook、分類、抽出、独自JSON入力、非会話型処理 | 入力・出力スキーマを自分で決めたい場合 |
| 両方 | チャットUIと業務APIの両方を提供したい場合 | 同じコンテナで複数の呼び出し口を持ちたい場合 |
公式ドキュメントでは、迷った場合はResponsesから始め、必要に応じてInvocationsを追加できると説明されています。Responsesは会話履歴、ストリーミング、バックグラウンド実行などをプラットフォーム側で扱いやすいため、一般的なAIアシスタント用途では最初の選択肢になります。(Microsoft Learn)
scale-to-zeroとセッション保持の実務上の注意
Hosted Agentは、アイドル状態が続くとコンピュートを解除し、次のリクエストで復元するscale-to-zeroの動作を取ります。公式Quickstartでは、約15分の非アクティブ後にアイドルコンピュートが解除され、次回リクエスト時に自動復元されると説明されています。また、セッションは状態を保持し、最大30日間持続できます。(Microsoft Learn)
この仕様はコスト面では有利ですが、アプリ設計では次の点に注意が必要です。
| 注意点 | 起きやすい問題 | 対策 |
|---|---|---|
| コールドスタート | 久しぶりのリクエストで応答開始が遅くなる | UIに「処理開始まで数秒かかる場合があります」と表示する |
| セッション依存 | セッションIDを失うと状態を復元できない | クライアント側で会話ID・セッションIDを適切に保持する |
| 一時ファイル | コンテナ内の作業ファイルを永続ストレージと誤解する | $HOME や /files の扱いを仕様に沿って設計する |
| 長時間処理 | 同期処理だけで待たせる | Responsesのbackground実行やポーリング設計を検討する |
| 負荷試験 | 初回リクエストと連続リクエストで性能差が出る | ウォーム時・コールド時を分けて測定する |
特に社内チャットボットとして使う場合、朝一番や昼休み明けの初回アクセスでコールドスタートが目立つ可能性があります。PoCの段階から「初回応答時間」と「連続利用時の応答時間」を分けて記録しておきましょう。
コンテナ設計で失敗しやすいポイント
Hosted Agentはマネージドな実行基盤ですが、実体はコンテナ化されたアプリケーションです。コンテナの作り方が不適切だと、Foundry側の設定が正しくても起動しません。
linux/amd64イメージを使う
公式のデプロイ記事では、Hosted Agentのプラットフォームは x86_64、つまり linux/amd64 のコンテナイメージを要求すると説明されています。Apple SiliconなどARMベースのマシンでビルドする場合は、--platform linux/amd64 を指定しないと互換性のないイメージになる可能性があります。(Microsoft Learn)
docker build --platform linux/amd64 -t myagent:v1 .ローカルでは動くのにAzure上で起動しない場合、まずアーキテクチャ不一致を疑いましょう。
ポート8088を前提にする
Hosted Agentのコンテナは、ローカルでは8088番ポートでエンドポイントを提供する前提になっています。本番環境ではFoundry gatewayがルーティングを担うため、コンテナ自体を公開ポートとして外部公開する必要はありません。(Microsoft Learn)
ローカル検証では次のように呼び出せます。
curl -sS -H "Content-Type: application/json" \
-X POST http://localhost:8088/responses \
-d '{"input":"What is Microsoft Foundry?","stream":false}'環境変数を重複定義しない
Hosted Agentのプラットフォームは、FOUNDRY_PROJECT_ENDPOINT、FOUNDRY_AGENT_NAME、FOUNDRY_AGENT_VERSION、APPLICATIONINSIGHTS_CONNECTION_STRING などの環境変数を自動注入します。公式ドキュメントでは、こうしたプラットフォーム注入変数を agent.yaml に再宣言しないよう案内されています。(Microsoft Learn)
独自に指定するのは、たとえば次のようなアプリ固有の値です。
environment_variables:
MODEL_DEPLOYMENT_NAME: "your-model-deployment"
APP_ENV: "dev"シークレット値を環境変数に直接置く設計は避け、Key VaultやマネージドID、接続リソースを使う方針を検討してください。Hosted Agentの概念ページでも、コンテナイメージや環境変数にシークレットを入れないことが推奨されています。(Microsoft Learn)
監視とログ確認は最初から組み込む
AIエージェントは、通常のWeb APIよりも「なぜその応答になったか」を追いにくいシステムです。Hosted Agentの検証では、デプロイ成功だけで終わらせず、ログとトレースを見られる状態にしておきましょう。
Quickstartでは、azd ai agent monitor でコンテナのライブログやシステムイベント、セッションログを確認できます。また、Application Insightsの接続文字列がコンテナへ自動注入され、OpenTelemetryトレースを確認できると説明されています。(Microsoft Learn)
azd ai agent monitor
azd ai agent monitor --tail 20
azd ai agent monitor --type system
azd ai agent monitor --session <session-id> --follow本番を見据えるなら、次の項目をPoCの段階で決めておくと後戻りが少なくなります。
| 監視項目 | 見るべき理由 | 例 |
|---|---|---|
| 起動ログ | コンテナ起動失敗や依存関係エラーを検出する | import error、port conflict |
| リクエストログ | 入力件数や失敗率を見る | 4xx、5xx、タイムアウト |
| モデル呼び出し | レイテンシとコスト傾向を見る | モデル応答時間、トークン使用量 |
| ツール呼び出し | MCPやWeb Searchの失敗を切り分ける | 接続エラー、認可エラー |
| セッションログ | 状態復元やファイル操作を追跡する | session-id単位の処理履歴 |
管理者は、開発者にAzure AI Project Managerを付与するだけでなく、Application Insightsのトレースを確認できるMonitoring Readerなどの権限も検討してください。公式の権限リファレンスでは、Azure AI Userではトレース閲覧が十分でない場合があることも示されています。(Microsoft Learn)
移行・展開時に確認すべきこと
すでにAzure Container AppsやApp Service、AKSでAIエージェントを運用している場合、Hosted Agentへすぐ置き換えるべきかは用途によって異なります。重要なのは、Hosted Agentが「エージェント運用に特化したマネージド基盤」である一方、プレビュー段階の制限もあることです。
移行を検討しやすいケース
次の条件に当てはまる場合は、Hosted Agentへの移行検証に向いています。
- エージェントごとのバージョン管理やロールバックを簡単にしたい
- Foundryのモデル、ツール、Playground、監視とまとめて管理したい
- TeamsやMicrosoft 365 Copilotへの展開を見据えている
- 独自コードを含むエージェントをPoCから本番候補へ進めたい
- コンテナ実行基盤の個別管理を減らしたい
Hosted Agentでは、エージェントバージョンがコンテナイメージ、CPU、メモリ、環境変数、プロトコル構成のスナップショットとして扱われます。更新時は新しいバージョンを作成し、必要に応じてカナリアやブルーグリーン展開のような考え方を取り入れられます。(Microsoft Learn)
すぐ移行しない方がよいケース
一方で、次の条件では慎重に判断しましょう。
- プレビュー機能を本番利用できない
- ACRを完全にプライベート化しており、パブリック到達性を許容できない
- 独自のネットワーク制御、固定スケール、特殊なランタイム要件がある
- 既存のCI/CD、監視、セキュリティ審査がAzure Container Apps前提で整備済み
- エージェントではなく単純なREST APIとして十分に動いている
移行判断では「Foundryに寄せることで運用が楽になる部分」と「既存基盤で自由度を維持した方がよい部分」を分けて比較するのが現実的です。
よくあるエラーと対処法
Hosted Agentの初回デプロイで詰まりやすいポイントを、管理者と開発者の両方が見られる形で整理します。
| エラー・症状 | 主な原因 | 対処 |
|---|---|---|
AuthenticationError または DefaultAzureCredential 失敗 | Azure認証セッションが古い | azd auth logout 後に azd auth login する |
ResourceNotFound | FoundryのエンドポイントURLが違う | Foundryポータルの値と設定ファイルを照合する |
DeploymentNotFound | モデルデプロイ名が違う | Build > Deploymentsでデプロイ名を確認する |
Connection refused | 8088番ポートが競合している | 別プロセスを停止するかポート利用状況を確認する |
AcrPullUnauthorized | FoundryプロジェクトのマネージドIDにACRプル権限がない | ACRにContainer Registry Repository ReaderまたはAcrPullを付与する |
SubscriptionNotRegistered | リソースプロバイダー未登録 | Microsoft.CognitiveServices を登録する |
azd ai agent init 失敗 | azdまたは拡張機能が古い | azd version と azd ext upgrade azure.ai.agents を確認する |
公式Quickstartでも、これらの認証、リソース、デプロイ、ACR関連のトラブルシューティングが案内されています。(Microsoft Learn)
本番導入前のチェックリスト
PoCが成功しても、そのまま本番へ進めるのは危険です。Hosted AgentはAI機能、コンテナ、ID、外部ツール、監視が組み合わさるため、次のチェックを完了してから展開しましょう。
| 分類 | チェック項目 | 完了の目安 |
|---|---|---|
| 権限 | 開発者、デプロイ担当、エージェントID、プロジェクトIDの権限を分離した | 個人Owner依存をなくしている |
| コンテナ | linux/amd64 でビルドし、固定タグを使っている | latest だけに依存していない |
| ACR | FoundryプロジェクトのマネージドIDがイメージをpullできる | image pull errorが出ない |
| ネットワーク | ACRの到達性と社内ポリシーが整合している | プライベートACR制限を把握している |
| 設定 | agent.yaml の不要なMCP接続やプレースホルダーを削除した | 未使用の接続IDが残っていない |
| シークレット | コンテナイメージや環境変数に秘密情報を埋め込んでいない | Key Vaultや接続リソースを検討済み |
| 監視 | Application Insightsでログ・トレースを確認できる | 障害時に原因を追える |
| コスト | モデル、ACR、Log Analytics、Application Insightsの課金範囲を確認した | 検証後の削除手順も決めている |
| 性能 | コールドスタートと連続利用時の応答時間を測定した | ユーザー体験上の許容値を決めている |
| プレビュー | プレビュー機能としての制限や変更可能性を関係者に共有した | 本番採用の判断材料がそろっている |
次に取るべき行動
Azure AI Foundryの Quickstart: Deploy your first hosted agent は、Hosted Agentを初めて試す開発者にとって最短ルートです。ただし、実務では「動いた」で終わらせず、権限、ACR、監視、セッション、コールドスタート、プレビュー制限まで確認することが重要です。
まずは専用のリソースグループを用意し、Azure Developer CLIまたはVS Code拡張機能で最小構成のHosted Agentをデプロイしてください。そのうえで、MCPツール、Web Search、File Search、社内API連携などを段階的に追加すると、原因切り分けがしやすくなります。
管理者は、開発者に必要な権限を一時的に広く渡すのではなく、Foundryプロジェクト、ACR、Application Insights、Log Analyticsのスコープごとに役割を整理しましょう。開発者は、ローカルテスト、azd deploy、Playground確認、azd ai agent monitor によるログ確認までを一連の検証手順として残しておくと、チーム内展開やCI/CD化に進めやすくなります。
コメント