Azure AI Projects SDK for Python 2.1.0の変更点まとめ｜実務で最初に確認すべき影響

Azure AI Projects SDK for Python 2.1.0 は、Hosted Agents、Agent endpoint、評価機能、トレーシングを使っているチームほど早めに確認したい更新です。特に実務で最初に見るべきポイントは、get_openai_client(agent_name=...) の追加、.beta.agents によるセッション操作、beta.skills / beta.toolboxes の追加、そして「トレーシング有効時に trace context propagation がデフォルトで有効になる」破壊的変更です。公式リリースでは 2026年4月20日付けで azure-ai-projects_2.1.0 が公開され、PyPI 上でも azure-ai-projects 2.1.0 が同日にリリースされています。(GitHub)

この記事では、Azure AI Projects SDK for Python の利用者が「まず何を確認し、どのコードや運用に影響が出るか」を実務目線で整理します。Python developers、AI application teams、Azure AI builders が、アップデート判断・影響調査・検証タスクにそのまま使えるよう、変更点を優先度順にまとめます。

Azure AI Projects SDK for Python 2.1.0 の位置づけ

Azure AI Projects SDK for Python は、Microsoft Foundry SDK の一部として提供される Python 向けクライアントライブラリです。Microsoft Foundry Project の Agent、デプロイ済みモデル、接続、データセット、インデックス、評価、ファインチューニングなどへアクセスするために使われます。Microsoft Learn の概要ページでは、バージョン 2.1.0 のライブラリとして紹介されており、Microsoft Foundry の data plane REST API v1 を利用すると説明されています。(Microsoft Learn)

インストール自体は従来通りです。

python -m pip install --upgrade azure-ai-projects azure-identity
python -m pip show azure-ai-projects

PyPI のメタデータでは、azure-ai-projects 2.1.0 は Python 3.9 以上を要求しています。既存プロジェクトで Python 3.8 以前が残っている場合は、SDK 更新より先にランタイム更新の要否を確認してください。(PyPI)

最初に確認すべき変更点まとめ

確認項目	影響を受けやすい利用者	実務で見るべきポイント
get_openai_client(agent_name=...) の追加	Hosted Agents、Agent endpoint を使うチーム	Agent endpoint へルーティングするコードに置き換えられるか
.beta.agents の Session 操作追加	Hosted Agents を運用するチーム	セッション作成、一覧、削除、ファイル操作を SDK から扱えるか
beta.skills / beta.toolboxes の追加	エージェント機能を部品化・再利用したいチーム	Skills と Toolboxes の管理を CI/CD や管理スクリプトに組み込めるか
評価 API 向け TypedDict の追加	Evals を Python で実装しているチーム	.evals.create()、.evals.runs.create() の入力定義を型補完に寄せられるか
トレーシングの破壊的変更	Azure Monitor、OpenTelemetry、Application Insights を使うチーム	trace ID の外部送信、コンプライアンス、ログ設計を確認する
サンプルの環境変数名変更	サンプルベースで検証・CI を作っているチーム	FOUNDRY_PROJECT_ENDPOINT など新しい命名に合わせる

この更新は、単なる小規模な型修正ではありません。Hosted Agents の扱い、評価コードの書きやすさ、監視・トレーシングの挙動に関わるため、本番環境へ反映する前に「コード」「環境変数」「観測基盤」「CI/CD」の4点をまとめて確認するのが安全です。

get_openai_client(agent_name=...) で Agent endpoint を扱いやすくなった

2.1.0 の目立つ変更は、AIProjectClient の get_openai_client() が任意引数 agent_name を受け取れるようになった点です。agent_name を指定すると、返却される OpenAI client は Foundry Project endpoint ではなく、Agent endpoint の base URL を使います。Agent endpoint は preview 機能のため、AIProjectClient のコンストラクターで allow_preview=True を指定する必要があります。(GitHub)

Microsoft Learn の API リファレンスでも、agent_name を渡した場合は Agent endpoint に向けた OpenAI client になり、allow_preview=True が設定されていない場合は ValueError が発生すると説明されています。(Microsoft Learn)

実務では、次のようなコードを確認します。

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

openai_client = project.get_openai_client(
    agent_name=os.environ["FOUNDRY_AGENT_NAME"]
)

ここで重要なのは、allow_preview=True を「なんとなく付ける」のではなく、preview 機能を使うコードパスを明確に分けることです。たとえば、本番環境では Agent endpoint を使うサービスだけに allow_preview=True を許可し、通常のモデル呼び出しや評価処理では project-scoped endpoint のままにする、といった分離が考えられます。

