MENU

Azure AI Projects SDK for Python 2.1.0の変更点と移行判断｜Agent/App Builder向け最新動向

Azure

Azure AI Projects SDK for Pythonを使ってエージェントや生成AIアプリを作っているなら、2.1.0は「とりあえず更新して終わり」のリリースではありません。2026年4月20日に公開された2.1.0では、Hosted Agents向けのSession操作、Skills、Toolboxes、get_openai_client()のAgent endpoint対応、評価機能まわりの型ヒント強化、Tracingの挙動変更が入っています。結論から言うと、新規開発は2.1.0前提で検証し、既存プロダクションはTracingとプレビュー機能の利用有無を確認してから段階的に上げるのが安全です。(PyPI)

目次

Azure AI Projects SDK for Python 2.1.0は何を示しているのか

Azure AI Projects SDK for Python 2.1.0の重要点は、単なる機能追加ではなく、Microsoftがエージェント開発・AIアプリ開発の「作る、動かす、評価する、観測する」面をかなり速いテンポで整えていることです。

特に今回のリリースでは、モデル呼び出しそのものよりも、実務で必要になる周辺領域が強化されています。

領域2.1.0で注目すべき変更開発現場への影響
Agent endpointget_openai_client(agent_name=...)に対応Foundry Project単位だけでなく、Agent endpointを意識した実装・検証がしやすくなる
Hosted Agents.beta.agentsにSession操作を追加セッション作成、ファイルアップロード、ダウンロードなどをSDKから扱いやすくなる
Skillsbeta.skillsサブクライアントを追加エージェントに持たせる機能単位をSDKで管理しやすくなる
Toolboxesbeta.toolboxesサブクライアントを追加ツール群やバージョン管理をアプリ開発の流れに組み込みやすくなる
Evaluation.evals.create()などの型ヒントを強化評価用ペイロードの記述ミスを開発時に検出しやすくなる
Tracingtracing有効時のtrace context propagationがデフォルト有効に観測性は上がるが、セキュリティ・プライバシー確認が必要になる

Azure AI Projects SDK for Pythonは、Microsoft Foundry Project内のリソースへアクセスするためのクライアントライブラリです。公式ドキュメントでは、Agentsの作成・実行、各種ツール連携、OpenAI互換クライアントの取得、評価、Red Team、デプロイ、接続、データセット、インデックスなどを扱う用途が示されています。(Microsoft Learn)

なぜ2.1.0は開発者が追うべきリリースなのか

SDKのバージョンアップは、開発者にとって「新機能が増えたか」だけでなく、次の3点を確認するタイミングです。

まず、互換性です。既存コードがそのまま動くか、環境変数名やプレビュー機能の有効化条件が変わっていないかを確認する必要があります。

次に、開発体験です。2.1.0では評価APIまわりのTypedDictが増え、get_openai_client()で返されるOpenAI clientの型ヒント不足も修正されています。AIアプリ開発ではJSON風の深い設定を扱うことが多いため、型補完や静的解析の効き方は実装速度に直結します。(PyPI)

最後に、運用影響です。Tracingのtrace context propagationが、tracing有効時にデフォルトで有効になります。分散トレースの相関は取りやすくなりますが、外部サービスへ送られるヘッダーや、baggage、メッセージ内容の記録設定は慎重に扱う必要があります。(Microsoft Learn)

リリース履歴から見るMicrosoftの反復速度

Azure AI Projects SDK for Pythonは、2026年3月6日に2.0.0が公開され、Foundry REST APIのGA版であるv1を使う最初の安定版リリースとして位置付けられました。その後、3月12日に2.0.1、4月20日に2.1.0が公開されています。PyPIのリリース履歴でも、2.0.0、2.0.1、2.1.0が短期間に並んでいます。(PyPI)

バージョン公開日意味合い
2.0.02026年3月6日Foundry REST API v1を使う最初の安定版リリース
2.0.12026年3月12日Memory Storesまわりの不具合修正
2.1.02026年4月20日Agent、Skills、Toolboxes、Evaluation、Tracingを広く強化

この流れを見ると、MicrosoftはAzure AI Projects SDK for Pythonを、単なる「AIモデル呼び出し用SDK」ではなく、エージェント／AIアプリの開発ライフサイクルを支える面として育てていると考えられます。モデルを呼ぶだけならOpenAI互換クライアントで足りますが、実務ではプロジェクト、接続、データセット、評価、トレース、ツール、Agentの状態管理まで必要になります。2.1.0は、その領域が急速に広がっていることを示すリリースです。

