2026年5月5日に公開された「Azure REST API documentation update: Spec: include code-based agent deploy routes in v1」の要点は、Azure AI Foundryのコードベースエージェント関連操作が、v1のREST API仕様面に含まれる方向で更新されたことです。すぐ確認すべきなのは、createAgentFromCodeなど5つの操作、CodeAgents=V1Previewの扱い、SDK生成時のメソッド名、そしてCI/CDでのzipアップロード・ハッシュ検証です。対象は、Azure REST APIでエージェントをコードからデプロイしている開発者、SDK生成やOpenAPI仕様を参照しているチーム、エージェントの自動デプロイを組んでいる運用担当者です。(GitHub)
Azure REST API documentation updateで何が変わったのか
今回の更新は、Azure REST APIそのものの一般的な使い方変更ではなく、Azure REST API仕様リポジトリ内のMicrosoft Foundry / Azure AI Projects系エージェント仕様に関する変更です。AzureのREST API仕様は、Azure REST API Specificationsリポジトリがカノニカルな仕様ソースとして扱われており、ここでの変更はドキュメント生成、SDK生成、APIレビューに影響する可能性があります。(GitHub)
PRの説明では、createAgentFromCode、updateAgentFromCode、createAgentVersionFromCode、downloadAgentCode、downloadAgentVersionCodeから@removed(Versions.v1)を外し、関連するcode_agents_v1_previewのv1除外状態も外すことで、v1 surfaceで利用できるようにする意図が示されています。さらにレビュー後、openapi3/v1/microsoft-foundry-openapi3.jsonが再生成され、これらの操作がv1側に反映される形になりました。(GitHub)
ただし、ここで重要なのは「v1に入った＝完全にプレビュー要素がなくなった」と早合点しないことです。OpenAPI上では、コードベースエージェント関連の操作やモデルにCodeAgents=V1Previewが紐づいています。つまり、v1のAPI仕様で参照できるようになった一方で、機能フラグやプレビュー扱いの確認は引き続き必要です。(GitHub)
| 確認項目 | 今回の変更 | 実務上の意味 |
|---|---|---|
| 対象操作 | コードベースエージェントの作成、更新、バージョン作成、コード取得がv1仕様に反映 | RESTクライアントやSDK生成で参照対象になる可能性がある |
| リクエスト形式 | アップロード系はmultipart/form-data | JSONだけで呼ぶ既存実装では対応できない |
| ハッシュ | x-ms-code-zip-sha256でzipのSHA-256を渡す | 変更検知、重複排除、整合性確認に使われる |
| ダウンロード | application/zipのバイナリとして返る | JSONパーサーではなくバイナリ保存処理が必要 |
| プレビューキー | CodeAgents=V1Previewが仕様メタデータに残る | Foundry-Featuresヘッダーの扱いを環境ごとに確認する |
| SDK生成 | APIViewでTypeSpec、Python、JavaScriptのAPIレビューが作成 | SDKのメソッド名や公開形が変わる可能性がある |
影響を受ける人、受けにくい人
このAzure REST API documentation updateの影響は、Azure REST APIを直接呼んでいるか、OpenAPI/TypeSpecからSDKやクライアントコードを生成しているかで大きく変わります。
| 立場 | 影響度 | 確認すべきこと |
|---|---|---|
| REST APIを直接呼んでエージェントをデプロイしている開発者 | 高 | v1で対象ルートを使えるか、ヘッダー・multipart・api-versionを確認する |
| Azure AI FoundryのコードベースエージェントをCI/CDで更新しているチーム | 高 | zip作成、SHA-256計算、バージョン作成、ダウンロード検証をパイプラインに組み込む |
| OpenAPIからクライアントを生成しているSDK担当者 | 高 | operationId、メソッド名、リクエストモデル、バイナリレスポンスの生成結果を確認する |
| 既存のプレビューAPIで同ルートを使っていたチーム | 中 | virtual-public-preview側は既にルートを持っていたため、v1移行時の差分を中心に確認する |
| 通常のエージェント作成・取得・削除だけを使う利用者 | 低 | 既存のcreateAgentやdeleteAgent中心なら影響は限定的 |
| Azure Resource Managerなど管理プレーンAPIだけを使う利用者 | 低 | 今回はFoundryのデータプレーン仕様が中心 |
本稿執筆時点で、PRはOpenの状態で、Swagger BreakingChangeチェックの失敗や、APIレビューの作成も確認されています。つまり、本番移行の判断では「PRの内容を確認した」だけで終わらせず、最新のマージ状況、Microsoft Learn上のリファレンス反映、利用SDKのリリース状況まで確認する必要があります。(GitHub)
v1に含まれるコードベースエージェント操作
今回の中心は、コードをzipとしてアップロードし、エージェントやエージェントバージョンを作成・更新・取得する操作です。OpenAPI v1では、POST /agentsやPOST /agents/{agent_name}のように既存操作とルートを共有する形もあり、生成されるoperationIdが結合された名前になる点にも注意が必要です。(GitHub)
| 操作 | メソッド・パス | 主な用途 | 実装時の確認ポイント |
|---|---|---|---|
createAgentFromCode | POST /agents | コードzipをアップロードして新規エージェントを作成 | x-ms-agent-name、x-ms-code-zip-sha256、multipart/form-dataを確認 |
updateAgentFromCode | POST /agents/{agent_name} | コードベースエージェントを更新し、新しいバージョンを作成 | 同じコード・定義なら既存バージョンが返る可能性を考慮 |
createAgentVersionFromCode | POST /agents/{agent_name}/versions | 既存エージェントに新しいコード版を追加 | バージョン管理、ロールバック、リリース履歴と紐づける |
downloadAgentCode | GET /agents/{agent_name}/code:download | 最新バージョンのコードzipを取得 | application/zipとして保存し、ハッシュ検証を行う |
downloadAgentVersionCode | GET /agents/{agent_name}/versions/{agent_version}/code:download | 指定バージョンのコードzipを取得 | 監査、差分確認、復元用に使いやすい |
アップロード系の説明では、メタデータJSONパートとバイナリコードパートを含むmultipart/form-dataを使い、最大アップロードサイズは250MBとされています。また、x-ms-code-zip-sha256は、アップロードするzipそのもののSHA-256ダイジェストとして扱われます。(GitHub)
ダウンロード系は、以前アップロードしたzipをapplication/zipとして返し、返却バイト列のSHA-256がエージェントバージョンのcode_configurationにあるcontent_hashと一致する前提で説明されています。監査やリリース確認のために、ダウンロード後のハッシュ検証を自動化しておくと安全です。(GitHub)
移行前に確認すべき設定
api-versionは「v1で見えるか」だけでなく実行環境で確認する
Azure REST APIでは、要求URI、HTTPメソッド、ヘッダー、要求本文、応答本文などを組み合わせて呼び出します。多くのAzure REST APIではapi-versionなどのクエリパラメーターや、Authorizationヘッダー、Content-Typeヘッダーを正しく指定する必要があります。(Microsoft Learn)
今回の仕様ではOpenAPIのinfo.versionがv1になっており、各操作にもapi-versionクエリパラメーターが定義されています。ただし、実際に指定すべき値や公開タイミングはサービスの最新リファレンスで確認してください。仕様PRだけを根拠に、本番コードのapi-versionを一斉変更するのは避けるべきです。(GitHub)
Foundry-Featuresヘッダーを安易に削除しない
OpenAPI上では、コードベースエージェント関連操作にCodeAgents=V1Previewが紐づいています。生成された仕様内のFoundry-Featuresヘッダーは必ずしも全操作でrequired: trueとして表現されているわけではありませんが、説明上はプレビュー操作やプレビューリソース利用時の機能フラグとして扱われています。(GitHub)
そのため、既存の呼び出しで次のようなヘッダーを使っている場合は、v1対応後もステージング環境で成功・失敗を比較してから変更してください。
Foundry-Features: CodeAgents=V1Preview特に「ドキュメント上はv1に見えるから、プレビュー用ヘッダーは不要」と判断するのは危険です。サービス側の実行時検証、テナント設定、リージョン展開状況によって挙動が変わる可能性があります。
multipart/form-dataの作り方を見直す
アップロード系の操作は、通常のJSON POSTとは違います。メタデータ部分はJSON、コード本体はzipのバイナリとして送る必要があります。
実装で失敗しやすいのは次の点です。
| 失敗しやすい点 | 原因 | 対策 |
|---|---|---|
Content-Type: application/jsonで送ってしまう | 既存のエージェント作成処理を流用している | コードアップロード時はmultipart/form-dataに分岐する |
| SHA-256が一致しない | zip化前のフォルダやソースファイル単位で計算している | 実際に送信するzipファイルのバイト列に対して計算する |
| 境界文字列が壊れる | multipart/form-dataのboundaryを手書きしている | HTTPクライアントライブラリにboundary生成を任せる |
| 250MBを超える | .git、テストデータ、ログ、キャッシュを含めている | デプロイ対象だけをzip化し、除外ルールをCIに入れる |
| 秘密情報をzipに含める | ローカル設定ファイルをまとめてアップロードしている | シークレットはKey Vaultや環境変数に分離する |
agent_nameとバージョン管理を整理する
createAgentFromCodeでは、POST /agentsのURLにエージェント名が入らないため、x-ms-agent-nameヘッダーでエージェント名を渡します。一方、更新やバージョン作成、ダウンロードでは/agents/{agent_name}のようにパスで指定します。エージェント名は最大63文字で、英数字で始まり英数字で終わり、途中にハイフンを含められるという制約が示されています。(GitHub)
CI/CDでは、エージェント名を環境別に明確に分けるのが安全です。
| 環境 | 命名例 | 目的 |
|---|---|---|
| 開発 | support-agent-dev | 動作検証用 |
| ステージング | support-agent-stg | 本番前の統合テスト用 |
| 本番 | support-agent-prod | 実運用用 |
同じエージェント名に対して更新を続ける場合は、バージョン番号、GitコミットID、zipのSHA-256、デプロイ日時をセットで記録しておくと、問題発生時に特定バージョンのコードをダウンロードして確認できます。
CI/CDパイプラインでの実装イメージ
コードベースエージェントをAzure REST APIでデプロイする場合、手作業でzipを作ってアップロードするより、CI/CDに組み込む方が安全です。最小構成では次の流れにします。
| 手順 | やること | 確認ポイント |
|---|---|---|
| ソース取得 | Gitの対象ブランチやタグをチェックアウト | 本番はタグや承認済みコミットに限定する |
| zip作成 | デプロイ対象コードだけをzip化 | .git、ローカル設定、不要なログを除外 |
| ハッシュ計算 | zipファイルのSHA-256を計算 | x-ms-code-zip-sha256に渡す値と一致させる |
| アップロード | POST /agentsまたはPOST /agents/{agent_name}/versionsを呼ぶ | api-version、認証、機能フラグ、multipartを確認 |
| 応答保存 | 返却されたエージェント・バージョン情報を記録 | GitコミットID、ビルド番号、ハッシュと紐づける |
| 検証 | downloadAgentCodeまたはdownloadAgentVersionCodeでzipを取得 | 取得したzipのハッシュを再計算する |
| リリース記録 | どのバージョンを本番利用しているか保存 | ロールバック判断に使える形にする |
この流れにすると、「API呼び出しは成功したが、実際にどのコードがデプロイされたか分からない」という運用上の問題を避けやすくなります。
SDK利用者が注意すべき点
今回のPRでは、APIViewがTypeSpec、Python、JavaScript向けのAPIレビューを作成しています。これは、OpenAPIやTypeSpecの変更がSDKの公開APIに影響し得ることを示します。(GitHub)
特に注意したいのは、POST /agentsやPOST /agents/{agent_name}が通常のエージェント作成・更新とコードベース作成・更新でルートを共有している点です。OpenAPI v1では、operationIdがAgents_createAgent_Agents_createAgentFromCodeやAgents_updateAgent_Agents_updateAgentFromCodeのように結合された形で表現されています。レビューコメントでも、このoperationIdがドキュメントの目次や生成コードに使われる可能性があるため、理由や修正方法を確認すべきという指摘があり、@operationIdデコレーターで修正できる可能性にも触れられています。(GitHub)
SDKで実装する場合は、次の順に確認してください。
| 確認対象 | 見るべきポイント |
|---|---|
| SDKのリリースノート | 対象操作が正式に含まれているか |
| 生成されたメソッド名 | 期待する名前で呼び出せるか、破壊的変更がないか |
| multipart対応 | SDKがzipアップロードを正しく扱えるか |
| バイナリダウンロード | application/zipをストリームまたはバイト列として扱えるか |
| プレビュー機能ヘッダー | SDKがFoundry-Featuresを指定できるか |
| エラー型 | ApiErrorResponseなどの既定エラーを処理できるか |
SDKの対応が遅れている場合は、無理に自作ラッパーでSDKを改造するより、当面はREST APIを直接呼ぶ小さなデプロイ用モジュールを作る方が安全な場合があります。
本番反映前のチェックリスト
本番環境でこの更新に対応する前に、次の項目を確認してください。
| チェック | 合格条件 |
|---|---|
| PR・公式ドキュメントの状態 | PRがマージ済み、または公式リファレンスに対象操作が反映済み |
| APIバージョン | 対象環境で指定すべきapi-versionが明確 |
| 認証 | Microsoft Entra IDのトークン取得と権限が確認済み |
| 機能フラグ | CodeAgents=V1Previewの要否をステージングで検証済み |
| zipサイズ | 250MB以下に収まる |
| ハッシュ | アップロード前後でSHA-256が一致する |
| ロールバック | 特定バージョンのコードzipをダウンロードして復元できる |
| SDK | 生成メソッド名、multipart、バイナリレスポンスの扱いを確認済み |
| 監査 | 誰が、いつ、どのコミットを、どのエージェントバージョンに反映したか記録できる |
今回の更新でやるべきこと
今回のAzure REST API documentation updateは、コードベースエージェントをv1仕様の中で扱いやすくするための重要な変更です。一方で、PRの状態、Swaggerチェック、operationIdのレビュー、CodeAgents=V1Previewの残存を考えると、すぐに本番コードを全面移行するより、まずは検証環境で5つの操作を個別に確認するのが現実的です。(GitHub)
次に取るべき行動は明確です。OpenAPI v1に対象ルートが反映されているかを確認し、createAgentFromCode、updateAgentFromCode、createAgentVersionFromCode、downloadAgentCode、downloadAgentVersionCodeをステージングで試します。そのうえで、CI/CDにzip作成、SHA-256計算、multipartアップロード、バージョン記録、ダウンロード検証を組み込んでください。SDKを使う場合は、メソッド名とバイナリ処理が安定してから本番へ進めるのが安全です。
コメント