Azure SDKの azure-ai-projects を利用している開発チームは、今回の更新で「評価者を生成するジョブ操作の追加」と「isolation_key 関連APIの削除」を優先して確認すべきです。特に、Python SDKで .beta.evaluators を使っている場合、または Hosted agents / beta agents のセッション作成・削除処理に isolation_key を渡している場合は、アップデート前にコード検索とスモークテストを行ってください。
この更新は、Azure SDK for Pythonの azure-ai-projects に対するPRとして2026年5月5日にマージされ、対象ブランチは feature/azure-ai-projects/2.2.0 です。PR本文では、TypeSpecからSDKを生成し、Evaluator generation jobsを追加し、isolation_key 関連のモデルや引数を削除する変更として整理されています。(GitHub)
Azure SDKの今回の更新でまず押さえるべき結論
今回のAzure SDK documentation updateは、単なるドキュメント文言の修正ではなく、azure-ai-projects のAPI形状に影響する更新です。とくに重要なのは次の3点です。
| 確認項目 | 内容 | 影響を受けやすい人 |
|---|---|---|
| Evaluator generation jobsの追加 | .beta.evaluators に生成ジョブ系の操作が追加 | 評価者の作成や評価ワークフローを自動化したい開発者 |
isolation_key 関連の削除 | IsolationKeySource 系モデルや IsolationKeySourceKind が削除対象 | Hosted agents / beta agents のセッション分離を実装していたチーム |
| TypeSpec生成によるAPI名の整理 | TypeSpecソースからSDKをEmitし、body のような汎用引数名をより具体的な名前へ変更する流れ | キーワード引数でSDKメソッドを呼び出しているPythonユーザー |
PRでは、新しいEvaluator generation job操作として create_generation_job、get_generation_job、list_generation_jobs、cancel_generation_job、delete_generation_job が .beta.evaluators に追加されたと説明されています。あわせて、EvaluatorGenerationJob、RubricBasedEvaluatorDefinition、RubricCriterion、DatasetReference などのモデル、EvaluatorGenerationJobSourceType、EvaluatorDefinitionType.RUBRICS も追加対象です。(GitHub)
一方で、EntraIsolationKeySource、HeaderIsolationKeySource、IsolationKeySource といったモデル、IsolationKeySourceKind enum、BetaAgentsOperations.create_session の isolation_key パラメーターが削除対象として示されています。PR本文では create_session に version_indicator と agent_session_id の明示的なキーワード引数が追加されたことも記載されています。(GitHub)
今回の変更は誰が対応すべきか
すべてのAzure SDK利用者がすぐに修正作業をする必要はありません。影響が大きいのは、Python向け azure-ai-projects を使い、かつプレビュー・ベータ系の評価機能やエージェントセッション機能に触れているケースです。
| 利用状況 | 対応優先度 | やるべきこと |
|---|---|---|
.beta.evaluators を利用している | 高 | 新しいgeneration job操作の有無を確認し、既存のEvaluator作成フローとの差分を整理する |
create_session() に isolation_key を渡している | 高 | コード検索し、削除された引数を使わない形に修正する |
IsolationKeySource 系モデルをimportしている | 高 | importエラーや型エラーが出るため、代替設計を確認する |
azure-ai-projects を固定バージョンで本番運用している | 中 | すぐに壊れる可能性は低いが、次回アップデート前に差分検証を行う |
| JavaScriptや.NET版だけを使っている | 低〜中 | 今回のPRはPythonリポジトリの変更だが、サービス仕様の反映状況は言語別に確認する |
| Azure AI Projectsを使っていない | 低 | 直接の対応は不要 |
現時点のMicrosoft Learnでは、Azure AI Projects client library for PythonはMicrosoft Foundry SDKの一部で、.evaluation_rules、.beta.evaluation_taxonomies、.beta.evaluators、.beta.insights、.beta.schedules などで評価関連機能を扱うと説明されています。(Microsoft Learn)
また、PyPI上の azure-ai-projects は2026年5月6日時点で最新表示が 2.1.0、リリース日は2026年4月20日です。今回のPRは feature/azure-ai-projects/2.2.0 ブランチへのマージであり、実際に手元の環境へ反映されるタイミングはパッケージ公開状況を確認して判断してください。(PyPI)
TypeSpecからSDKをEmitするとは何か
今回のPR名にある「Emit SDK from TypeSpec」は、API仕様をTypeSpecで定義し、その定義からSDKコードを生成することを意味します。
TypeSpecはMicrosoftが開発・支援するAPI設計用の言語で、TypeSpecコンパイラとEmitterによってAPI仕様、クライアントコード、サーバー側コードなどを生成できます。Microsoft Learnでも、TypeSpecはPythonを含む複数言語のクライアントコード生成に対応すると説明されています。(Microsoft Learn)
この点が重要なのは、SDKの変更が「手書きの便利メソッド追加」ではなく、API仕様の変更を反映した生成物として現れるためです。つまり、次のような変更が起こりやすくなります。
| TypeSpec由来の変更 | 開発現場で起きること |
|---|---|
| モデル名・enum名の追加 | importできる型が増える |
| 操作名の追加 | .beta.evaluators.create_generation_job() のようなメソッドが増える |
| 引数名の整理 | body のような曖昧な引数名が、job や taxonomy など具体的な名前へ変わる |
| 不要なモデル削除 | 古いimportや型注釈が失敗する |
| ベータAPIの仕様更新 | 以前動いていたキーワード引数がエラーになる |
今回のTypeSpecソースは、azure-rest-api-specs の feature/foundry-release ブランチにあるコミット 146c19ec からEmitされたとPRに記載されています。コミットメッセージは「emitted SDK内の body より説明的な入力引数名を使う」という趣旨です。(GitHub)
該当コミットでは、TypeSpec側で @body body が taxonomy や job に変更されている箇所が確認できます。これは、Pythonでキーワード引数を明示して呼び出しているコードに影響する可能性があります。(GitHub)
追加されたEvaluator generation jobsの見方
今回の機能追加で注目すべきなのは、評価者そのものを管理するだけでなく、評価者を生成するジョブを扱えるようになる点です。
従来のEvaluator操作は、EvaluatorVersionの作成、取得、一覧、更新、削除といった「評価者定義の管理」が中心でした。Microsoft Learn上の BetaEvaluatorsOperations でも、現行のAPIリファレンスには create_version、get_version、list、list_versions、update_version、delete_version といった操作が掲載されています。(Microsoft Learn)
今回追加されるgeneration job操作は、評価者を生成する処理をジョブとして作成・取得・一覧・キャンセル・削除する流れを扱うものです。生成元の種類として PROMPT、AGENT、TRACES、DATASET が定義されているため、プロンプト、エージェント、トレース、データセットを材料に評価者生成を行う設計だと考えると理解しやすいです。(GitHub)
実務で想定される活用シーン
Evaluator generation jobsは、次のような場面で役立つ可能性があります。
| 活用シーン | 期待できる効果 |
|---|---|
| エージェント評価の初期設計 | 既存のAgentやPromptから評価観点を作る流れを自動化しやすい |
| RAGやチャットボットの継続評価 | DatasetやTracesをもとに、評価者定義の更新サイクルを作りやすい |
| 品質基準の標準化 | Rubricベースの評価者定義を使い、チーム間で評価軸をそろえやすい |
| CI/CDとの連携 | 評価者生成、評価実行、結果確認をパイプライン化しやすい |
ただし、.beta 配下の機能である点には注意が必要です。ベータ操作は将来のSDK更新でメソッド名、引数、モデル構造が変わる可能性があります。本番ワークロードに組み込む場合は、SDKバージョンを固定し、更新時に自動テストを必ず通す運用にしてください。
isolation_key削除で壊れやすいコード
今回のBreaking Changesで最も注意すべきなのは、isolation_key を前提にしていたコードです。
PR本文では、EntraIsolationKeySource、HeaderIsolationKeySource、IsolationKeySource の削除、IsolationKeySourceKind の削除、BetaAgentsOperations.create_session からの isolation_key パラメーター削除が示されています。(GitHub)
さらにPR内のCHANGELOG差分では、beta operationsのBreaking changesとして、EntraAuthorizationScheme から必須プロパティ isolation_key_source が削除されたこと、.beta.agents.create_session() と .beta.agents.delete_session() から必須キーワード引数 isolation_key が削除されたことが記載されています。(GitHub)
まず検索すべきキーワード
アップデート前に、リポジトリ全体で次の文字列を検索してください。
grep -R "isolation_key" .
grep -R "IsolationKeySource" .
grep -R "HeaderIsolationKeySource" .
grep -R "EntraIsolationKeySource" .
grep -R "IsolationKeySourceKind" .PowerShellを使う場合は次のように検索できます。
Select-String -Path .\* -Pattern "isolation_key","IsolationKeySource","HeaderIsolationKeySource","EntraIsolationKeySource","IsolationKeySourceKind" -Recurseヒットした箇所は、単に削除すればよいとは限りません。isolation_key は、ユーザー、会話、テナント、セッションなどを分離する設計意図で使われていた可能性があります。引数が削除された場合でも、アプリ側で必要な分離要件が消えるわけではありません。
確認すべき観点は次のとおりです。
| 観点 | 確認内容 |
|---|---|
| セッション識別 | agent_session_id など、明示的なセッションIDを使う設計に変わっているか |
| バージョン指定 | version_indicator を指定すべき場面があるか |
| 認可境界 | Microsoft Entra ID、RBAC、Foundry Project単位の権限で分離できているか |
| ログ・監査 | 旧 isolation_key をログや監査キーとしても使っていなかったか |
| テストデータ | 同一ユーザー・別ユーザー・別テナント相当のケースでデータが混ざらないか |
移行時に実施するチェックリスト
SDK更新時は、いきなり pip install -U azure-ai-projects を本番環境で実行するのではなく、検証環境で次の順番に進めるのが安全です。
| 手順 | 作業 | 判断基準 |
| -: | ————————— | —————————————- |
| 1 | 現在のSDKバージョンを確認 | 2.1.0 以前か、次期 2.2.0 系を検証しているかを把握する |
| 2 | isolation_key 関連を検索 | ヒットがあればBreaking Change対応が必要 |
| 3 | .beta.evaluators の使用箇所を確認 | 既存のEvaluator作成・更新処理とgeneration jobを混同しない |
| 4 | importエラーを確認 | 削除モデルをimportしていないか確認 |
| 5 | キーワード引数の変更を確認 | body= のような汎用引数名を使っていないか確認 |
| 6 | 型チェック・単体テストを実行 | mypy、pyright、pytestなどで早期に検出する |
| 7 | Foundry Project上でスモークテスト | セッション作成、削除、評価者一覧、評価ジョブ作成を最小ケースで確認する |
| 8 | 本番反映前にバージョン固定 | requirements.txt やlockファイルで再現性を確保する |
現在のバージョン確認は次のコマンドで行えます。
python -m pip show azure-ai-projectsメソッドの有無を確認したい場合は、実際に利用しているSDKをインストールした検証環境で、Pythonのイントロスペクションを使うと確実です。
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
import os
import inspect
client = AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
)
for name in [
"create_generation_job",
"get_generation_job",
"list_generation_jobs",
"cancel_generation_job",
"delete_generation_job",
]:
print(name, hasattr(client.beta.evaluators, name))
if hasattr(client.beta.evaluators, "create_generation_job"):
print(inspect.signature(client.beta.evaluators.create_generation_job))この確認は、Microsoft LearnのAPIリファレンス更新を待たずに、手元のSDKに実際にどのメソッドが存在するかを把握できる点が実務的です。
create_session周りの修正イメージ
create_session に isolation_key を渡していたコードは、SDK更新後に TypeError になる可能性があります。修正時は、まず「旧キーで何を分離していたのか」を明確にしてください。
概念的には、次のような見直しになります。
# 旧: isolation_key をセッション分離のために渡していた例
session = client.beta.agents.create_session(
...,
isolation_key=user_or_tenant_key,
)# 新: isolation_key は渡さない
# version_indicator や agent_session_id の指定要否は、利用中SDKの型ヒント・APIリファレンス・実際のsignatureで確認する
session = client.beta.agents.create_session(
...,
version_indicator=version_indicator,
agent_session_id=agent_session_id,
)ここで重要なのは、isolation_key を削除するだけで終わらせないことです。たとえば、旧実装で tenant_id を isolation_key に入れていた場合、削除後に同じアプリケーション内でテナント境界をどう表現するのかを確認する必要があります。
確認不足のまま移行すると、次のような失敗が起こりやすくなります。
| 失敗例 | 原因 | 対策 |
|---|---|---|
セッション作成で unexpected keyword argument 'isolation_key' が出る | 削除された引数を渡している | 呼び出し箇所を検索し、SDKの現行signatureに合わせる |
import時に IsolationKeySource が見つからない | 削除モデルをimportしている | 型注釈・モデル生成・テストデータから削除する |
| セッション削除処理だけ失敗する | delete_session() 側にも isolation_key を渡している | 作成・取得・削除をセットで検索する |
| ユーザー間の会話分離が曖昧になる | isolation_key をアプリ側の設計キーとして使っていた | agent_session_id、認可、DB側の所有者管理を再設計する |
| CIでは通るが本番で失敗する | SDKバージョンが環境ごとに違う | lockファイルとデプロイログでバージョンを固定・記録する |
Evaluator generation jobsを導入する前に確認する設定
Evaluator generation jobsは便利な追加ですが、導入前にSDKメソッドだけでなく、Foundry Project、認証、データセット、トレースの準備も確認してください。
Azure AI Projects client library for Pythonは、利用前提としてPython 3.9以降、Azureサブスクリプション、Microsoft Foundry Project、Foundry project endpointを必要とします。認証ではAPIキーまたはMicrosoft Entra IDに関する説明があり、Entra ID利用時は DefaultAzureCredential などの TokenCredential 実装を使います。(Microsoft Learn)
Evaluator generation jobsを実務に入れる場合は、次の観点を先に整理しておくと、後から手戻りしにくくなります。
| 確認項目 | 具体的に見ること |
|---|---|
| 生成元 | Prompt、Agent、Traces、Datasetのどれを使うか |
| 評価基準 | Rubricベースの基準を誰が承認するか |
| データ品質 | DatasetやTraceに個人情報・機密情報が含まれていないか |
| 権限 | 評価者生成に必要なFoundry Project上のロールが付与されているか |
| コスト | ジョブ生成や評価実行が継続的に走る場合の利用量を監視できるか |
| 再現性 | 同じ入力から同じ評価基準を再現・レビューできるか |
| 監査 | 生成されたEvaluatorを誰がいつ使ったか追跡できるか |
特に、TracesやDatasetを生成元に使う場合は、評価者の品質だけでなく、入力データの取り扱いが重要です。評価に使うデータが偏っていると、生成されたEvaluatorも偏った基準になりやすくなります。
ドキュメント更新と実パッケージ更新のズレに注意
Azure SDK関連の更新では、GitHub PR、Microsoft Learn、PyPI、実際の手元環境の反映タイミングが一致しないことがあります。
今回も、PRは2026年5月5日にマージされていますが、PyPI上の最新安定表示は2026年4月20日リリースの azure-ai-projects 2.1.0 です。(GitHub)
そのため、次のように判断してください。
| 状況 | 判断 |
|---|---|
| PRはマージ済みだがPyPIに新バージョンがない | まだ通常インストールでは反映されていない可能性がある |
| Microsoft Learnに新メソッドが載っていない | ドキュメント反映が遅れている可能性がある |
| 手元SDKに新メソッドがある | 実パッケージを基準にテストする |
| 本番環境と開発環境で挙動が違う | まず pip show azure-ai-projects でバージョン差を確認する |
--pre を使っている | プレビュー版を取得している可能性があるため、lockファイルを必ず確認する |
実務では、PRやドキュメントを見て「すでに全環境で使える」と判断しないことが重要です。導入前に、インストール済みバージョン、APIリファレンス、実際のメソッドsignatureを3点セットで確認してください。
実装チーム向けの移行判断基準
最後に、今回のAzure SDK更新に対して「すぐ対応する」「検証だけする」「様子を見る」を判断する基準を整理します。
すぐ対応すべきケース
次のいずれかに当てはまる場合は、早めに検証環境で修正を始めてください。
isolation_keyをcreate_session()またはdelete_session()に渡しているIsolationKeySource系モデルをimportしている.beta.evaluatorsを使った評価機能を開発中- 次期
azure-ai-projectsへのアップデートを予定している - TypeSpec生成後のSDKを前提にAPIラッパーを作っている
検証だけしておくケース
次のケースでは、すぐ本番修正は不要でも、CI上で新バージョンの互換性テストを走らせる価値があります。
- 現在は
azure-ai-projects 2.1.0以前で固定している - 評価機能は使っているが、EvaluatorVersionの一覧・取得が中心
- Hosted agentsは使っているが、セッション分離を独自DBで管理している
- 今後、Rubricベース評価やDatasetベース評価を導入する予定がある
当面様子見でよいケース
次のケースは、今回の更新による直接影響は限定的です。
- Azure AI Projectsを使っていない
- Python SDKではなく、別言語SDKだけを使っている
.beta配下の機能を使っていない- SDKを固定し、自動アップデートしない運用にしている
ただし、Azure AI FoundryやAzure SDKは継続的に更新されます。将来的に評価機能やエージェント機能を使う予定があるなら、今回の変更点は把握しておくと移行時のトラブルを減らせます。
まず取るべき次の行動
今回の更新で最初にやるべきことは、新機能を試すことではなく、既存コードがBreaking Changesに触れていないかを確認することです。
まず、pip show azure-ai-projects でバージョンを確認し、リポジトリ内で isolation_key と IsolationKeySource 系の文字列を検索してください。ヒットがなければ、次に .beta.evaluators の利用箇所を確認し、Evaluator generation jobsを導入する価値があるかを検討します。
一方、isolation_key がヒットした場合は、セッション分離の設計を見直してからSDK更新を進めるべきです。単に引数を消すだけでは、ユーザー単位・テナント単位・会話単位の分離要件を満たせなくなる可能性があります。
Azure SDKの azure-ai-projects は、Microsoft Foundry SDKの中でも評価、エージェント、データセット、トレースに関わる変化の速い領域です。今回のTypeSpec由来の更新をきっかけに、SDKバージョン固定、API差分テスト、ベータ機能の利用範囲を見直しておくと、今後の更新にも対応しやすくなります。
コメント