既存コードで確認したいポイント

従来の Hosted Agents 呼び出しで、Agent の参照情報を extra_body に詰めていたコードや、endpoint URL を手作業で組み立てていたコードは、get_openai_client(agent_name=...) に置き換えられる可能性があります。Microsoft の移行ドキュメントでも、Agent invocation code では extra_body の agent_reference ではなく、project.get_openai_client(agent_name=...) を使うことがチェックリストに含まれています。(Microsoft Learn)

ただし、置き換え時には次の点を確認してください。

確認箇所	見落としやすい失敗
allow_preview=True	付け忘れると agent_name 指定時に例外になる
環境変数	旧サンプル名のまま残っていると endpoint や agent 名を読み込めない
エンドポイント種別	Foundry Project endpoint と Agent endpoint を混同する
認証	ローカルでは動くが、CI/CD や本番の Managed Identity で権限不足になる
テスト	Agent endpoint 経由の応答、通常のモデル応答、評価処理を分けて確認しない

Hosted Agents 利用者は .beta.agents の Session 操作を確認する

2.1.0 では .beta.agents サブクライアントが追加され、Hosted Agents 向けの Session 操作が利用できるようになりました。公式リリースでは、create_session()、delete_session()、get_session()、list_sessions()、セッションファイルの upload / download / delete などが追加されています。(GitHub)

Microsoft Learn の Hosted Agents セッション管理ドキュメントでは、Python SDK の前提条件として azure-ai-projects>=2.1.0 と azure-identity が示され、Session 操作は preview sub-client の project.beta.agents を使うと説明されています。(Microsoft Learn)

