Azure REST API documentation update の今回の要点は、誤ったヘッダーに紐づいていた isolation key フィールドが仕様から削除されたことです。特に、Azure AI Foundry の hosted agent sessions を REST API や生成SDKで扱っている場合は、x-session-isolation-key を正しいヘッダーとして使い続けていないかを確認してください。現在のドキュメントでは、明示的にヘッダー分離を使う場合のヘッダーは x-ms-user-isolation-key と説明されています。(GitHub)
今回のAzure REST API documentation updateで変わったこと
今回の変更は、Azure REST API 全体の仕様変更というより、Azure AI Foundry の data plane API 仕様に含まれる hosted agent sessions 周辺の修正です。GitHub の Pull Request #42827 は「remove isolation key field that had wrong header」という内容で、2026年5月4日に feature/foundry-release ブランチへマージされています。対象は public preview の Data Plane API Specification Update です。(GitHub)
変更の中心は、TypeSpec 上に存在していた誤った isolation key 関連フィールドの削除です。PRの説明では、クライアントが送っていたヘッダーとバックエンドが参照しているヘッダーが異なっており、正しいヘッダーへ単純に差し替えると利用者のアプリが静かに壊れる可能性があるため、いったん誤ったフィールドを削除する判断が示されています。(GitHub)
具体的には、以下の2ファイルが変更されています。
| 変更対象 | 削除された内容 | 影響の見方 |
|---|---|---|
models.tsp | EntraAuthorizationScheme から isolation_key_source を削除 | Entra 認証方式のモデルに isolation key source が含まれる前提のコードは確認が必要 |
routes.tsp | session 作成・削除ルートから @header("x-session-isolation-key") isolation_key: string を削除 | REST呼び出しや生成クライアントで x-session-isolation-key を送っている場合は見直し対象 |
PR上では、models.tsp で1行、routes.tsp で8行が削除され、create session と delete session に関係するヘッダー定義が取り除かれています。(GitHub)
isolation key自体が廃止されたわけではない
注意したいのは、「isolation key フィールドが削除された」ことと「isolation key の考え方がなくなった」ことは別だという点です。
Microsoft Learn の hosted agent sessions の説明では、isolation key はセッションをスコープ分けする値とされています。認証・認可そのものは Microsoft Entra トークンとプロジェクトのロール割り当てで行われ、isolation key は、認証済みの呼び出し元がどのセッションに作用するかを絞り込むための値です。(Microsoft Learn)
つまり、今回の変更を次のように理解すると安全です。
| 誤解 | 正しい理解 |
|---|---|
| isolation key は不要になった | 不要になったとは限らない。Header方式では引き続き重要 |
x-session-isolation-key を使えばよい | 現在の説明では Header方式のヘッダーは x-ms-user-isolation-key |
| isolation key があれば認可できる | isolation key は認可機構ではなくスコープ分離の値 |
| セッションIDを使えば会話履歴も維持される | session continuity と conversation continuity は別物 |
特に、セッションIDはサンドボックスやファイル状態の継続に関係しますが、会話履歴そのものを自動的に再生するものではありません。Responses protocol では previous_response_id や conversation、Invocations protocol ではコンテナ側の状態管理が関係します。(Microsoft Learn)
誰が対応すべきか
今回の Azure REST API documentation update で確認すべきなのは、主に次のような開発者・運用担当者です。
| 対象者 | 確認すべきこと |
|---|---|
| Azure AI Foundry の hosted agent sessions をREST APIで呼び出している人 | x-session-isolation-key を送っていないか |
| TypeSpec / OpenAPI 仕様からクライアントを生成しているチーム | 再生成後に isolation_key パラメーターの有無が変わらないか |
| Python / JavaScript SDKのプレビュー機能を使っている人 | create/delete session 周辺の引数やヘッダー仕様を確認 |
| マルチテナント・ユーザー単位でセッション分離しているサービス | Header方式かEntra方式かを明確にし、分離キーの設計を見直す |
| CIでAPI仕様差分をチェックしているチーム | APIView や型定義の差分をリリース前に確認 |
PRでは APIView が TypeSpec、Python、JavaScript のAPIレビューを作成しているため、特に生成SDKや型定義に依存しているチームは、単なるドキュメント修正として流さない方が安全です。(GitHub)
一方で、Azure REST API を使っていても、Azure AI Foundry の hosted agent sessions を利用していない場合や、セッション作成・削除・ファイル操作・エージェント呼び出しに関係しないシステムでは、直接の影響は小さいと考えられます。
正しいヘッダーと設定の考え方
現在の Microsoft Learn では、session operations は preview feature とされており、RESTリクエストでは Foundry-Features: HostedAgents=V1Preview ヘッダーを含める必要があると説明されています。また、az rest で Foundry Agent Service の data-plane endpoint を呼び出す場合は、--resource "https://ai.azure.com" が必要です。(Microsoft Learn)
isolation key の扱いは、agent endpoint の authorization scheme によって変わります。
| authorization scheme | isolation key の扱い | 実装時の注意 |
|---|---|---|
Entra | Microsoft Entra トークンからプラットフォームが導出 | x-ms-user-isolation-key は受け付けられても無視される |
Header | x-ms-user-isolation-key ヘッダーから読み取る | セッション所有者ごとに安定した値を毎回送る必要がある |
Header方式で重要なのは、同じユーザーや同じテナントに対して安定したキーを使い続けることです。リクエストごとにランダムな値を入れると、作成したセッションを後続の取得・削除・ファイル操作で見つけられなくなる可能性があります。
REST呼び出しを見直す場合は、まず以下のようにヘッダー名を確認してください。
# 見直し対象
x-session-isolation-key
# Header方式で確認すべきヘッダー
x-ms-user-isolation-keyたとえば、Header方式で明示的にセッションを作成するREST呼び出しは、現在のドキュメントでは次のような考え方になります。
az rest --method POST \
--url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/sessions?api-version=${API_VERSION}" \
--resource "https://ai.azure.com" \
--headers "x-ms-user-isolation-key=user-123" "Foundry-Features=HostedAgents=V1Preview" \
--body '{}'削除時も、作成時と同じ isolation key を使う必要があります。Header方式ではキーが一致しないと、対象セッションに作用できません。Entra方式では、呼び出し元のIDに基づいてスコープが決まります。(Microsoft Learn)
既存コードの確認手順
今回の変更でまず行うべきことは、仕様書を読むことではなく、自分たちのコードが誤ったヘッダーに依存していないかを洗い出すことです。実務では、次の順番で確認すると漏れが少なくなります。
| 手順 | 作業 | 判断ポイント |
|---|---|---|
| 1 | リポジトリ内を検索 | x-session-isolation-key があれば優先的に修正候補 |
| 2 | RESTクライアントの共通ヘッダーを確認 | APIごとに不要なヘッダーを一括送信していないか |
| 3 | authorization scheme を確認 | Entra方式かHeader方式かを環境ごとに把握 |
| 4 | session 作成・取得・削除をテスト | 作成したセッションを同じキーで削除できるか |
| 5 | SDKや生成クライアントを更新 | 型エラー、引数名変更、ヘッダー生成の差分を確認 |
| 6 | CIに回帰テストを追加 | 誤ったヘッダーへ戻らないようにする |
検索は次のようなコマンドで十分です。
grep -R "x-session-isolation-key\|x-ms-user-isolation-key\|isolation_key_source\|isolation_key" .x-session-isolation-key が見つかった場合は、単純に x-ms-user-isolation-key へ置換する前に、まず agent endpoint が Header方式なのか Entra方式なのかを確認してください。Entra方式であれば、ヘッダーを送っても期待した分離制御には使われない可能性があります。
移行時に起きやすい失敗
今回のような API 仕様修正でよくある失敗は、ヘッダー名だけを直して終わりにしてしまうことです。しかし、実際にはセッション、会話、認証、分離キーがそれぞれ別の役割を持っています。
| 失敗パターン | 起きる問題 | 対策 |
|---|---|---|
x-session-isolation-key を使い続ける | バックエンドが期待するキーとして扱われない可能性がある | 最新ドキュメントに合わせてヘッダー名を確認 |
| Header方式なのにキーを毎回変える | 後続操作で同じセッションに到達できない | ユーザーIDやテナントIDなど安定した値を使う |
| Entra方式でヘッダー値に依存する | ヘッダーを送っても分離条件として使われない | Entraトークンとロール割り当てを前提に設計 |
agent_session_id だけで会話履歴が続くと思い込む | モデルへの文脈が維持されない | Responsesでは previous_response_id や conversation を併用 |
| Invocations protocol で body に session ID を入れる | プラットフォームのルーティングに使われない | agent_session_id はクエリ文字列に入れる |
Invocations endpoint では、agent_session_id はクエリ文字列から読み取られます。body内の agent_session_id や session_id、x-agent-session-id のようなヘッダーはコンテナへ渡されるだけで、プラットフォームのサンドボックスルーティングには使われないと説明されています。(Microsoft Learn)
SDK利用者が確認すべきポイント
SDKを使っている場合でも、今回の変更を完全に無視するのは危険です。PR上で Python と JavaScript の APIレビューが作成されているため、プレビュー版SDKや生成クライアントでは、引数や型定義に差分が出る可能性があります。(GitHub)
特に確認したいのは次の3点です。
create_sessionやdelete_sessionでisolation_keyを渡しているか- SDKの更新後に型エラーや警告が出ていないか
- RESTヘッダーをSDK外のラッパーで独自に追加していないか
Microsoft Learn では、Python SDK の create_session と delete_session は isolation_key キーワードを要求すると説明されています。ただし、サーバー側でそれが強制されるのは、agent endpoint が Header方式でキーを読むように設定されている場合です。(Microsoft Learn)
そのため、SDK利用者は「引数があるから常にサーバーで使われる」と考えない方が安全です。Entra方式とHeader方式で挙動が異なるため、環境ごとの認証方式を確認してからテストしてください。
変更後の動作確認で見るべきログとエラー
移行後は、単にビルドが通るかではなく、セッション分離が期待通りに機能しているかを確認します。おすすめは、少なくとも2つの異なるユーザーまたはテナント相当のキーでテストすることです。
| 確認項目 | 期待する結果 |
|---|---|
| user-123 でセッション作成 | セッションIDが返る |
| user-123 で同じセッションを取得 | 取得できる |
| user-456 で user-123 のセッションを取得 | 見えない、または操作できない |
| user-123 で削除 | 削除できる |
| 削除後に再取得 | セッションが存在しない状態になる |
エラーを見るときは、400 だけでなく、認証・認可・スコープ不一致に関わる 401、403、対象が見つからない 404 も確認してください。Header方式でヘッダーが欠けている場合、リクエスト自体が失敗する可能性があります。(Microsoft Learn)
今回の変更を受けた実務上の結論
今回の Azure REST API documentation update は、派手な新機能追加ではなく、プレビュー段階のAPI仕様をバックエンドの実装に合わせて整理するための修正です。しかし、生成SDKやRESTクライアントにとっては、ヘッダー名や引数の扱いが変わる可能性があるため、実装済みのシステムでは確認が必要です。
まずは、自分たちのコードに x-session-isolation-key が残っていないかを検索してください。次に、agent endpoint の authorization scheme が Entra方式かHeader方式かを確認し、Header方式であれば x-ms-user-isolation-key を安定した値で送る設計になっているかを検証します。最後に、セッション作成・取得・削除・ファイル操作・エージェント呼び出しを一通りテストし、セッション分離と会話継続を混同していないかを確認すると、今回の変更によるトラブルを避けやすくなります。
コメント