2.1.0の主要変更点を実務目線で整理

get_openai_client()がAgent endpointを扱いやすくなった

2.1.0では、AIProjectClientのget_openai_client()に任意引数agent_nameが追加されました。agent_nameを指定すると、返されるOpenAI clientはFoundry Project endpointではなくAgent endpointのbase URLを使います。Agent endpointはプレビュー機能のため、この使い方ではAIProjectClient作成時にallow_preview=Trueが必要です。(PyPI)

これは、エージェントを中心にアプリを組むチームにとって重要です。従来の「プロジェクト内のモデルに問い合わせる」実装から、「特定のAgent endpointをアプリの実行単位として扱う」実装へ移りやすくなるためです。

基本形は次のように考えます。

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,
):
    with project_client.get_openai_client(
        agent_name=os.environ["FOUNDRY_AGENT_NAME"]
    ) as openai_client:
        # responses、conversations、evalsなど、
        # 利用する操作に応じて公式サンプルと同じ形で呼び出す
        pass

ここで注意したいのは、allow_preview=Trueを安易に全環境へ入れないことです。検証環境では有効にしても、プロダクションでは「どのプレビュー機能を、どの責任範囲で使っているか」をチーム内で明示しておくべきです。

.beta.agentsにSession操作が追加された

2.1.0では、.beta.agentsサブクライアントにHosted Agents向けのSession操作が追加されました。主な操作には、Sessionの作成・削除・取得・一覧、Session fileのアップロード・ダウンロード・削除・一覧があります。これらはHosted Agentsで動作する操作としてリリースノートに記載されています。(PyPI)

これにより、次のような実装シナリオが組みやすくなります。

シナリオ使いどころ
ユーザーごとの会話セッション管理サポートボット、業務アシスタント、社内FAQエージェント
セッション単位のファイル受け渡し契約書レビュー、帳票確認、ログ解析、ドキュメント検索
検証用セッションの作成・削除QA、評価、デモ環境、PoCの自動化

特にAIアプリでは、単発のチャットだけでなく、ユーザーの操作履歴やアップロードファイルを含めた「作業単位」を管理する必要があります。Session操作の追加は、SDKがアプリケーション実装に近づいているサインです。

beta.skillsでエージェント機能の部品化が進む

新しく追加されたbeta.skillsでは、Skillの作成、パッケージからの作成、削除、ダウンロード、取得、一覧、更新が扱えます。(PyPI)

Skillsは、エージェントに持たせる能力を部品として扱う発想に近いものです。たとえば、社内申請を支援するエージェントであれば、次のような切り分けが考えられます。

Skillの例役割
申請ルール確認入力内容が社内規定に合っているか確認する
添付資料チェック必要書類がそろっているか確認する
承認者候補の提示部門や金額に応じて承認者を推定する
申請文面の整形ユーザー入力を正式な申請文に整える

実務では、ひとつの巨大なエージェントにすべてを詰め込むより、機能を小さく分けてテストし、再利用できる形にした方が保守しやすくなります。beta.skillsの追加は、そうした設計にSDK側が寄ってきていると見てよいでしょう。

beta.toolboxesでツール群の管理がしやすくなる

2.1.0ではbeta.toolboxesも追加されました。操作には、Toolboxの作成・取得・一覧・更新・削除に加えて、versionの作成・取得・一覧・削除が含まれます。(PyPI)

AIエージェント開発では、ツール連携が増えるほど「どのツールを、どのバージョンで、どのAgentに使わせるのか」が問題になります。たとえば、検索、コード実行、ファイル検索、社内API、OpenAPI連携などを組み合わせる場合、ツール構成を手作業で管理すると再現性が落ちます。

ToolboxesがSDKから扱えるようになると、CI/CDや検証環境で次のような管理がしやすくなります。

管理したいこと実務上のメリット
ツール構成のバージョン化本番と検証で同じ構成を再現しやすい
不要なToolboxの削除PoC後のリソース散乱を防げる
一覧取得運用中のAgentが依存するツール群を棚卸ししやすい
更新ツール追加や設定変更をコード化しやすい

