Azure REST API documentation updateとして、2026年5月5日に確認すべきポイントは明確です。Hosted code-based agent向けに、アップロード済みのコードZIPをダウンロードできるプレビューGETエンドポイントが2つ追加されました。これにより、これまで「コードはアップロードできるが、サービス側にある同一ZIPを取り戻せない」という運用上の穴を埋められます。
すぐに既存API呼び出しが壊れる変更ではありません。ただし、Azure AI FoundryやHosted Agentを使って、コードベースのエージェントをCI/CD、監査、バックアップ、エージェント生成ツールと連携しているチームは、早めに仕様確認しておくべき更新です。
Azure REST API documentation updateで追加された内容
今回のAzure REST API documentation updateでは、Hosted code-based agentに対して、過去にアップロードしたコードZIPを取得するためのGET操作が追加されました。PRでは、downloadAgentVersionCodeとdownloadAgentCodeの2操作が追加され、どちらもcode_agents_v1_previewのプレビュー機能として扱われます。(GitHub)
| 操作 | ルート | 取得対象 | 主な使い方 |
|---|---|---|---|
downloadAgentVersionCode | GET /agents/{agent_name}/versions/{agent_version}/code:download | 指定したエージェントバージョンのコードZIP | 監査、ロールバック確認、特定バージョンの再現 |
downloadAgentCode | GET /agents/{agent_name}/code:download | エージェントの最新バージョンのコードZIP | 現在の実体確認、管理画面やツールからのダウンロード |
レスポンスは、アップロード済みのZIPをapplication/zipとして返す設計です。TypeSpec上のDownloadAgentCodeResponseでも、Content-Typeはapplication/zip、本文はZIPのバイト列として定義されています。(GitHub)
何が便利になるのか
これまでのコードベースHosted Agentでは、createAgentFromCode、updateAgentFromCode、createAgentVersionFromCodeのように、コードをアップロードする操作は用意されていました。一方で、アップロード後にサービス側へ保存されたコードZIPを取得する方法がありませんでした。今回の更新は、その非対称性を解消するものです。(GitHub)
実務では、次のような場面で役立ちます。
監査やレビューで「実際に動いているコード」を確認できる
Gitリポジトリにあるコードと、実際にHosted Agentへアップロードされたコードが常に一致しているとは限りません。手動アップロード、ビルド成果物の差異、CI/CDの設定ミス、生成AIによるコード生成などがあるためです。
今回のエンドポイントを使えば、サービス側に保存されているコードZIPを取得し、次のような確認ができます。
- Gitの特定コミットとZIP内容が一致しているか
- 本番環境で動いているエージェントのコードに不要ファイルが含まれていないか
- 監査時に「どのコードがアップロードされていたか」を証跡として残せるか
- 生成されたエージェントのコードを利用者が確認できるか
PRでも、Agent Builderのような「プロンプトからHosted Agentを作る仕組み」では、ユーザーの手元に生成コードが存在しないため、生成されたコードを検査する手段が必要だと説明されています。(GitHub)
障害調査やロールバック判断がしやすくなる
特定のエージェントバージョンで障害が起きた場合、downloadAgentVersionCodeを使うことで、そのバージョンに紐づくコードZIPを取得できます。
たとえば、バージョン3でのみエラーが発生している場合は、次の観点で調査できます。
GET /agents/my-agent/versions/3/code:download
Accept: application/zip確認すべきポイントは、単に「ZIPを取れるか」ではありません。取得したZIPを展開し、エントリーポイント、依存関係、設定ファイル、不要なローカルファイル混入の有無を確認することが重要です。
影響を受ける人・受けにくい人
今回の変更は、全Azure REST API利用者に影響するものではありません。影響範囲は、Hosted code-based agentを扱う開発者、運用担当者、ツール開発者に限定されます。
| 対象者 | 対応優先度 | 理由 |
|---|---|---|
| Hosted code-based agentをREST APIで作成・更新している開発者 | 高 | ダウンロードAPIをCI/CDや運用手順に組み込める |
| Agent Builderや管理ポータルを開発しているチーム | 高 | 生成されたコードをユーザーに提示する導線を作れる |
| SDK・CLI・社内ツールのラッパーを作っている担当者 | 中〜高 | バイナリレスポンス、application/zip、404処理の実装が必要 |
| 監査・セキュリティ担当者 | 中 | 実際にアップロードされたコードの確認手段が増える |
| 通常のAzure管理APIだけを使っている利用者 | 低 | Hosted code-based agentを使っていなければ直接影響は小さい |
特に注意したいのは、「Hosted Agentを使っている」だけでは対象とは限らない点です。今回の更新は、コードZIPをアップロードして作成・更新するcode-based agentの文脈で重要になります。
既存システムへの破壊的変更はあるか
今回の追加は、基本的には新しいGETエンドポイントの追加です。既存の作成・更新APIを直接変更するものではないため、通常は既存のREST API呼び出しが急に失敗するような変更ではありません。
ただし、次の点は見落とさないでください。
| 確認項目 | 注意点 |
|---|---|
| プレビュー機能の扱い | code_agents_v1_previewのopt-in配下であり、正式版と同じ安定性を前提にしない |
| v1からの除外 | PRでは@removed(Versions.v1)によりv1から除外される説明があるため、安定版APIとして扱わない |
| SDK生成への影響 | APIViewではTypeSpec、Python、JavaScriptのAPIレビューが作成されており、SDK側の表現が変わる可能性がある |
| バイナリレスポンス | JSONではなくZIPを受け取るため、通常のJSONパーサー前提の実装では扱えない |
| 404の意味 | エージェント不存在、バージョン不存在、または対象バージョンにアップロード済みコードがない場合を区別して考える必要がある |
PR上では、今回の変更によりAPIレベルの変更が検出され、TypeSpec、Python、JavaScriptのAPIレビューが作成されています。SDKや自動生成クライアントを利用している場合は、ドキュメントだけでなく、使用中SDKのリリース状況も確認するのが安全です。(GitHub)
実装時に確認すべきリクエストとレスポンス
実装では、通常のJSON APIと同じ感覚で扱うと失敗しやすいです。返ってくるのはZIPファイルであり、保存先、ファイル名、サイズ、ハッシュ検証まで設計しておく必要があります。
最新バージョンのコードを取得する例
GET /agents/my-agent/code:download
Accept: application/zipこの操作は、エージェントの最新バージョンのコードZIPを取得する用途に向いています。管理画面で「現在のコードをダウンロード」ボタンを作る場合や、デバッグ用に現在の実体を確認する場合に使いやすいでしょう。
ただし、最新バージョンは運用設定によっては頻繁に変わります。Microsoft Foundryのエージェントでは、既定で最新バージョンへトラフィックを向ける考え方があり、必要に応じて特定バージョンへ固定できます。運用中の実体確認では、エージェントのルーティング設定とあわせて確認することが大切です。(Microsoft Learn)
特定バージョンのコードを取得する例
GET /agents/my-agent/versions/3/code:download
Accept: application/zipこの操作は、監査や障害調査に向いています。最新ではなく、明示的にバージョンを指定できるため、「2026年5月時点で本番に出ていたバージョン3のコードを確認する」といった用途に使えます。
レスポンス処理で見るべき点
| ステータス | 想定される内容 | 実装時の対応 |
|---|---|---|
200 OK | ZIPバイト列 | ファイルとして保存し、必要に応じてハッシュ検証する |
404 Not Found | エージェント、バージョン、またはアップロード済みコードが見つからない | 対象名・バージョン・作成方式を確認する |
| その他の4xx | 認証、権限、プレビューopt-inなどの問題 | トークン、RBAC、ヘッダー、APIバージョンを確認する |
| 5xx | サービス側または一時的な問題 | リトライ方針と運用アラートを整備する |
PRでは、200 OK時に生のZIPバイト列を返し、404 Not Foundはエージェントやバージョンが存在しない場合、またはバージョンにアップロード済みコードがない場合に該当すると説明されています。(GitHub)
content_hashによる整合性確認を忘れない
今回のエンドポイントは、単にZIPを取得するだけでなく、取得した内容が期待どおりか確認する運用とセットで考えるべきです。
TypeSpec上では、返却されたバイト列のSHA-256ダイジェストが、対象バージョンのcode_configurationにあるcontent_hashと一致することが説明されています。(GitHub)
実務では、次の流れにすると安全です。
| 手順 | 内容 |
|---|---|
| 取得前 | 対象エージェント名とバージョンを確定する |
| 取得 | code:downloadエンドポイントからZIPをダウンロードする |
| 検証 | ZIPのSHA-256を計算し、バージョン情報のcontent_hashと比較する |
| 保存 | 監査用ストレージや証跡管理システムへ保存する |
| 記録 | 取得日時、取得者、エージェント名、バージョン、ハッシュ値をログ化する |
ここで重要なのは、ZIPをダウンロードできたことと、正しいZIPであることは別問題だという点です。監査や復元に使うなら、ハッシュ検証まで含めて手順化しましょう。
移行・設定確認の観点
今回のAzure REST API documentation updateに対して、既存環境で大きな移行作業が必要になるケースは限定的です。ただし、Hosted Agentのプレビュー更新やSDK生成の影響を受ける可能性があるため、次の観点で確認しておくと安全です。
プレビューopt-inが有効か確認する
今回の2つのダウンロード操作は、code_agents_v1_previewのプレビュー機能として定義されています。呼び出し時に必要なAPIバージョン、プレビュー機能の有効化方法、ヘッダー指定は、利用中のFoundry環境や公開ドキュメントの更新に合わせて確認してください。
プレビュー機能は、正式リリース前に仕様が変わる可能性があります。特に社内ツールへ組み込む場合は、エンドポイント名、パス、レスポンス形式をハードコードしすぎない方が安全です。
SDKだけでなくREST APIの実装も確認する
自動生成SDKを使っている場合、REST API仕様が更新されても、手元のSDKにすぐ反映されるとは限りません。
確認すべき点は次のとおりです。
- 利用中SDKに
downloadAgentCode相当のメソッドが追加されているか - バイナリストリームを受け取れる型になっているか
Content-Type: application/zipを正しく扱えるか- 404時のエラー型や例外処理が既存実装と合っているか
- SDK未対応の場合に
az restやHTTPクライアントで代替できるか
PRのレビュー過程では、当初のapplication/octet-streamから、ZIPであることを明示するapplication/zipへ調整された経緯があります。ツール側でMIMEタイプを見て処理を分岐している場合は、この点が特に重要です。(GitHub)
ルート名の変更履歴に注意する
PR内では、当初のルート案から最終的に/code:download形式へ変更されています。レビューでは、/code/contentよりもダウンロード操作であることが明確な/code:downloadが推奨され、最終的に両ルートが/code:downloadへリネームされました。(GitHub)
古いメモ、社内Wiki、試験実装に/code/contentが残っている場合は修正が必要です。特にプレビュー段階のAPIでは、PR途中の情報をもとに実装すると、正式なドキュメント更新後に動かないことがあります。
セキュリティ上の注意点
コードZIPをダウンロードできる機能は便利ですが、同時に管理すべきリスクも増えます。Hosted Agentのコードには、アプリケーションロジック、ツール連携、設定ファイル、場合によっては誤って含めた機密情報が入っている可能性があります。
ダウンロード権限は最小限にする
コードの閲覧権限は、実質的にソースコード閲覧権限です。運用担当者全員に無条件で付与するのではなく、次のように分けるのが現実的です。
| 役割 | 推奨される扱い |
|---|---|
| 開発者 | 開発・検証環境では許可、本番は必要時のみ |
| SRE/運用担当 | 障害調査に必要な範囲で許可 |
| セキュリティ担当 | 監査目的で許可 |
| 一般閲覧者 | 原則として不要 |
| 外部委託先 | 契約・権限範囲に応じて厳格に制御 |
Microsoft FoundryのHosted Agentでは、エージェントの管理やRBAC、エージェントIDの扱いが運用上の重要ポイントになります。Hosted Agentの管理ドキュメントでも、エージェントの詳細取得、バージョン一覧、バージョン作成、IDとRBACの確認が運用手順として示されています。(GitHub)
ZIP内に秘密情報を入れない
今回の更新により、サービス側にアップロード済みのZIPを後から取得しやすくなります。これは便利な一方で、誤って秘密情報をZIPへ含めていた場合、そのリスクが見えやすくなるということでもあります。
避けるべき例は次のとおりです。
.envファイルを含める- APIキーや接続文字列をコード内に直書きする
- ローカル検証用の証明書や秘密鍵を含める
- 不要なログやテストデータをZIPに含める
- 個人情報を含むサンプルファイルを同梱する
CI/CDでアップロードZIPを作る場合は、ZIP生成前に除外ルールを明確にしてください。distやsrcだけを含めるのか、設定テンプレートを含めるのか、依存関係を含めるのかを決めておくと事故を防げます。
実務でおすすめの確認チェックリスト
今回のAzure REST API documentation updateを受けて、Hosted code-based agentを使っているチームは、次のチェックリストで状況を確認するとよいでしょう。
| チェック項目 | 確認内容 |
|---|---|
| 対象エージェントの洗い出し | コードZIPで作成・更新しているHosted Agentがあるか |
| API仕様の確認 | downloadAgentVersionCodeとdownloadAgentCodeのパスを最新仕様で確認したか |
| プレビュー設定 | code_agents_v1_previewを利用できる環境か |
| 権限 | コードZIPを取得できるユーザー・サービスプリンシパルを制限しているか |
| ダウンロード処理 | JSONではなくZIPとして保存できる実装になっているか |
| ハッシュ検証 | content_hashと取得ZIPのSHA-256を比較する手順があるか |
| 404処理 | エージェント不存在、バージョン不存在、コード未アップロードを運用上切り分けられるか |
| 監査ログ | 誰が、いつ、どのエージェントのコードを取得したか記録できるか |
| 秘密情報対策 | ZIPに秘密情報を含めないビルド手順になっているか |
| 社内ドキュメント | 古い/code/content表記が残っていないか |
このチェックリストの中で最初に見るべきなのは、対象エージェントの有無です。Hosted code-based agentを使っていなければ、今回の更新は参考情報にとどまります。一方、使っている場合は、ダウンロード機能を運用・監査・復旧のどこに組み込むかを決める価値があります。
よくある失敗パターン
最新バージョン取得を監査用途に使ってしまう
GET /agents/{agent_name}/code:downloadは便利ですが、監査には不向きな場合があります。最新バージョンは時間とともに変わるため、「ある時点で本番に出ていたコード」を証明したい場合は、バージョン指定のdownloadAgentVersionCodeを使うべきです。
ZIPをJSONとして処理してしまう
REST APIのレスポンスだからといって、常にJSONとは限りません。今回のレスポンスはapplication/zipです。HTTPクライアント側で自動的にJSONパースする設定になっていると、エラーや文字化けの原因になります。
404を単純な「エージェントなし」と扱う
PRの説明では、404はエージェントやバージョンが存在しない場合だけでなく、対象バージョンにアップロード済みコードがない場合にも該当します。運用画面では「エージェントが存在しません」と断定せず、「対象コードを取得できません。エージェント名、バージョン、作成方式を確認してください」のように表示する方が安全です。
ZIPの内容をそのまま再アップロードする
取得したZIPを再アップロードして復元する運用を考える場合、ランタイム設定、エントリーポイント、環境変数、RBAC、プロトコル設定なども確認が必要です。コードZIPだけでHosted Agentの運用状態すべてを完全に再現できるとは限りません。
まず取るべき行動
今回のAzure REST API documentation updateは、Hosted code-based agentの運用をより透明にする更新です。特に、生成AIで作成したエージェント、CI/CDで自動更新するエージェント、監査対象となる業務エージェントでは、コードZIPを後から取得できることの価値が大きくなります。
まずは、社内またはプロジェクト内で次の3点を確認してください。
1つ目は、コードZIPで作成・更新しているHosted Agentが存在するか。2つ目は、ダウンロード権限を誰に与えるべきか。3つ目は、取得したZIPをどのように検証・保管・監査ログ化するかです。
既存処理を急いで変更する必要はありませんが、Hosted code-based agentを本格運用しているなら、downloadAgentVersionCodeを監査・障害調査用に、downloadAgentCodeを管理ツールや現状確認用に位置づけると、運用の見通しがよくなります。
コメント