Azure REST APIの「Spec: add build_packages_remotely to CodeConfiguration」は、Hosted Agentのコード配置時に依存パッケージをどう解決するかを明示できるようにする仕様更新です。最初の提案名はbuild_packages_remotelyでしたが、最終的にマージされた内容ではブール値ではなく、CodeConfigurationにdependency_resolutionを追加し、bundledまたはremote_buildで指定する形に変更されています。既存のZIPに依存関係を同梱している運用は基本的にbundledを確認し、将来リモートビルドを使いたい場合はremote_buildの対応状況を慎重に見極める必要があります。(GitHub)
Azure REST APIのCodeConfiguration更新で何が変わったのか
今回のAzure REST API仕様更新は、Azure AI Foundry関連のHosted Agent定義で使われるCodeConfigurationモデルに、依存関係の解決方法を表す項目を追加するものです。
PR名は「Spec: add build_packages_remotely to CodeConfiguration」ですが、レビュー過程で設計が見直され、最終コミットではbuild_packages_remotelyという真偽値ではなく、dependency_resolutionという文字列ベースの選択肢に置き換えられました。選択肢はbundledとremote_buildです。(GitHub)
| 項目 | 変更前 | 変更後 |
|---|---|---|
| 依存関係の解決方法 | 明示する項目がない | dependency_resolutionで指定 |
| デフォルトの考え方 | 呼び出し側の実装やサービス既定に依存 | bundledが既定 |
| 依存関係をZIPに同梱する運用 | 暗黙的に行う | bundledとして明示可能 |
| サービス側で依存関係をビルドする運用 | 仕様上は表現しにくい | remote_buildとして表現可能 |
| 変更対象 | CodeConfiguration周辺 | TypeSpec、OpenAPI JSON/YAMLのv1およびvirtual-public-preview |
重要なのは、記事やPR名だけを見てbuild_packages_remotely: trueのような設定を実装しないことです。最終的な仕様ではdependency_resolutionを使う形になっているため、実装時はマージ後のOpenAPIまたはTypeSpecを確認してください。
build_packages_remotelyではなくdependency_resolutionになった理由
当初のbuild_packages_remotelyは、サービス側でパッケージをビルドするかどうかをtrueまたはfalseで指定する設計でした。たとえば、trueならrequirements.txtなどをもとにサービス側でPython依存関係を解決し、falseなら呼び出し側が依存パッケージをZIPに同梱済みとみなす、という意図です。(GitHub)
しかし、最終的には「何をするか」をより明確に表すdependency_resolutionへ変更されました。これは、単なるリモートビルドの有無ではなく、依存関係の解決戦略を指定する項目として扱うためです。PR内の最終コミットでは、将来ほかの依存関係解決方式を追加しやすい形にする意図も示されています。(GitHub)
実務上、この変更は小さく見えて重要です。ブール値は一見シンプルですが、将来「キャッシュ済み環境を使う」「ベースイメージに含める」「管理済み環境から解決する」といった別の選択肢が増えた場合に表現しにくくなります。dependency_resolutionのような文字列選択型であれば、APIの意味を保ったまま拡張しやすくなります。
追加されたdependency_resolutionの値と使い分け
dependency_resolutionには、少なくとも次の値が定義されています。OpenAPI上ではCodeDependencyResolutionというスキーマが追加され、bundledとremote_buildが列挙されています。(GitHub)
| 値 | 意味 | 向いているケース | 注意点 |
|---|---|---|---|
bundled | 呼び出し側が依存関係をZIPに同梱する。サービス側ではリモートビルドしない | 厳格なサプライチェーン管理、閉域環境、再現性を重視する本番環境 | ZIPサイズ、OSやPythonバージョンとの互換性、ネイティブ依存関係に注意 |
remote_build | アップロードしたZIP内のマニフェストをもとに、サービス側で依存関係をビルドする | 開発・検証、軽量なデプロイ、依存関係を同梱したくないケース | リモートビルド機能の提供状況、ビルド失敗、外部リポジトリアクセス制限に注意 |
既定値はbundledです。OpenAPIの説明でも、bundledでは呼び出し側がすべての依存関係をZIPに含め、サービスはリモートビルドを行わないと説明されています。remote_buildは、アップロードZIP内のマニフェストから依存関係をリモートでビルドする指定です。(GitHub)
判断基準は「誰が依存関係の責任を持つか」
設定を選ぶときは、単に便利かどうかではなく、依存関係の責任範囲で判断すると失敗しにくくなります。
bundledを選ぶべきなのは、ビルド済み成果物を自社側で検証してから配置したい場合です。たとえば、社内のCIでpip install -r requirements.txt -t ./packageのように依存関係を展開し、脆弱性スキャンやライセンスチェックを通したうえでZIP化する運用です。本番環境や規制の強い業務では、この方式のほうが監査しやすくなります。
一方、remote_buildは、ソースコードとrequirements.txtのようなマニフェストを渡して、サービス側で依存関係を解決させたい場合に向いています。ただし、リモートビルドはネットワーク、パッケージリポジトリ、ネイティブライブラリ、ビルド環境の差分で失敗しやすい領域です。PRのレビューでも、リモートビルドには非自明な失敗モードがある点が指摘されています。(GitHub)
対応が必要な人、すぐ確認すべき人
今回のAzure REST API更新で特に確認が必要なのは、Hosted Agentをコードベースで作成・更新している開発者、REST APIを直接呼んでいるチーム、OpenAPI定義からSDKや型定義を生成しているチームです。
| 対象者 | 確認すべきこと |
|---|---|
| REST APIを直接呼び出している開発者 | リクエストJSONのCodeConfigurationにdependency_resolutionが必要になるか |
| SDK生成をしているチーム | 生成後のモデルでdependency_resolutionが必須プロパティとして扱われるか |
| CI/CD担当者 | ZIP内に依存関係を同梱しているか、マニフェストだけを含めているか |
| セキュリティ・監査担当者 | 外部パッケージ取得をサービス側に任せてよいか |
| 既存サンプルを流用しているチーム | サンプルのCodeConfigurationが最新スキーマとずれていないか |
現時点のMicrosoft Learn上のPython向けCodeConfigurationドキュメントでは、変数としてruntimeとentry_pointが掲載されています。日本語の.NET向けプレビュー文書でも、プロパティとしてEntryPointとRuntimeが掲載されています。つまり、SDKドキュメントや言語別リファレンスがすぐに最新REST仕様へ追従しているとは限りません。実装時は、SDKドキュメントだけでなく、対象のREST API仕様や生成元のOpenAPIも確認するのが安全です。(Microsoft Learn)
既存実装への影響
今回の変更は、単に新しい説明文が増えただけではありません。OpenAPIのrequiredにdependency_resolutionが追加されています。v1とvirtual-public-previewのJSON/YAMLの両方で、runtime、entry_pointに加えてdependency_resolutionが必須項目として定義されています。(GitHub)
そのため、次のような影響が出る可能性があります。
REST APIリクエストの検証でエラーになる可能性
既存のリクエストが次のようにruntimeとentry_pointだけを送っている場合、クライアント側のスキーマ検証や生成SDKの型チェックで不足扱いになる可能性があります。
{
"runtime": "python_3_12",
"entry_point": ["python", "main.py"]
}新しい仕様を前提にするなら、依存関係を同梱している場合は次のようにdependency_resolutionを明示するのが安全です。
{
"runtime": "python_3_12",
"entry_point": ["python", "main.py"],
"dependency_resolution": "bundled"
}ただし、実際のペイロード構造はエンドポイントや親モデルの形に依存します。上記はCodeConfiguration部分だけを切り出した例です。
生成SDKのコンストラクタや型が変わる可能性
OpenAPIやTypeSpecからSDKを生成している場合、dependency_resolutionがコンストラクタ引数、必須プロパティ、または列挙型に近いモデルとして現れる可能性があります。既存コードでCodeConfiguration(runtime, entryPoint)のように作成している場合、生成結果によってはビルドエラーや警告が出ることがあります。
特にTypeScriptやC#のように型チェックが強い環境では、次の観点で差分を確認してください。
| 確認項目 | 見るポイント |
|---|---|
| コンストラクタ | 新しい引数が追加されていないか |
| モデル定義 | dependency_resolutionが必須か任意か |
| シリアライズ | 値を省略したときにbundledが送信されるか |
| デシリアライズ | 未知の値を受けたときに落ちないか |
| テスト | 既存のスナップショットJSONが失敗しないか |
サンプルコードと実運用コードの差が広がる可能性
PRの説明では、既存例は有効なままとされていますが、最終的なOpenAPIではdependency_resolutionがrequiredに追加されています。ここは注意が必要です。サービス側が既定値を補完する場合でも、SDKやAPIクライアントの検証レイヤーでは必須扱いになることがあります。
実運用では「サーバーが受け付けるか」だけでなく、「自社のクライアント、CI、APIゲートウェイ、契約テストが受け付けるか」まで確認してください。
移行・設定確認の進め方
今回の変更に対して、既存システムでは次の順番で確認すると無駄がありません。
| 手順 | 作業 | 判断ポイント |
|---|---|---|
| 1 | Hosted Agent作成・更新処理を洗い出す | CodeConfigurationを送信している箇所を特定 |
| 2 | ZIP作成方法を確認する | 依存関係をZIPに含めているか、マニフェストだけか |
| 3 | 既定の値を決める | 本番は原則bundled、検証でremote_buildを評価 |
| 4 | リクエストJSONまたはSDKモデルを更新する | dependency_resolutionを明示 |
| 5 | CIで契約テストを実行する | 生成SDK、OpenAPI検証、スナップショット差分を確認 |
| 6 | 失敗時のログを整備する | リモートビルド失敗時に原因を追えるようにする |
最初にやるべきことは、build_packages_remotelyという名前で実装していないか確認することです。初期のPRタイトルや説明をもとに実装を進めていた場合、最終仕様と名前が違っている可能性があります。
次に、依存関係をどこで解決しているかを確認します。CIで依存関係をZIPに入れているならbundledが自然です。ZIPにソースとrequirements.txtだけを入れている運用なら、remote_buildが該当しそうに見えますが、サービス側の対応状況や制約を確認してから使うべきです。
bundledを使う場合のチェックポイント
bundledは既定値として定義されており、もっとも堅実な選択肢です。依存関係を呼び出し側でZIPに含めるため、ビルド環境と実行環境の差を管理しやすく、監査もしやすくなります。
ただし、次の点を見落とすとデプロイ後に失敗します。
| チェック項目 | 失敗しやすい例 | 対策 |
|---|---|---|
| Pythonバージョン | CIはPython 3.11、実行はPython 3.12 | runtimeとCIのPythonを合わせる |
| OS依存パッケージ | macOSでビルドしたネイティブ依存をLinuxで実行 | 実行環境に近いLinuxコンテナでビルド |
| ZIP構造 | 依存パッケージが探索パス外にある | 実行時のimportパスを確認 |
| サイズ | 依存関係を入れすぎてZIPが肥大化 | 不要パッケージ、テスト、キャッシュを除外 |
| セキュリティ | 古い依存関係を同梱 | CIで脆弱性スキャンを実施 |
本番環境では、まずbundledを基準に考えるのが安全です。ビルド結果を自社で固定できるため、「昨日は動いたが今日はパッケージ取得で失敗した」といった外部要因を減らせます。
remote_buildを検討する場合の注意点
remote_buildは、依存関係をサービス側で解決できるため、デプロイZIPを軽くしやすいのが利点です。開発初期や検証環境では便利に見えるでしょう。
一方で、本番運用では次のリスクを確認する必要があります。
| リスク | 内容 | 確認方法 |
|---|---|---|
| パッケージ取得失敗 | 外部リポジトリにアクセスできない、認証が必要 | ビルドログ、ネットワーク制約、プライベートリポジトリ設定を確認 |
| バージョン不一致 | バージョン範囲指定により、想定外の最新版が入る | requirements.txtでバージョンを固定 |
| ネイティブビルド失敗 | コンパイラやOSライブラリ不足で失敗 | 依存パッケージのビルド要件を確認 |
| 再現性低下 | 時期によって解決結果が変わる | lockファイルやハッシュ固定を検討 |
| 監査難易度 | どの依存関係が入ったか追跡しにくい | ビルド成果物とログを保存 |
特に、規制産業、金融、医療、行政系システムなどでは、リモートビルドによって依存関係の取得経路が変わること自体がレビュー対象になります。remote_buildを使う場合は、単に「動くか」ではなく、「誰が、いつ、どの依存関係を取得したか」を追跡できるかまで確認してください。
実装時に避けたい失敗
今回の仕様更新で起きやすい失敗は、名前の取り違えと既定値の過信です。
まず、PR名に含まれるbuild_packages_remotelyをそのまま使わないでください。最終的に追加されたのはdependency_resolutionです。値もtrueまたはfalseではなく、bundledまたはremote_buildです。(GitHub)
次に、「既定値がbundledだから何もしなくてよい」と決めつけないことです。OpenAPI上ではdependency_resolutionがrequiredに含まれているため、クライアントやSDK生成の都合で明示指定が必要になる可能性があります。(GitHub)
最後に、remote_buildを安易に本番へ入れないことです。レビューコメントでもリモートビルドの失敗モードが指摘されており、依存関係の解決はネットワーク、パッケージ管理、ビルド環境、セキュリティポリシーが絡む領域です。(GitHub)
まず取るべき対応
今回のAzure REST API documentation updateを受けて、すぐに行うべき対応は次の3つです。
まず、Hosted Agentの作成・更新でCodeConfigurationを使っている箇所を検索してください。REST APIのJSON、生成SDKのモデル、IaC、社内ラッパー、テスト用スナップショットが対象です。
次に、依存関係の運用方針を決めます。現時点で依存パッケージをZIPに同梱しているなら、dependency_resolutionにbundledを明示する方針が現実的です。ソースとマニフェストだけをアップロードしたい場合は、remote_buildを検証環境で試し、失敗時のログ、再現性、セキュリティレビューを確認してから本番適用を検討してください。
最後に、SDKドキュメントだけで判断しないことが重要です。Microsoft Learnの言語別SDKドキュメントには、現時点でruntimeとentry_pointのみが掲載されているページもあります。REST API仕様、OpenAPI差分、生成SDKの実際の型定義を合わせて確認することで、実装のズレを避けられます。(Microsoft Learn)
今回の変更は、依存関係の解決方法をAPI契約として明確にするための更新です。既存運用ではbundledを基準に安全性と再現性を確認し、remote_buildは便利さだけでなく、失敗時の調査性とサプライチェーン管理まで含めて判断しましょう。
コメント