ただし、beta配下の機能はプレビュー扱いです。新機能を先行して使える一方、仕様や命名、サポート範囲が変わる可能性があります。プロダクション投入前に、依存する操作と代替手段を整理しておくことが重要です。

Evaluationの型ヒント強化は地味だが重要

2.1.0では、AIProjectClient.get_openai_client()で取得したOpenAI clientの.evals.create()と.evals.runs.create()に対して、型ヒントのサポートが追加されました。リリースノートでは、評価設定やデータソース、Azure AI向けターゲット、Red Team、Trace、CSV関連などのTypedDictが追加されたことが示されています。(PyPI)

これは、AIアプリチームにとってかなり実用的です。評価処理は、モデル名、対象Agent、評価基準、データソース、CSV、合成データ、Red Teamなどの設定が増えやすく、ペイロードの形も複雑になりがちです。

型ヒントが効くと、次のようなミスを早い段階で見つけやすくなります。

よくあるミス型ヒントで改善しやすい点
キー名のタイプミスエディタ補完で候補を確認しやすい
必須項目の抜け静的解析や補完で気づきやすい
データソース種別の混同TypedDictの名前から用途を推測しやすい
評価ターゲットの指定ミスAgent向け、Model向けなどの違いを整理しやすい

AIアプリの品質管理では、評価を「最後に人間が見るもの」にしないことが重要です。SDK側の型が整うほど、評価設定をコードレビューしやすくなり、CIに組み込むハードルも下がります。

Tracingの変更は必ず確認する

2.1.0のBreaking Changesとして、tracing有効時にtrace context propagationがデフォルトで有効になる変更があります。公式ドキュメントでは、OpenAI clientがget_openai_client()から取得された場合に、traceparentやtracestateなどのW3C Trace ContextヘッダーをHTTPリクエストへ挿入し、クライアント側のspanとサーバー側のspanを関連付ける説明がされています。(PyPI)

これは観測性の観点では便利です。Azure Monitorなどで、ユーザー操作、Agent呼び出し、Azure OpenAIや関連サービスの処理を横断して見やすくなります。

一方で、セキュリティ・プライバシーの観点では確認が必要です。ドキュメントでは、trace identifierがサービス側に共有される可能性や、baggage headerにユーザー識別子、セッション情報、認証情報、業務データ、個人情報が含まれ得る点が説明されています。baggage propagationはデフォルトでは無効ですが、必要に応じて明示的に制御する必要があります。(Microsoft Learn)

Tracingを使っている場合は、アップグレード前に次を確認してください。

確認項目判断基準
tracingを有効化しているかAZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=trueやOpenTelemetry設定の有無を確認
trace context propagationを許容できるか社内の監査・コンプライアンス要件で外部送信ヘッダーを確認
baggageを使っているか個人情報や認証情報がbaggageに混入していないか確認
content recordingを使っているかメッセージ内容やツール呼び出し詳細が記録される範囲を確認
binary data tracingを使うかファイルや画像の内容がトレースに含まれるリスクを確認

trace context propagationを無効にしたい場合は、環境変数AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION=falseを使うか、AIProjectInstrumentor().instrument()にenable_trace_context_propagation=Falseを渡す方法がドキュメントで示されています。(Microsoft Learn)

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

2.1.0では、サンプル内の環境変数名が次のように変更されています。(PyPI)

旧サンプル名新サンプル名
AZURE_AI_PROJECT_ENDPOINTFOUNDRY_PROJECT_ENDPOINT
AZURE_AI_MODEL_DEPLOYMENT_NAMEFOUNDRY_MODEL_NAME
AZURE_AI_MODEL_AGENT_NAMEFOUNDRY_AGENT_NAME

これはサンプル更新の一部であり、既存アプリが独自に使っている環境変数名まで強制的に変わるわけではありません。ただし、公式サンプルをコピーして検証しているチームでは、.env、GitHub Actions、Azure Pipelines、Docker Compose、Kubernetes Secretなどの名前が食い違い、起動時にKeyErrorや未設定エラーが起きる可能性があります。

移行時は、コードだけでなく設定ファイルも検索してください。

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

見つかった場合は、プロジェクト方針に合わせてリネームするか、互換用に両方を読む実装にします。長期的には、公式サンプルに合わせてFOUNDRY_*へ寄せた方が、今後のサンプル追従は楽になります。

