Azure AIのHosted agentsを運用している場合、2026年4月30日の公式ドキュメント更新「Update hosted agents documentation on versioning」で最も重要なのは、同じ内容のままエージェントバージョン作成を実行しても、新しいバージョンは作成されないと明記された点です。つまり、単に「create version」を再実行すれば再デプロイや世代追加になる、という運用は見直す必要があります。特にCI/CD、カナリアリリース、ブルーグリーンデプロイ、障害時のロールバック設計に関わるチームは、バージョン作成条件とルーティング設定を早めに確認しておくべきです。(GitHub)
Azure AIの公式ドキュメント更新「Update hosted agents documentation on versioning」で何が変わったか
今回の更新は、MicrosoftDocsのAzure AI関連リポジトリに対する小さな差分です。対象ファイルはHosted agentsの概念説明ページで、変更行数だけを見ると大規模な仕様変更には見えません。GitHub上のコミットでは、hosted-agents.mdのVersioningセクションに対して「変更のないパラメーターでエージェントバージョンを作成しても、新しいバージョンは作成されない」という説明が追加されています。(GitHub)
ただし、運用面の影響は小さくありません。Hosted agentsでは、エージェントバージョンはコンテナイメージ、リソース割り当て、環境変数、プロトコル設定などのスナップショットとして扱われます。公式ドキュメントでも、バージョンはimmutable、つまり作成後に変更できないものとして説明されています。(GitHub)
今回のポイントは、次のように整理できます。
| 確認項目 | 更新前に誤解しやすかった点 | 更新後に意識すべき点 |
|---|---|---|
| バージョン作成 | create versionを呼べば毎回新バージョンができる | 同じパラメーターなら新バージョンは作成されない |
| 再デプロイ | 同じイメージタグで再実行すれば反映されると考えがち | image、環境変数、CPU、メモリ、プロトコル設定などに実質的な変更が必要 |
| CI/CD | デプロイジョブの成功だけで新バージョン作成済みと判断しがち | 実際のversion番号、status、ルーティング先を確認する |
| ロールアウト | バージョンが増える前提でカナリア配信を組みがち | 新バージョンが作成されていない場合、配信比率の変更対象が存在しない |
Hosted agentsのバージョン管理を理解する
Azure AI FoundryのHosted agentsは、独自コードや任意のエージェントフレームワークをコンテナ化し、Foundry Agent Service上で実行するための仕組みです。公式ドキュメントでは、Hosted agentsはプレビュー扱いであり、利用時は制約や変更可能性を前提に設計する必要があります。(GitHub)
Versioningセクションで説明されているエージェントバージョンは、単なる履歴番号ではありません。実行環境の重要な設定をまとめた固定スナップショットです。
主に含まれる要素は次のとおりです。
- コンテナイメージ
- CPUやメモリなどのリソース割り当て
- 環境変数
- Responses、Invocationsなどのプロトコル設定
- デプロイメントが参照するバージョン情報
この仕組みの利点は、運用中のバージョンを不用意に書き換えず、過去の状態を再現しやすいことです。一方で、「同じ設定のまま作成操作だけを繰り返す」運用とは相性がよくありません。
今回の更新で特に注意すべきポイント
同じパラメーターでは新しいバージョンが作成されない
今回の更新で明確になったのは、エージェントバージョン作成時にコンテナイメージや環境変数などのパラメーターが変わっていない場合、新しいバージョン作成にはつながらないという点です。(GitHub)
たとえば、次のような運用は注意が必要です。
myregistry.azurecr.io/my-agent:latestこのように同じタグを使い続けている場合、Azure AI側から見るとimageパラメーターの文字列は変わっていません。たとえAzure Container Registry側でlatestの中身を更新していたとしても、Hosted agentsのバージョン作成条件として差分が認識されない可能性があります。
実務では、少なくとも次のような運用に寄せるのが安全です。
myregistry.azurecr.io/my-agent:2026-04-30-001
myregistry.azurecr.io/my-agent:1.4.2
myregistry.azurecr.io/my-agent:build-3842重要なのは、実際にリリースしたい変更が、Hosted agentsのバージョンパラメーター上でも差分として見えることです。
環境変数はバージョンごとに固定される
公式ドキュメントでは、環境変数はランタイム設定を渡す主要な手段であり、バージョン作成後はimmutableになると説明されています。(GitHub)
これは、次のような変更にも影響します。
| 変更したい内容 | 新バージョンが必要か | 補足 |
|---|---|---|
| モデルデプロイ名を変える | 必要 | 環境変数で渡している場合は新バージョン対象 |
| Project endpointを変える | 必要 | 実行時設定が変わるため影響範囲を確認 |
| 外部APIのURLを変える | 必要な場合が多い | 環境変数管理なら新バージョンとして扱う |
| シークレット値を差し替える | 設計次第 | Key Vaultや接続情報の参照方式も確認 |
| ログレベルだけ変える | 必要な場合がある | 環境変数で固定しているなら差分対象 |
ログレベルのような小さな変更でも、環境変数でバージョンに組み込んでいる場合は「設定変更」として扱う必要があります。逆に、同じ環境変数のままcreate versionを実行しても、新しい世代が増えない可能性があります。
デプロイ成功と新バージョン作成成功を分けて確認する
CI/CDでは「デプロイコマンドが成功したか」だけでなく、「新しいagent versionが実際に作成されたか」を確認する必要があります。
Microsoft Learnの管理ドキュメントでは、エージェントの詳細取得、特定バージョンの取得、全バージョンの一覧取得、バージョン作成、ステータス確認の方法が示されています。バージョン作成後はcreating、active、failedなどのstatusを確認する流れも説明されています。(Microsoft Learn)
確認観点は次の3つです。
| 確認するもの | 見るべき内容 | 失敗例 |
|---|---|---|
| version一覧 | 新しい番号や対象バージョンが存在するか | デプロイは成功したがversionが増えていない |
| version status | activeになっているか | creatingのまま、またはfailed |
| agent endpoint | トラフィックが意図したversionに向いているか | 最新版を作ったが本番が旧版を参照している |
特に本番運用では、「ビルド成功」「イメージPush成功」「Hosted agent version作成成功」「エンドポイントのルーティング反映成功」を別々のチェックとして扱うと、切り戻し時の原因調査が楽になります。
影響を受けやすい運用パターン
latestタグや固定タグでコンテナを更新している
最も影響を受けやすいのは、コンテナイメージのタグを固定しているチームです。
たとえば、毎回次のような同じ値でデプロイしているケースです。
myregistry.azurecr.io/my-agent:latest
myregistry.azurecr.io/my-agent:prod
myregistry.azurecr.io/my-agent:stableこの運用では、Azure Container Registry側の実体が変わっていても、Hosted agentsの定義上は同じimage値に見える場合があります。そのため、新しいエージェントバージョンが作成されず、期待したコードが反映されないリスクがあります。
対策はシンプルです。ビルドごと、またはリリースごとに一意なイメージ参照を使います。
myregistry.azurecr.io/my-agent:1.5.0
myregistry.azurecr.io/my-agent:20260430.1
myregistry.azurecr.io/my-agent:main-9f2c31a本番では、人間が読めるバージョン番号とCIのビルド番号を組み合わせると、障害時の追跡がしやすくなります。
カナリアリリースを自動化している
Hosted agentsでは、複数バージョン間でトラフィックを分割し、カナリアリリースやブルーグリーンデプロイを支援する説明があります。公式ドキュメントでも、バージョン間のweighted rolloutsに触れられています。(GitHub)
管理ドキュメントでは、エージェントエンドポイントのルーティングを設定し、たとえば90%を旧バージョン、10%を新バージョンに流す例も示されています。(Microsoft Learn)
ただし、新バージョンが作成されていなければ、カナリア配信の対象がありません。
CI/CDに組み込むなら、次の順序で確認すると安全です。
| 手順 | 確認内容 |
|---|---|
| ビルド | 新しいコンテナイメージが作成されたか |
| Push | Azure Container Registryに新しいタグで登録されたか |
| バージョン作成 | Hosted agentの新versionが作成されたか |
| 状態確認 | 新versionがactiveになったか |
| ルーティング | 旧version 90%、新version 10%など意図どおりか |
| 監視 | エラー率、レイテンシ、ツール呼び出し失敗を確認 |
| 昇格 | 問題なければ新versionへ100%切り替え |
「create versionを呼んだはず」ではなく、「新しいversion IDが存在し、activeになり、トラフィックを受けている」ことまで確認するのがポイントです。
本番エージェントをAlways use latestで運用している
Microsoft Foundryのエージェント設定では、バージョンルーティングに「Always use latest」と「特定バージョンへの固定」があります。公式ドキュメントでは、デフォルトでは最新バージョンへ100%ルーティングされ、新しいバージョンが作られるとTeamsやMicrosoft 365で提供される内容も更新されると説明されています。(Microsoft Learn)
開発環境では「Always use latest」が便利です。しかし本番環境では、新バージョン作成と同時に利用者へ反映される可能性があります。
本番運用では、次の判断が現実的です。
| 環境 | 推奨ルーティング | 理由 |
|---|---|---|
| 開発 | Always use latest | 変更確認を早く回せる |
| 検証 | latestまたは固定 | テスト方式に応じて選ぶ |
| 本番 | 特定バージョン固定 | 意図しない即時反映を防げる |
| カナリア | 比率指定 | 影響範囲を限定できる |
今回の更新を踏まえると、本番では「新バージョンが作られない場合」と「作られた瞬間にlatestへ流れる場合」の両方を考える必要があります。どちらもリリース事故につながりやすいため、version selectorの運用ルールを明確にしておきましょう。
開発者が確認すべきこと
開発者は、コード変更がHosted agentsのバージョン差分として正しく表現されているかを確認する必要があります。
特に見直したいのは次の項目です。
| 確認項目 | 実務でのチェック |
|---|---|
| コンテナイメージタグ | 毎回同じタグを使っていないか |
| agent.yaml | image、CPU、memory、protocol設定が意図どおりか |
| 環境変数 | 変更が必要な値を古いままにしていないか |
| プロトコル | Responses、Invocationsなど利用プロトコルが一致しているか |
| ローカルテスト | 新イメージで起動確認してからversion作成しているか |
たとえば、コードだけを修正しても、CIが古いイメージタグを使い回していると、Hosted agents側では新しいバージョン作成に結びつかない可能性があります。
チェックの観点としては、次のように考えると分かりやすいです。
コードが変わった
↓
新しいコンテナイメージが作られた
↓
Hosted agent定義のimage値が変わった
↓
新しいagent versionが作られた
↓
エンドポイントがそのversionへルーティングされたこの流れのどこかが途切れると、ユーザーには変更が反映されません。
クラウド管理者が確認すべきこと
クラウド管理者やプラットフォーム担当者は、リリース手順と権限管理を確認する必要があります。
Hosted agentsの管理ドキュメントでは、REST API、Python SDK、Azure Developer CLIを使って、エージェント一覧、バージョン一覧、バージョン詳細、ログ、ルーティングなどを確認できることが説明されています。(Microsoft Learn)
管理者視点で重要なのは次の点です。
| 項目 | 確認する理由 |
|---|---|
| version作成権限 | CI/CDサービスプリンシパルが必要な操作を実行できるか |
| ACR参照権限 | Agent ServiceがコンテナイメージをPullできるか |
| RBAC | エージェント実行時IDに過剰権限がないか |
| ログ取得 | バージョン作成失敗や起動失敗を追跡できるか |
| 削除ポリシー | 古いversionをいつ削除するか決めているか |
また、削除操作には注意が必要です。公式ドキュメントでは、エージェント全体を削除すると全バージョンが削除され、アクティブセッションも終了し、元に戻せないと説明されています。(Microsoft Learn)
古いバージョンを整理する場合でも、直近の安定版やロールバック候補は残しておくのが実務的です。
ソリューションアーキテクトが確認すべきこと
ソリューションアーキテクトは、Hosted agentsのバージョニングをアプリケーション全体のリリース設計に組み込む必要があります。
確認すべき観点は、単に「新しいバージョンが作れるか」ではありません。
| 設計観点 | 確認内容 |
|---|---|
| リリース戦略 | 即時反映、段階配信、承認制のどれにするか |
| ロールバック | どのversionへ戻すかを事前に決めているか |
| 状態管理 | sessionやconversationへの影響を理解しているか |
| 外部連携 | ツール、API、MCP、Azure AI Searchなどの変更と同期しているか |
| 監視 | バージョン別に品質、遅延、エラーを見られるか |
Hosted agentsは、単なるプロンプト設定ではなく、コンテナ化されたアプリケーションです。そのため、Webアプリやマイクロサービスと同じように、リリース単位、依存関係、実行時設定、監視、ロールバックを設計する必要があります。
特にAIエージェントでは、コードやプロンプトが少し変わっただけでも、回答品質やツール呼び出しの挙動が変わります。バージョン作成の有無を正しく把握できないと、「どの変更がユーザー影響を生んだのか」を追いにくくなります。
移行準備で見直すべきチェックリスト
2026年時点のHosted agents関連ドキュメントでは、プレビュー更新や移行情報も公開されています。移行ガイドでは、初期パブリックプレビューのホスティングバックエンドが廃止され、2026年4月以前にデプロイしたHosted agentsは新しいモデルで再デプロイが必要になるケースが説明されています。(Microsoft Learn)
今回のversioning更新とあわせて、次のチェックリストを確認しておくとよいでしょう。
| チェック項目 | 対象者 | 優先度 |
|---|---|---|
| 同一imageタグを使い回していないか | 開発者、DevOps | 高 |
| create version後にversion一覧を確認しているか | DevOps | 高 |
| 本番agentがlatest自動追従になっていないか | 管理者、アーキテクト | 高 |
| カナリア配信の対象versionが存在するか | DevOps | 高 |
| 環境変数の変更が新version化される運用か | 開発者 | 中 |
| 古いversionの削除基準があるか | 管理者 | 中 |
| 移行対象の古いHosted agentsが残っていないか | 管理者 | 高 |
| エージェントIDとRBACを再確認したか | 管理者 | 高 |
| リリース後の評価・監視をversion単位で行えるか | アーキテクト | 中 |
よくある失敗と対策
失敗：デプロイしたのに変更が反映されない
原因として多いのは、同じコンテナイメージタグ、同じ環境変数、同じプロトコル設定のままversion作成を実行しているケースです。
対策は、新しいリリースごとにHosted agentsのversionパラメーター上でも差分が出るようにすることです。特にlatest固定は避け、CIのビルド番号やGitのコミットIDを含むタグを使うと確認しやすくなります。
失敗：新バージョンを作った瞬間に本番へ流れてしまう
デフォルトのルーティングがlatest追従になっている場合、新しいバージョンが作成されると、そのバージョンへトラフィックが向く可能性があります。公式ドキュメントでも、本番やTeams、Microsoft 365向けに公開する場合は、安定性のために特定バージョンへpinする考え方が示されています。(Microsoft Learn)
対策は、本番エージェントではversion selectorを明示的に管理することです。新バージョン作成と本番反映を別ステップに分けると、承認フローや検証を挟みやすくなります。
失敗：ロールバック先が分からない
AIエージェントは、モデル、プロンプト、ツール、外部API、環境変数が絡み合います。バージョン番号だけを見ても、何が入っているか分からない状態では、障害時に戻し先を判断できません。
対策として、リリースノートやCIログに次の情報を残しておきましょう。
agent name
agent version
container image
Git commit
主要な環境変数の変更有無
有効なprotocol
ルーティング比率
リリース担当者
検証結果これだけでも、障害調査とロールバック判断の速度が大きく変わります。
今回の更新を受けて今すぐやるべきこと
Azure AIの今回の公式ドキュメント更新は、表面的にはHosted agentsのVersioningセクションに対する説明追加です。しかし実務では、CI/CD、リリース管理、カナリア配信、ロールバック設計に直結します。
まず確認すべきことは次の3つです。
| 今すぐ確認すること | 理由 |
|---|---|
| 同じパラメーターでcreate versionを再実行する運用がないか | 新バージョンが作成されない可能性がある |
| 本番エンドポイントがlatest追従か固定か | 意図しない即時反映を防ぐため |
| version作成後にstatusとルーティングを検証しているか | デプロイ成功と本番反映成功は別物だから |
Hosted agentsは、AIエージェントを本番アプリケーションとして扱うための基盤です。だからこそ、バージョン管理も「履歴が増えればよい」ではなく、どの変更を、どのバージョンとして、どの利用者へ、どの比率で届けるかを明確にする必要があります。
今回の更新をきっかけに、コンテナイメージタグ、環境変数、version selector、CI/CDの確認処理を見直しておくと、今後のAzure AIエージェント運用で起きやすい「反映されない」「勝手に反映された」「戻せない」というトラブルを減らせます。
コメント