Azure AI Projects Python SDK 2.1.0 is released の実務上の結論は、Hosted Agents、Agent endpoint、評価自動化、DevOpsでの運用確認をしているチームほどアップデート価値が高いという点です。単純に Foundry Project のモデルへ問い合わせるだけなら急いで全面移行する必要はありませんが、Agent をコンテナ化して運用する、セッションやファイルをSDKから管理する、評価ジョブをCIに組み込む、といった用途では実装がかなり整理されます。
2026年4月20日に公開された Azure AI Projects SDK for Python 2.1.0 では、get_openai_client(agent_name=...)、.beta.agents のセッション操作、.beta.skills、.beta.toolboxes、評価入力向けTypedDict、トレーシング関連の変更が追加されています。特に Developers、platform engineers、DevOps teams は「新機能を試す」よりも、既存コードのどこを置き換えるべきか、どこはまだプレビューとして慎重に扱うべきかを見極めることが重要です。(GitHub)
Azure AI Projects SDK for Python 2.1.0で何が変わったのか
Azure AI Projects SDK for Python は、Microsoft Foundry Project 内の Agents、評価、デプロイ、接続、データセット、インデックスなどを扱うためのPythonクライアントライブラリです。公式ドキュメントでは、このライブラリは Microsoft Foundry SDK の一部として説明されており、Python 3.9以降、Azureサブスクリプション、Foundry Project、FOUNDRY_PROJECT_ENDPOINT 形式のプロジェクトエンドポイントが前提になります。(Microsoft Learn)
今回の2.1.0は、派手な「新モデル対応」よりも、Agentを本番運用に近い形で扱うためのSDK整備が中心です。主な変更点を実装目線で整理すると、次のようになります。
| 変更点 | 実務で楽になること | 主な対象 |
|---|---|---|
get_openai_client(agent_name=...) | Agent endpoint向けのOpenAI互換クライアントを作りやすくなる | Agent実装者、API開発者 |
.beta.agents のSession操作 | Hosted Agentsのセッション作成、取得、一覧、削除、ファイル操作をSDKで扱える | Platform engineers、SRE |
.beta.skills | Skillの作成、更新、取得、削除、パッケージ操作をSDK化できる | Agent機能開発者 |
.beta.toolboxes | Tool定義をバージョン管理し、デフォルトバージョンを切り替えやすくなる | DevOps、ガバナンス担当 |
| 評価入力向けTypedDict | .evals.create() や .evals.runs.create() の入力をIDEや型チェックで検出しやすくなる | 評価基盤担当 |
| トレーシング変更 | トレース有効時のコンテキスト伝播がデフォルト有効になる | Observability担当 |
注意したいのは、.beta 配下の機能やHosted Agents関連の機能は、名前の通りプレビュー要素を含むことです。AIProjectClient のAPIリファレンスでも、.beta サブクライアントはプレビュー操作として扱われ、Hosted AgentやWorkflow Agentなどのプレビュー機能では allow_preview=True が関係します。(Microsoft Learn)
すぐ移行すべきチーム、様子を見るべきチーム
Azure AI Projects Python SDK 2.1.0は、全チームが即日で全面移行すべきリリースというより、Agent運用の深さによって優先度が変わるリリースです。
| 状況 | 移行判断 | 理由 |
|---|---|---|
| Hosted Agentsを使っている、または検証中 | 早めに検証する | 2.1.0以降がHosted Agents移行ドキュメントの前提になっているため |
| Agent endpointをOpenAI互換APIで呼びたい | 優先度高 | get_openai_client(agent_name=...) でエンドポイント切り替えが明確になる |
| セッション、セッション内ファイル、Agent endpointを自動化したい | 優先度高 | .beta.agents でSDKから管理できる範囲が増えた |
| 評価ジョブをCI/CDに組み込みたい | 優先度中〜高 | TypedDictにより入力ミスを検出しやすくなる |
| 単純なモデル呼び出しだけをしている | 優先度中 | 破壊的変更の影響確認は必要だが、新機能の恩恵は限定的 |
| 厳格な監査・プライバシー要件がある | 検証必須 | トレースコンテキスト伝播のデフォルト有効化を確認する必要がある |
MicrosoftのHosted Agents移行ガイドでは、Azure AI Projects SDK 2.1.0以降が前提として示され、プロトコルライブラリ、SDK呼び出し、ID/RBAC、Azure Developer CLI、再デプロイまで含めて更新する流れが説明されています。すでにHosted Agentsのプレビューを使っていたチームは、SDKだけを上げるのではなく、Agentのエントリポイント、agent.yaml、RBAC、CI/CDのデプロイ手順までまとめて確認した方が安全です。(Microsoft Learn)
セットアップとバージョン固定の基本
まずは検証環境で2.1.0を明示的に入れます。本番環境では、意図しないメジャーアップデートを避けるため、しばらくは上限を付けておくと運用しやすくなります。
python -m pip install --upgrade pip
pip install "azure-ai-projects==2.1.0" azure-identity openai python-dotenv
pip show azure-ai-projects継続的に2.x系の更新を取り込みたい場合は、次のように制約します。
azure-ai-projects>=2.1.0,<3
azure-identity
openai
python-dotenv環境変数は、2.1.0のサンプル更新に合わせて FOUNDRY_ プレフィックスに寄せると、公式サンプルとの差分が減ります。リリースノートでは、サンプル内の AZURE_AI_PROJECT_ENDPOINT が FOUNDRY_PROJECT_ENDPOINT、AZURE_AI_MODEL_DEPLOYMENT_NAME が FOUNDRY_MODEL_NAME、AZURE_AI_MODEL_AGENT_NAME が FOUNDRY_AGENT_NAME に変更されています。既存アプリで古い環境変数名を使い続けること自体は可能ですが、新旧が混在するとCI/CDで事故が起きやすくなります。(GitHub)
export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL_NAME="<model-deployment-name>"
export FOUNDRY_AGENT_NAME="<agent-name>"get_openai_client(agent_name=...)でAgent endpoint呼び出しが分かりやすくなる
2.1.0で最も分かりやすい改善は、AIProjectClient.get_openai_client() に agent_name を渡せるようになったことです。通常はFoundry Project endpointに /openai/v1 を付けたbase URLが使われますが、agent_name を指定するとAgent endpoint向けのbase URLが使われます。Agent endpointはプレビュー機能のため、AIProjectClient 側で allow_preview=True が必要です。(Microsoft Learn)
プロジェクト上のモデルを呼び出す場合
モデル呼び出しだけなら、従来通り get_openai_client() を使えます。
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
with (
DefaultAzureCredential() as credential,
AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
) as project_client,
):
with project_client.get_openai_client() as openai_client:
response = openai_client.responses.create(
model=os.environ["FOUNDRY_MODEL_NAME"],
input="この問い合わせを3行で要約してください。",
)
print(response.output_text)Agent endpointを呼び出す場合
Agent endpointを呼び出す場合は、allow_preview=True と agent_name を明示します。公式サンプルでも、Agent endpointに紐づくOpenAIクライアントを作成し、Responses APIを呼び出す流れが示されています。(GitHub)
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
with (
DefaultAzureCredential() as credential,
AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
allow_preview=True,
) as project_client,
):
openai_client = project_client.get_openai_client(
agent_name=os.environ["FOUNDRY_AGENT_NAME"]
)
response = openai_client.responses.create(
input="注文番号A-123の配送状況を確認してください。",
extra_body={
"agent_session_id": os.environ["FOUNDRY_AGENT_SESSION_ID"],
},
)
print(response.output_text)この変更で楽になるのは、アプリ側でAgent endpoint用のbase URLを組み立てる責任が減ることです。複数Agentを運用する場合も、agent_name を設定値として切り替えればよく、環境別の設定ファイルやCI/CDの変数管理が単純になります。
ただし、allow_preview=True を忘れると agent_name 指定時に例外が発生します。実装では、Agent endpointを使うクライアント生成箇所を1つの関数に集約し、プレビュー設定を漏らさないようにするのがおすすめです。
def create_project_client() -> AIProjectClient:
return AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
allow_preview=True,
)Hosted Agentsのセッション管理をSDKで扱える
2.1.0では、.beta.agents にHosted Agents向けのSession操作が追加されています。リリースノートでは、create_session()、delete_session()、delete_session_file()、download_session_file()、get_session()、get_session_files()、list_sessions()、upload_session_file() が追加されたと説明されています。(GitHub)
セッション操作は、長く動くAgentやユーザーごとの作業空間を扱うときに重要です。たとえば、以下のようなケースで効果があります。
- ユーザー単位でAgentの作業状態を分離する
- Agentの実行セッションに一時ファイルをアップロードする
- セッション内で生成されたファイルをダウンロードする
- テスト終了後にセッションを削除する
- CIでAgentの起動、呼び出し、削除までを自動化する
最小構成では、Agentのバージョンを指定してセッションを作成します。公式サンプルでは、Hosted Agentのバージョンを作成した後、VersionRefIndicator と isolation_key を使ってセッションを作成しています。(GitHub)
import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator
from azure.identity import DefaultAzureCredential
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
agent_version = os.environ["FOUNDRY_AGENT_VERSION"]
with (
DefaultAzureCredential() as credential,
AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
allow_preview=True,
) as project_client,
):
session = project_client.beta.agents.create_session(
agent_name=agent_name,
isolation_key="tenant-001-user-123",
version_indicator=VersionRefIndicator(agent_version=agent_version),
)
print(session.agent_session_id)isolation_key は、セッションの所有や分離に関わる値です。実務では、メールアドレスや氏名などの個人情報をそのまま入れるより、テナントID、ユーザーID、ワークスペースIDなどを組み合わせた内部ID、またはハッシュ化した値を使う方が安全です。
セッション内ファイル操作でAgentの前処理・後処理を自動化できる
.beta.agents では、セッション内のサンドボックスにファイルをアップロードしたり、生成物をダウンロードしたりできます。APIリファレンスでは、upload_session_file() はbytesまたはローカルファイルパスを受け取り、セッション内の相対パスに保存できると説明されています。また、アップロード上限は50MBで、超過すると 413 Payload Too Large になります。(Microsoft Learn)
project_client.beta.agents.upload_session_file(
agent_name=agent_name,
session_id=session.agent_session_id,
content_or_file_path="./input/customer_report.csv",
path="input/customer_report.csv",
)
for chunk in project_client.beta.agents.download_session_file(
agent_name=agent_name,
agent_session_id=session.agent_session_id,
path="output/result.json",
):
with open("./output/result.json", "ab") as f:
f.write(chunk)失敗しやすいのは、Agent呼び出しのたびにセッションを作りっぱなしにする運用です。検証では問題になりにくいものの、CIや負荷試験では不要なセッションが残りやすくなります。テストコードでは try/finally で削除処理を入れておきましょう。
session = project_client.beta.agents.create_session(
agent_name=agent_name,
isolation_key="ci-smoke-test",
version_indicator=VersionRefIndicator(agent_version=agent_version),
)
try:
# Agent呼び出しやファイル操作
pass
finally:
project_client.beta.agents.delete_session(
agent_name=agent_name,
session_id=session.agent_session_id,
isolation_key="ci-smoke-test",
)SkillsとToolboxesでAgent機能の再利用がしやすくなる
2.1.0では、.beta.skills と .beta.toolboxes も追加されています。ざっくり言えば、SkillsはAgentに与える振る舞いや専門能力の部品化、ToolboxesはAgentが使うツール定義の部品化とバージョン管理に向いています。(GitHub)
| 項目 | Skills | Toolboxes |
|---|---|---|
| 主な用途 | Agentの専門能力や指示を再利用する | Tool定義をまとめて管理する |
| 代表操作 | create、create_from_package、update、download、delete | create_version、update、list_versions、delete_version、delete |
| 向いている例 | サポート回答、社内規約案内、製品説明 | MCP tool、承認ポリシー付きツール、複数バージョンの切り替え |
| 運用上のポイント | instructionのレビューが重要 | デフォルトバージョンの切り替え確認が重要 |
Skillを作成・更新する
公式サンプルでは、project_client.beta.skills を使ってSkillを作成し、取得、更新、一覧、削除まで実行しています。(GitHub)
skills_client = project_client.beta.skills
created = skills_client.create(
name="product_support_skill",
description="製品サポート向けの回答スキル",
instructions=(
"あなたは製品サポート担当です。"
"社内ポリシーと製品ガイドに基づいて、簡潔に回答してください。"
),
metadata={
"domain": "support",
"status": "created",
},
)
updated = skills_client.update(
"product_support_skill",
description="製品サポート向けの回答スキル v2",
metadata={
"domain": "support",
"status": "updated",
},
)Skillは便利ですが、instructionsに業務ルールを詰め込みすぎると、レビューが難しくなります。実務では、Skill名、目的、対象ユーザー、禁止事項、参照すべきデータソースを明確にし、変更時はPull Requestでレビューできる形にしておくと安全です。
Toolboxをバージョン管理する
Toolboxesは、ツール定義をバージョン化して管理できる点が重要です。公式サンプルでは、MCP toolを含むToolboxを2バージョン作成し、default_version を切り替える処理が示されています。(GitHub)
from azure.ai.projects.models import MCPTool
toolbox_name = "toolbox_with_mcp_tool"
tools = [
MCPTool(
server_label="api_specs",
server_url="https://gitmcp.io/Azure/azure-rest-api-specs",
require_approval="always",
)
]
created = project_client.beta.toolboxes.create_version(
name=toolbox_name,
description="MCPツールを含むToolbox",
tools=tools,
)
project_client.beta.toolboxes.update(
toolbox_name,
default_version=created.version,
)Toolboxの運用で大切なのは、作成と切り替えを分けて考えることです。新バージョンを作るだけなら既存Agentに影響しませんが、default_version を切り替えると実行時の動作が変わる可能性があります。DevOpsでは、次の順序にすると事故を減らせます。
| 手順 | 確認内容 |
|---|---|
| 新しいToolbox versionを作成 | ツールURL、承認設定、metadataを確認 |
| 検証Agentで動作確認 | Agentが想定通りツールを呼ぶか確認 |
default_version を更新 | 本番Agentに影響する範囲を確認 |
| スモークテストを実行 | 代表的な問い合わせ、失敗系、権限エラーを確認 |
| 古いバージョンを整理 | すぐ削除せず、ロールバック可能な期間を残す |
評価自動化ではTypedDictの追加が効く
2.1.0では、get_openai_client() で取得したOpenAIクライアントの .evals.create() と .evals.runs.create() に対する型ヒントが強化されました。リリースノートでは、ModelSamplingConfigParam、AzureAIAgentTargetParam、AzureAIModelTargetParam、EvalCsvFileIdSource、EvalCsvRunDataSource、TracesPreviewEvalRunDataSource などのTypedDictクラスが追加されたと説明されています。(GitHub)
この改善は、評価ジョブを手作業で1回実行するチームよりも、CI/CDや定期ジョブで評価を回すチームに向いています。評価入力はネストした辞書になりやすく、キー名のtypoや型のズレが実行時まで見つからないことがあります。TypedDictを使うと、IDE、mypy、pyrightなどで早めに検出しやすくなります。
たとえば、サンプリング設定やCSVファイルIDの入力は、次のように型を付けて管理できます。
from azure.ai.projects.models import (
EvalCsvFileIdSource,
ModelSamplingConfigParam,
)
sampling: ModelSamplingConfigParam = {
"max_completion_tokens": 800,
"temperature": 0.0,
"top_p": 1.0,
"seed": 42,
}
csv_source: EvalCsvFileIdSource = {
"type": "file_id",
"id": uploaded_csv_file_id,
}ModelSamplingConfigParam には max_completion_tokens、seed、temperature、top_p などの属性があり、EvalCsvFileIdSource はアップロード済みCSVファイルIDを表す id と type を持ちます。(Microsoft Learn)
実務では、評価入力を関数の中で直接組み立てるより、build_eval_config.py のような専用モジュールに分ける方が保守しやすくなります。CIでは、最低限以下をチェックすると効果的です。
python -m pip install mypy
mypy src/evaluations
python scripts/run_eval_smoke.pyトレーシングは「便利になったが、確認なしで有効化しない」
2.1.0のBreaking Changesとして、トレーシングが有効な場合にtrace context propagationがデフォルト有効になります。READMEでは、get_openai_client() で取得したOpenAIクライアント経由のHTTPリクエストに、W3C Trace Contextの traceparent と tracestate が注入され、クライアント側とサーバー側のスパンを同じ分散トレースに関連付けやすくなると説明されています。(GitHub)
これはObservabilityの観点では大きな改善です。Agentの遅延、ツール呼び出し、モデル呼び出し、評価結果をつなげて追いやすくなります。一方で、監査やプライバシー要件が厳しい環境では、トレースIDやbaggageの扱いを確認する必要があります。READMEでも、baggageにはユーザー識別子、セッション情報、認証情報、業務データ、個人情報が含まれる可能性があるため、baggage propagationはデフォルト無効で、必要な場合のみ有効化する設計だと説明されています。(GitHub)
トレースコンテキスト伝播を無効化したい場合は、環境変数またはinstrument時の引数で制御します。
export AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION=falseAIProjectInstrumentor().instrument(
enable_trace_context_propagation=False
)運用で特に注意したいのは、設定変更のタイミングです。READMEでは、trace context propagationの設定変更は、変更後に get_openai_client() で取得したOpenAIクライアントに反映され、既に取得済みのクライアントには影響しないと説明されています。つまり、設定変更後はクライアントを作り直す必要があります。(GitHub)
移行時に失敗しやすいポイント
Azure AI Projects SDK for Python 2.1.0への移行では、コードそのものよりも、環境変数、プレビュー設定、トレーシング、Agent種別の取り違えでつまずきやすくなります。
| 失敗しやすいポイント | 起きる問題 | 対策 |
|---|---|---|
allow_preview=True を忘れる | agent_name 指定時に例外が出る | Agent endpoint用クライアント生成を共通化する |
| 古い環境変数名と新しいサンプル名が混在 | CI/CDで KeyError や設定漏れが起きる | FOUNDRY_ 系へ寄せる、または互換マッピングを作る |
| Hosted Agents以外でSession APIを使う | セッション操作が期待通り動かない | SessionはHosted Agents向けと理解する |
| セッションを削除しない | 検証環境やCIで不要なリソースが残る | try/finally で削除する |
| Toolboxの新バージョン作成と切り替えを同時に行う | 本番Agentの動作が急に変わる | 作成、検証、default切り替えを分ける |
| トレース設定を確認しない | 監査上共有したくない情報が伝播する可能性 | propagation、baggage、content recordingを明示的に管理する |
| セッションファイルに大容量データを直接置く | 50MB超過で失敗する | 外部ストレージや分割アップロードを検討する |
DevOpsでの移行チェックリスト
開発者個人のローカル検証で終わらせず、DevOpsチームは次の順序で移行すると安全です。
| フェーズ | やること | 完了条件 |
|---|---|---|
| 依存関係確認 | azure-ai-projects を2.1.0に固定 | pip show azure-ai-projects で2.1.0を確認 |
| 環境変数整理 | FOUNDRY_PROJECT_ENDPOINT などに統一 | ローカル、CI、シークレットストアで同じ名前を使う |
| Client生成確認 | allow_preview=True が必要な箇所を特定 | Agent endpoint呼び出しで例外が出ない |
| Agent endpoint確認 | get_openai_client(agent_name=...) に置き換え | 手動base URL組み立てが残っていない |
| Session操作確認 | 作成、取得、一覧、削除をテスト | テスト後にセッションが残らない |
| Skills/Toolboxes確認 | 作成と更新を検証環境で実行 | バージョン切り替え前後の動作を確認 |
| 評価確認 | TypedDictで評価入力を整理 | 型チェックとスモーク評価が通る |
| トレース確認 | propagation設定を確認 | 監査・プライバシー方針と一致している |
CIのスモークテストでは、すべてのAgent機能を網羅する必要はありません。最初は、SDK認証、プロジェクト接続、Agent endpoint呼び出し、セッション作成・削除だけを確認する軽いテストを用意すると、アップデート時の異常を早く検出できます。
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
def main() -> None:
with (
DefaultAzureCredential() as credential,
AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
allow_preview=True,
) as project_client,
):
# プロジェクト接続の疎通確認
deployments = list(project_client.deployments.list())
print(f"deployments: {len(deployments)}")
# Agent endpointの疎通確認
openai_client = project_client.get_openai_client(
agent_name=os.environ["FOUNDRY_AGENT_NAME"]
)
response = openai_client.responses.create(
input="health check",
extra_body={
"agent_session_id": os.environ["FOUNDRY_AGENT_SESSION_ID"],
},
)
print(response.output_text[:100])
if __name__ == "__main__":
main()このテストは本番ワークロードの品質を保証するものではありませんが、認証、エンドポイント、SDKバージョン、Agent endpointの基本的な破損を検出するには役立ちます。
2.1.0で開発・移行・自動化はどこが楽になるのか
Azure AI Projects Python SDK 2.1.0の価値は、個別のAPI追加よりも、Agent運用の境界がはっきりした点にあります。
開発者にとっては、get_openai_client(agent_name=...) によって、Foundry Project endpointとAgent endpointの使い分けがコード上で明確になります。Platform engineersにとっては、Hosted Agentsのセッションやファイル操作をSDKで扱えるため、検証・削除・障害調査の自動化がしやすくなります。DevOps teamsにとっては、SkillsやToolboxesをコードで作成・更新し、評価入力をTypedDictで管理し、トレーシング設定を明示できる点が大きな改善です。
一方で、プレビュー機能を含むため、いきなり本番コードへ広範囲に入れるのは避けた方が安全です。まずは検証環境で2.1.0に固定し、Agent endpoint、Session、Toolbox、評価、トレーシングの順にスモークテストを作成してください。既存コードを一気に書き換えるのではなく、クライアント生成、環境変数、Agent呼び出し、セッション管理、評価入力の5つに分けて移行すると、影響範囲を抑えながら2.1.0の恩恵を取り込めます。
コメント