アップグレード前に確認すべき環境

Azure AI Projects SDK for Python 2.1.0を使うには、Python 3.9以上が前提です。PyPIのメタ情報でもPython >=3.9が示されており、公式ドキュメントの前提条件にもPython 3.9以降が含まれています。(PyPI)

インストールとバージョン確認は次のコマンドで行えます。

pip install --upgrade azure-ai-projects==2.1.0
pip show azure-ai-projects

新規プロジェクトなら、requirements.txtやpyproject.tomlで明示的にバージョンを固定しておくと、チームメンバーやCI環境で再現しやすくなります。

azure-ai-projects==2.1.0

既存プロジェクトでは、いきなり本番環境でpip install -U azure-ai-projectsを実行するのは避けてください。Azure SDK系は依存パッケージも含めて更新される可能性があるため、ロックファイルやconstraintsファイルを使い、ステージング環境で確認してから反映するのが安全です。

2.1.0へ移行する手順

現在のバージョンと依存関係を確認する

まず、現在のSDKバージョンを確認します。

pip show azure-ai-projects
pip freeze | grep -E "azure-ai-projects|azure-core|azure-identity|openai"

Azure AI Projects SDK for Pythonは、OpenAI互換クライアント、Azure Identity、Azure Coreなどと組み合わせて使うことが多いため、単体のバージョンだけを見ても十分ではありません。特にget_openai_client()や評価機能を使っている場合は、OpenAIパッケージ側の挙動も確認してください。

ステージング環境で2.1.0に固定する

次に、ステージング環境で2.1.0へ上げます。

pip install --upgrade azure-ai-projects==2.1.0

この時点で、最低限次のスモークテストを実行します。

テスト目的
AIProjectClientを作成できるかendpoint、credential、ロール設定の確認
get_openai_client()を取得できるかOpenAI互換クライアントの認証・base URL確認
既存のResponsesやConversationsが動くかアプリの中核処理が壊れていないか確認
Agent関連処理が動くかallow_previewやAgent名の設定確認
Evaluation処理が動くか型ヒント変更後のペイロード確認
Tracingが想定通りかtrace context propagationの挙動確認

Tracing設定をレビューする

Tracingを使っているチームは、アップグレード作業の中で必ず設定をレビューしてください。

echo $AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING
echo $AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION
echo $AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE
echo $OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT

特に、金融、医療、公共、個人情報を扱う業務システムでは、トレースに含まれるヘッダーやメッセージ内容をレビュー対象に含めるべきです。便利だから有効にするのではなく、「どの情報を、どのバックエンドに、どの保持期間で送るのか」を明確にしてください。

サンプル追従と実装差分を分けて管理する

2.1.0では、Hosted Agents、Sessions、Skills、Toolboxes、構造化入力、File Search、Code Interpreter、CSV評価、合成データ評価、Chat Completions basicなどのサンプルが追加されています。(PyPI)

サンプルを読むときは、次の2つを分けて考えると失敗しにくくなります。

観点見るべき内容
SDKの新しい呼び出し方サブクライアント名、メソッド名、引数、環境変数
自社アプリへの適用認証、例外処理、ログ、権限、CI/CD、データ保持

サンプルは動作確認には有用ですが、そのまま本番実装に貼り付けるものではありません。特にプレビュー機能、ファイル操作、トレース、評価データは、自社のセキュリティ基準に合わせて調整してください。

すぐアップグレードすべきチーム、慎重に進めるべきチーム

2.1.0は魅力的な更新ですが、全チームが同じ速度で本番投入すべきとは限りません。

チームの状況推奨アクション
新規にAzure AI Projects SDK for Pythonで開発する2.1.0を前提に設計・検証する
Hosted Agentsを検証している2.1.0へ上げ、Session、Skills、Toolboxesのサンプルを確認する
Evaluationをコード化している型ヒント強化の恩恵が大きいため、早めに検証する
Tracingを有効化しているアップグレード前にtrace propagationとbaggage設定を確認する
2.0.xで本番安定稼働しているステージング検証後に段階的に移行する
1.xや2.0.0b系から移行する2.0.0時点の破壊的変更も含めて確認する
プレビュー機能を本番禁止にしている.beta配下とallow_preview=Trueの使用箇所を制限する