基本形は次のようになります。

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project = AIProjectClient(
    endpoint="<your-project-endpoint>",
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

session = project.beta.agents.create_session(
    agent_name="my-agent",
    isolation_key="user-123",
    body={},
)

Hosted Agents のセッションは、ユーザー・テナント・ワークロード単位で状態を分離したい場合に重要です。Microsoft Learn では、セッション作成時の isolation_key はセッション所有者を識別する値であり、ユーザーやテナントなどの論理境界に使えると説明されています。(Microsoft Learn)

セッション設計で決めておくべきこと

Hosted Agents を実務で使う場合、SDK のメソッド名だけを覚えても不十分です。先に次の設計を固めると、後から権限やデータ分離で詰まりにくくなります。

設計項目	判断基準
isolation_key の単位	個人ユーザー単位、法人テナント単位、ジョブ単位のどれで状態を分けるか
セッションの寿命	1リクエストごとに破棄するか、会話・タスク単位で再利用するか
ファイル操作の扱い	セッションに紐づく一時ファイルをいつ削除するか
ログと監査	agent 名、session ID、ユーザー識別子をどこまで記録するか
エラー時の後片付け	例外発生時に session / file を削除する処理を入れるか

特にファイルアップロードを使う場合は、セッションに紐づくファイルがどのタスクで使われ、いつ不要になるかを明確にしておきましょう。検証環境では動いても、本番では不要ファイルの残存、ユーザー間の取り違え、監査ログ不足が問題になりやすい領域です。

beta.skills と beta.toolboxes はエージェント機能の再利用に効く

2.1.0 では、beta.skills サブクライアントと beta.toolboxes サブクライアントも追加されました。公式リリースでは、Skills について create()、create_from_package()、delete()、download()、get()、list()、update() が追加され、Toolboxes について create_version()、get_version()、list_versions()、delete_version() などが追加されています。(GitHub)

実務上は、以下のようなチームで確認価値が高い変更です。

利用シーン	期待できる効果
複数の Agent で共通ツールを使う	ツールやスキルを個別実装ではなく管理対象として扱いやすくなる
開発・検証・本番で Agent 構成をそろえる	Skills / Toolboxes の作成や更新をスクリプト化しやすくなる
Agent 機能を段階的にリリースする	Toolbox version を使った更新管理を検討できる
チーム内で部品を再利用する	Python コード、設定、パッケージ管理の境界を明確にしやすい

一方で、名前に beta が含まれる通り、安定版の業務 API と同じ感覚で無条件に本番へ組み込むのは避けたいところです。まずは検証環境で、作成・更新・削除・バージョン管理・権限エラー時の挙動を確認してから、運用スクリプトに組み込むのが現実的です。

評価コードでは TypedDict の追加が地味に大きい

2.1.0 では、AIProjectClient.get_openai_client() で取得した OpenAI client に対して、.evals.create() と .evals.runs.create() の型ヒントが追加されました。公式リリースでは、ModelSamplingConfigParam、AzureAIAgentTargetParam、AzureAIModelTargetParam、EvalCsvRunDataSource、RedTeamEvalRunDataSource など複数の TypedDict クラスが追加されたと説明されています。(GitHub)

これは、評価処理を本格的に運用しているチームほど恩恵があります。Evals 系の入力はネストが深くなりやすく、辞書のキー名や構造を誤ると、実行時エラーや期待しない評価結果につながります。TypedDict によって、エディター補完、型チェック、レビュー時の見通しが改善されます。

評価チームが見直すべきコード

評価処理が次のような状態なら、2.1.0 への更新後に型ヒントを活かす価値があります。

既存の状態	見直し方
評価設定を大きな dict で直接書いている	TypedDict に合わせて入力構造を分割する
CSV 評価や synthetic data 評価を試している	新しいサンプルに合わせてデータソース指定を確認する
評価コードが属人化している	型補完と小さな設定関数でレビューしやすくする
実行時まで入力ミスに気づけない	mypy、pyright、IDE 補完を導入する

評価は「一度動けばよい」処理ではなく、モデル変更、プロンプト変更、ツール変更のたびに回す品質ゲートになり得ます。2.1.0 の型ヒント強化は、評価処理を実験コードから運用品質へ近づける材料として見ておくとよいでしょう。

破壊的変更：トレーシング有効時の trace context propagation

今回もっとも注意すべき変更は、トレーシングに関する breaking change です。2.1.0 では、トレーシングが有効な場合、trace context propagation がデフォルトで有効になります。公式リリースでも「Tracing: trace context propagation is enabled by default when tracing is enabled」と明記されています。(GitHub)

Microsoft Learn / PyPI の説明では、trace context propagation が有効な場合、get_openai_client() で取得した OpenAI client が行う HTTP リクエストに W3C Trace Context headers の traceparent と tracestate が自動挿入されます。これにより、クライアント側 span と Azure OpenAI などのサーバー側 span を同一 trace ID で関連付けやすくなります。(PyPI)

便利な変更ですが、監査・セキュリティ・プライバシーの観点では必ず確認が必要です。ドキュメントでは、trace ID がサービスへ送信されること、プライバシーやコンプライアンス要件で trace identifier の共有が許容されない場合は無効化できることも説明されています。(PyPI)

無効化する場合の代表例は次の通りです。

export AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION=false

または、計装時に明示します。

AIProjectInstrumentor().instrument(
    enable_trace_context_propagation=False
)

監視基盤で確認するチェックリスト

確認項目	確認内容
トレーシングを有効化しているか	AIProjectInstrumentor().instrument() や Azure Monitor 設定を使っているか
trace ID の送信が許容されるか	社内規程、顧客契約、ログ管理ルールに反しないか
baggage propagation を有効化していないか	baggage には任意の key-value が入る可能性があるため、PII や認証情報の混入を確認する
content recording を有効化していないか	メッセージ本文、ツール引数、戻り値が trace に含まれる可能性を確認する
既存 client の再取得が必要か	設定変更後、既に取得済みの OpenAI client には反映されない場合がある

ドキュメントでは、baggage propagation は trace context propagation が有効な場合でもデフォルトでは含まれないと説明されています。一方で、baggage にはユーザー識別子、セッション情報、認証情報、業務メタデータ、PII が含まれる可能性があるため、明示的に有効化する場合は内容を監査する必要があります。(PyPI)

サンプルの環境変数名変更に注意する

2.1.0 のサンプル更新では、環境変数名が次のように変更されています。公式リリースでは、すべてのサンプルで AZURE_AI_PROJECT_ENDPOINT が FOUNDRY_PROJECT_ENDPOINT に、AZURE_AI_MODEL_DEPLOYMENT_NAME が FOUNDRY_MODEL_NAME に、AZURE_AI_MODEL_AGENT_NAME が FOUNDRY_AGENT_NAME に変更されたと説明されています。(GitHub)

旧サンプル名	新サンプル名
AZURE_AI_PROJECT_ENDPOINT	FOUNDRY_PROJECT_ENDPOINT
AZURE_AI_MODEL_DEPLOYMENT_NAME	FOUNDRY_MODEL_NAME
AZURE_AI_MODEL_AGENT_NAME	FOUNDRY_AGENT_NAME

この変更は SDK の API 変更そのものではありませんが、サンプルコードをベースにした検証環境や CI/CD では影響が出やすいポイントです。

たとえば、GitHub Actions、Azure DevOps、Docker Compose、.env、Kubernetes Secret に旧名が残っていると、サンプルを更新しただけで実行時に環境変数が見つからなくなります。SDK 更新時は、コードだけでなく設定ファイルも検索してください。

grep -R "AZURE_AI_PROJECT_ENDPOINT\|AZURE_AI_MODEL_DEPLOYMENT_NAME\|AZURE_AI_MODEL_AGENT_NAME" .

見つかった場合は、単純置換する前に「その変数を自社コードでも使っているのか」「公式サンプル由来の変数なのか」を分けて判断します。社内の既存命名を維持する場合は、サンプル側だけを薄い変換レイヤーで吸収する方法もあります。

アップデート前に確認する実務手順

Azure AI Projects SDK for Python 2.1.0 へ更新する場合は、次の順序で進めると影響を切り分けやすくなります。

手順	作業内容	完了条件
現行バージョン確認	pip show azure-ai-projects、lockfile、コンテナイメージを確認	実行環境ごとの SDK バージョンが分かっている
利用機能の棚卸し	Agents、Hosted Agents、Evals、Tracing、Datasets などを確認	影響を受ける機能がリスト化されている
検証環境で更新	azure-ai-projects==2.1.0 を固定してテスト	主要 API の正常系・異常系が通る
トレーシング確認	Azure Monitor / OpenTelemetry の出力を確認	trace context の送信可否を判断済み
環境変数確認	新旧サンプル変数名、Secret、CI/CD を確認	実行時に未定義エラーが出ない
Hosted Agents 確認	allow_preview=True、project.beta.agents、Agent endpoint を検証	セッション操作と Agent 呼び出しが通る
本番反映	段階的にデプロイし、ログとメトリクスを確認	エラー率・レイテンシ・トレース出力に異常がない

ライブラリ更新では、コードのコンパイルや単体テストだけでは不十分です。特に AI アプリケーションでは、応答品質、ツール呼び出し、評価結果、トレース、権限、ファイル処理が絡みます。検証項目を API 単位ではなく「ユーザーが実行するタスク単位」で作ると、実運用に近い問題を見つけやすくなります。

すぐ更新すべきチーム、様子見でもよいチーム

Azure AI Projects SDK for Python 2.1.0 は、多くのチームにとって前向きな更新ですが、全員が即日更新すべきとは限りません。

チームの状況	判断
Hosted Agents の refreshed public preview へ移行している	早めに更新する価値が高い
Agent endpoint 経由の Responses API を使いたい	2.1.0 の get_openai_client(agent_name=...) を検証する
Evals を Python で継続運用している	TypedDict の恩恵があるため更新候補
Azure Monitor / OpenTelemetry を本番で使っている	更新前にトレーシング設定を必ず確認する
単純な project-scoped モデル呼び出しのみ	緊急性は低いが、依存関係更新のタイミングで検証する
preview 機能を本番に入れられない	beta 系 API は検証環境に限定する

Microsoft の Hosted Agents 移行チェックリストでも、azure-ai-projects SDK を 2.1.0 以降へ更新することが前提に含まれています。Hosted Agents を使うチームは、SDK だけでなく Agent Framework、LangGraph、protocol library、RBAC、azd 周りの変更も合わせて確認してください。(Microsoft Learn)

まとめ：最初の一歩は「Hosted Agents」と「Tracing」の影響確認

Azure AI Projects SDK for Python 2.1.0 の更新で、最初に確認すべきなのは次の2点です。

まず、Hosted Agents や Agent endpoint を使っている場合は、get_openai_client(agent_name=...)、allow_preview=True、.beta.agents の Session 操作を検証してください。Agent 呼び出し、セッション分離、ファイル操作、環境変数名の変更が実運用に影響します。

次に、トレーシングを有効にしている場合は、trace context propagation がデフォルト有効になる破壊的変更を確認してください。可観測性は向上しますが、trace ID、baggage、content recording、ログ共有の扱いはセキュリティレビューの対象になります。

今すぐ取るべき行動は、現行バージョンの確認、利用機能の棚卸し、検証環境での 2.1.0 固定テストです。Hosted Agents、Evals、Tracing を使っているチームは、単なる SDK アップデートではなく、アプリケーション構成と運用ルールの見直しとして扱うと失敗を減らせます。