特に1.xやベータ版から移行する場合、2.1.0だけを見て判断すると危険です。2.0.0では、allow_previewの導入、クラス名・メソッド名の変更、.betaサブクライアントへの移動など、多くの破壊的変更が入っています。移行計画では2.0.0の変更点も合わせて確認してください。(PyPI)

よくある失敗と回避策

Azure AI Projects SDKを「モデル呼び出し用SDK」だけだと思い込む

Azure AI Projects SDK for Pythonは、モデルを呼び出すだけのライブラリではありません。Foundry Project内のAgents、Deployments、Connections、Datasets、Indexes、Evaluations、Tracingなど、AIアプリ開発に必要な周辺リソースも扱います。公式ドキュメントでも、Agents、ツール連携、評価、Red Team、Fine-tuning、Deployments、Connections、Datasets、Indexesなどの用途が示されています。(Microsoft Learn)

モデル呼び出しだけを見ていると、2.1.0の価値を見落とします。今回の更新は、Agentをアプリとして運用するための面が広がっている点に注目すべきです。

.betaを「すぐ本番で使える安定機能」と扱う

.betaサブクライアントは、名前の通りプレビュー機能を扱う領域です。公式APIリファレンスでは、.beta配下のメソッドはプレビューであり、.betaという名前によりプレビュー利用が示されるため、メソッド利用自体にallow_preview=Trueが不要なケースが説明されています。一方、Hosted AgentやWorkflow Agent作成などではallow_preview=Trueが必要になるケースもあります。(Microsoft Learn)

つまり、allow_preview=Trueが不要だから安定版、という意味ではありません。設計レビューでは「.betaを使っているか」をチェック項目に入れてください。

サンプルの環境変数変更を見落とす

公式サンプルに追従している場合、FOUNDRY_PROJECT_ENDPOINT、FOUNDRY_MODEL_NAME、FOUNDRY_AGENT_NAMEへの変更を見落とすと、検証環境だけ動かない、CIだけ落ちる、といった問題が起きます。

環境変数の移行は、コード検索だけでなく、次の場所も確認してください。

確認場所例
ローカル設定.env、direnv、シェルプロファイル
CI/CDGitHub Actions Secrets、Azure Pipelines variables
コンテナDockerfile、docker-compose.yml
クラウド設定App Service設定、Container Apps、Kubernetes Secret
ドキュメントREADME、オンボーディング手順、社内Wiki

tracingの便利さだけを見て有効化する

Tracingは障害調査や性能分析に有効ですが、AIアプリではユーザー入力、ファイル名、ツール呼び出し、業務データがトレースに混ざりやすくなります。特にcontent recordingやbinary data tracingは、情報量が増える分だけリスクも増えます。公式ドキュメントでも、メッセージ内容やバイナリデータの記録には機微情報やトレースサイズの注意が示されています。(Microsoft Learn)

本番で有効化する前に、最低限次を決めてください。

決めること例
何を記録するかtrace IDのみ、メッセージ内容なし
どこへ送るかAzure Monitor、OTLP対応バックエンド
誰が見られるかSRE、開発リード、セキュリティ担当のみ
いつ削除するか監査要件に沿った保持期間
何を記録しないか個人情報、認証情報、添付ファイル本文

開発チームが次に取るべき行動

Azure AI Projects SDK for Python 2.1.0は、AgentとAIアプリを作るチームにとって、かなり実務寄りの更新です。Hosted AgentsのSession操作、Skills、Toolboxes、評価の型ヒント、Tracingの相関強化を見ると、Microsoftが「モデルを呼ぶSDK」から「AIアプリを継続的に開発・評価・運用するSDK」へ面を広げていることが分かります。

次にやるべきことはシンプルです。まず、現在のazure-ai-projectsのバージョンを確認します。次に、2.1.0をステージング環境へ入れ、get_openai_client()、Agent、Evaluation、Tracingの既存処理をテストします。Tracingを使っている場合は、trace context propagation、baggage、content recordingの扱いを必ずレビューしてください。最後に、公式サンプルの環境変数名変更に合わせて、.env、CI/CD、運用ドキュメントを更新します。

新規開発なら、2.1.0を起点に設計して問題ありません。既存プロダクションなら、プレビュー機能とTracing設定を切り分けて、段階的に移行するのが最も安全です。

Azure
Azure AI Foundry AIエージェント Azure AI Python SDK

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次