Azure AI Projects SDK for Pythonを管理している場合、2.1.0で最初に確認すべきことは「新機能を使うか」ではなく、設定差分・トレーシングの既定動作・環境変数名・preview機能の利用範囲です。2026年4月20日に公開されたAzure AI Projects Python SDK 2.1.0では、Hosted Agents関連の操作、get_openai_client(agent_name=...)、Skills、Toolboxes、評価処理の型ヒント強化などが追加されました。一方で、トレーシングを有効にしている環境では、trace context propagationが既定で有効になる点が管理上の重要ポイントです。(GitHub)
この記事では、IT管理者、運用責任者、展開計画担当者向けに、Azure AI Projects SDK for Python 2.1.0を導入・検証・周知するための実用チェックリストをまとめます。すぐに本番へ反映するのではなく、まず依存関係、環境変数、監査ログ、プレビュー機能、ロール割り当て、ロールバック方法を確認してから段階的に展開しましょう。
Azure AI Projects SDK for Python 2.1.0で管理者が最初に見るべき変更点
Azure AI Projects SDK for Pythonは、Microsoft Foundry Project内のAgents、接続、デプロイ、データセット、インデックス、評価などへアクセスするためのPythonクライアントライブラリです。Microsoft Learnのドキュメントでは、2.1.0時点のライブラリがMicrosoft Foundry SDKの一部として説明され、Foundry Project endpoint、Python 3.9以降、Azureサブスクリプション、Foundryプロジェクトなどが前提として示されています。(Microsoft Learn)
2.1.0の変更は、開発者だけでなく管理者にも影響します。特に次の4点は、発表直後に確認してください。
| 確認項目 | 管理者への影響 | 優先度 |
|---|---|---|
get_openai_client()にagent_name引数が追加 | Agent endpointを使う構成ではallow_preview=Trueの扱いを確認する必要がある | 高 |
.beta.agents、beta.skills、beta.toolboxesの追加 | Hosted Agents、Skills、Toolboxesを使うチームの権限・利用範囲・運用ルールが必要 | 高 |
| トレーシングのtrace context propagationが既定で有効 | 監査、プライバシー、外部連携ログの扱いを見直す必要がある | 高 |
| サンプルの環境変数名変更 | CI/CD、手順書、オンボーディング資料の変数名が古いままだと失敗しやすい | 中 |
2.1.0は単なる機能追加版として扱わない方が安全です。特にトレーシングを有効化している環境では、既定動作の変更が監査・ログ設計に影響します。
導入判断チェックリスト：今すぐ上げるべき環境と待つべき環境
Azure AI Projects SDK for Python 2.1.0への更新は、全環境へ一括展開するよりも、利用機能ごとに判断するのが現実的です。
2.1.0への検証を優先すべき環境
次のいずれかに該当する場合は、開発環境またはステージング環境で2.1.0の検証を優先しましょう。
- Hosted AgentsのSession操作を使う予定がある
get_openai_client(agent_name=...)でAgent endpointを使いたい- SkillsまたはToolboxesのCRUD操作を検証したい
.evals.create()や.evals.runs.create()で型ヒントを活用したい- 公式サンプルをベースに新規実装を進めている
- グローバルチームに新しい開発手順を周知する必要がある
2.1.0では.beta.agentsにSession操作が追加されましたが、リリースノートではこれらがHosted Agentsで動作する操作として説明されています。Hosted Agentsを使わない組織では、導入メリットよりも設定確認の負荷が先に立つ可能性があります。(PyPI)
更新を急がず、検証計画を先に作るべき環境
次の条件に当てはまる場合は、すぐに本番反映せず、検証計画を作ってから進めてください。
| 状況 | 推奨対応 |
|---|---|
| 本番でトレーシングを有効にしている | trace context propagationの影響を確認してから展開 |
| 金融、医療、公共系などログ管理が厳しい | trace ID、baggage、メッセージ内容の記録設定をセキュリティ担当と確認 |
依存関係をlatestで入れている | 先にazure-ai-projects==2.1.0のようにバージョン固定へ変更 |
| preview機能の利用ルールがない | allow_preview=Trueを誰が、どの環境で使えるか決める |
| サンプルコードを社内テンプレート化している | 環境変数名の変更を先に反映 |
「新しいから入れる」ではなく、「どの変更が自社の運用に影響するか」を先に棚卸しすることが重要です。
依存関係とバージョン固定のチェックリスト
SDK更新で最も多い失敗は、アプリごとに異なるバージョンが混在し、開発環境では動くのにCIや本番で動かないケースです。管理者は、まず依存関係の固定方法を確認します。
現在の導入状況を確認する
各アプリケーション、コンテナイメージ、CIジョブで次のコマンドを実行し、導入済みバージョンを確認します。
python -m pip show azure-ai-projects
python -m pip freeze | grep azure-ai-projectsMicrosoft Learnでは、pip install azure-ai-projectsでインストールし、pip show azure-ai-projectsでバージョン確認する手順が示されています。PyPI上では2.1.0が2026年4月20日に公開され、Python 3.9以降が要件として表示されています。(Microsoft Learn)
本番向けはバージョンを固定する
本番・ステージングでは、次のように明示的にバージョンを固定します。
azure-ai-projects==2.1.0requirements.txt、pyproject.toml、Dockerfile、GitHub Actions、Azure DevOps Pipelinesなど、依存関係を記述している場所を横断的に確認してください。
python -m pip install --upgrade "azure-ai-projects==2.1.0"
python -m pip show azure-ai-projects管理者向けの判断基準はシンプルです。検証環境では2.1.0へ上げて差分を確認し、本番環境ではテスト完了まで2.0.1など既存の承認済みバージョンを維持します。latest相当の指定は、再現性が落ちるため避けましょう。
設定差分チェックリスト：環境変数名の変更を必ず周知する
2.1.0のサンプル更新では、環境変数名がFoundry寄りの名称へ変更されています。これは「サンプルだけの変更」と見落とされがちですが、社内テンプレート、README、CI/CD、Secret管理に影響します。リリースノートでは、AZURE_AI_PROJECT_ENDPOINTがFOUNDRY_PROJECT_ENDPOINTへ、AZURE_AI_MODEL_DEPLOYMENT_NAMEがFOUNDRY_MODEL_NAMEへ、AZURE_AI_MODEL_AGENT_NAMEがFOUNDRY_AGENT_NAMEへ変更されたことが示されています。(PyPI)
| 旧名称 | 新名称 | 確認する場所 |
|---|---|---|
AZURE_AI_PROJECT_ENDPOINT | FOUNDRY_PROJECT_ENDPOINT | .env、Key Vault、CI/CD変数、Docker Compose、Kubernetes Secret |
AZURE_AI_MODEL_DEPLOYMENT_NAME | FOUNDRY_MODEL_NAME | アプリ設定、ジョブ定義、テストコード |
AZURE_AI_MODEL_AGENT_NAME | FOUNDRY_AGENT_NAME | Agent実行スクリプト、サンプル派生コード、運用手順書 |
ただし、既存アプリが旧変数名で独自に動いている場合、SDK自体が自動的に新変数名を要求するとは限りません。問題は「公式サンプルや新規コードが新名称を前提にする」ことです。移行期は、次のようにラッパー側で互換性を持たせると安全です。
import os
project_endpoint = (
os.getenv("FOUNDRY_PROJECT_ENDPOINT")
or os.getenv("AZURE_AI_PROJECT_ENDPOINT")
)
model_name = (
os.getenv("FOUNDRY_MODEL_NAME")
or os.getenv("AZURE_AI_MODEL_DEPLOYMENT_NAME")
)
agent_name = (
os.getenv("FOUNDRY_AGENT_NAME")
or os.getenv("AZURE_AI_MODEL_AGENT_NAME")
)
if not project_endpoint:
raise RuntimeError("FOUNDRY_PROJECT_ENDPOINT is required.")この互換コードは恒久対応ではなく、移行期間中の安全策です。周知後は新名称へ統一し、旧名称は削除予定日を決めて運用しましょう。
allow_preview=Trueの利用範囲を決める
2.1.0では、AIProjectClient.get_openai_client()に任意のagent_name引数が追加されました。リリースノートでは、agent_nameを指定した場合、返されるOpenAIクライアントがFoundry Project endpointではなくAgent endpointのbase URLを使うと説明されています。またAgent endpointsはpreview機能のため、AIProjectClientのコンストラクタでallow_preview=Trueを設定する必要があります。(PyPI)
管理者は、allow_preview=Trueを「開発者が自由に使える便利設定」にしないことが重要です。preview機能は仕様や動作が変わる可能性があり、サポート範囲や本番適用の判断が必要です。
preview機能の利用ルール例
| 項目 | 推奨ルール |
|---|---|
| 利用可能環境 | まず開発・検証環境のみ。本番は承認制 |
| 利用者 | Agent運用担当、AI基盤チーム、承認済みアプリの開発者 |
| 設定方法 | 共通ライブラリまたは設定ファイルで一元管理 |
| ログ確認 | preview機能を使う処理はログ・メトリックを明示的に分ける |
| ロールバック | allow_preview=Falseで動く既存経路を残す |
サンプルコードとしては、次のようにpreview利用を明示します。
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
allow_preview=True,
)
with project_client.get_openai_client(
agent_name=os.environ["FOUNDRY_AGENT_NAME"]
) as openai_client:
# Agent endpoint経由の処理をここに実装
passstableな処理とpreviewな処理が同じアプリに混在する場合は、クライアント生成箇所を分けて、どの処理がpreview機能に依存しているか分かるようにしてください。
トレーシングと監査ログのチェックリスト
2.1.0で管理者が最も注意すべき変更は、トレーシングです。リリースノートでは、トレーシングが有効な場合にtrace context propagationが既定で有効になることがBreaking Changesとして記載されています。(PyPI)
Microsoft Learnでは、GenAI tracing instrumentationはexperimental preview機能であり、利用するにはAZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=trueを明示的に設定する必要があると説明されています。また、trace context propagationが有効な場合、OpenAIクライアント経由のHTTPリクエストにW3C Trace Contextヘッダーであるtraceparentやtracestateが注入されます。(Microsoft Learn)
トレーシング有効環境で確認する項目
- [ ]
AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=trueを設定している環境を洗い出した - [ ] Azure Monitor、Application Insights、OpenTelemetry exporterの送信先を確認した
- [ ] trace IDが外部サービス側へ送られることをセキュリティ担当に説明した
- [ ] 必要に応じて
AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION=falseを設定する方針を決めた - [ ]
baggageヘッダーを有効化していないことを確認した - [ ] メッセージ本文やツール呼び出し内容を記録する設定が有効になっていないか確認した
- [ ] OpenAIクライアントを生成する前にトレーシング設定が反映されるよう、初期化順序を確認した
Microsoft Learnでは、trace context propagationを無効化する方法として、環境変数AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION=falseまたはAIProjectInstrumentor().instrument()のenable_trace_context_propagation=Falseが示されています。また、この設定変更は変更後に取得したOpenAIクライアントへ反映され、すでに取得済みのクライアントには影響しないと説明されています。(Microsoft Learn)
セキュリティ上の注意点
traceparentやtracestateは、分散トレーシングの相関に役立ちます。一方で、監査方針によっては「外部サービスへトレース識別子を送ること」自体をレビュー対象にすべきです。
特にbaggageは慎重に扱ってください。Microsoft Learnでは、baggageにユーザー識別子、セッション情報、認証情報、個人情報などが含まれる可能性があるため、既定では伝播されないと説明されています。要件が明確でない限り、baggage propagationは有効化しない方が安全です。(PyPI)
.beta.agents、Skills、Toolboxesの運用チェック
2.1.0では、.beta.agents、beta.skills、beta.toolboxesに新しい操作が追加されました。リリースノートによると、.beta.agentsにはSession関連操作とpatch_agent_details()が追加され、beta.skillsには作成、パッケージからの作成、取得、一覧、更新、削除、ダウンロードが追加されています。beta.toolboxesにはバージョン作成、取得、一覧、更新、削除などの操作が追加されています。(PyPI)
管理者は、これらを「使える機能」として開放する前に、運用単位を決める必要があります。
| 機能領域 | 管理者が決めること | 失敗しやすいポイント |
|---|---|---|
.beta.agents Session操作 | Hosted Agentsを使うチーム、セッション保持期間、ファイル扱い | Hosted Agents以外でも使えると誤解する |
beta.skills | Skillパッケージの作成者、承認者、配布方法 | 未承認のSkillが環境へ混入する |
beta.toolboxes | Toolboxのバージョン管理、削除権限、更新手順 | 古いversionを参照するAgentが残る |
patch_agent_details() | Agent詳細の変更権限、変更履歴の記録 | 本番Agentの設定変更がレビューなしで行われる |
previewやbetaの呼び出しは、開発スピードを上げる一方で、運用管理の粒度が粗いとトラブルの原因になります。最低限、誰が作成し、誰が更新し、どこに履歴を残すかを決めてから利用を開始しましょう。
評価処理と型ヒントの変更を開発者へ周知する
2.1.0では、AIProjectClient.get_openai_client()で取得したOpenAIクライアントの.evals.create()と.evals.runs.create()に対して、型ヒントのサポートが追加されています。リリースノートでは、入力作成を支援するTypedDictクラスの追加も示されています。(PyPI)
これは管理者にとっても意味があります。評価処理は、AIアプリケーションの品質管理、レッドチーム、リリース判定に関わるため、入力形式のばらつきを減らせる可能性があります。
開発チームへは、次のように周知すると実務で伝わりやすくなります。
Azure AI Projects SDK for Python 2.1.0では、評価APIの入力作成に使える型ヒントが強化されています。
評価ジョブの新規実装・修正時は、公式サンプルのTypedDict利用例を参照し、辞書の手書きによるキー名ミスを減らしてください。
既存評価ジョブは、2.1.0へ上げた後にステージングで再実行し、入力形式・結果保存・失敗時ログを確認してください。型ヒントは実行時のすべてのミスを防ぐものではありません。CIで型チェックを行っていない場合は、mypyやpyrightなどの導入も合わせて検討すると効果が出やすくなります。
展開順序：管理者向けの安全なロールアウト手順
Azure AI Projects SDK for Python 2.1.0の展開は、次の順序で進めると失敗を減らせます。
| フェーズ | 実施内容 | 完了条件 |
|---|---|---|
| 棚卸し | SDK利用アプリ、バージョン、環境変数、トレーシング設定を洗い出す | 対象アプリ一覧と責任者が明確 |
| 開発環境検証 | azure-ai-projects==2.1.0へ固定して単体テストを実行 | 主要API呼び出しが成功 |
| 設定差分確認 | 新旧環境変数、allow_preview、ログ設定を確認 | 変更が設定台帳に反映済み |
| セキュリティ確認 | trace context、baggage、content recording、ログ共有ルールを確認 | セキュリティ担当が承認 |
| ステージング展開 | 本番相当の権限・ネットワーク・監視で検証 | エラー率、レイテンシ、ログが許容範囲 |
| 段階的本番展開 | 一部ワークロードから反映 | ロールバック手順が確認済み |
| 全体周知 | 開発者、運用、サポートへ変更点を共有 | 手順書・FAQ・問い合わせ先が更新済み |
本番反映前には、次のロールバック手順を必ず用意してください。
python -m pip install --upgrade "azure-ai-projects==<previous-approved-version>"
python -m pip show azure-ai-projects<previous-approved-version>には、自社で直前に承認していたバージョンを入れます。バージョンを覚え書きで管理せず、変更申請やリリースノートに明記しておくことが重要です。
周知チェックリスト：誰に何を伝えるべきか
2.1.0の周知は、開発者向けだけでは不十分です。運用、セキュリティ、サポート、プロジェクト管理者で知るべき内容が異なります。
| 対象者 | 伝える内容 | 伝え方 |
|---|---|---|
| 開発者 | 2.1.0の新機能、環境変数名、型ヒント、allow_preview | 技術メモ、サンプル差分、Pull Requestテンプレート |
| SRE・運用担当 | トレーシング既定動作、ログ、監視ダッシュボード | Runbook、監視項目、アラート条件 |
| セキュリティ担当 | trace ID伝播、baggage、content recording、非マスクログ | リスク説明、承認フロー、例外申請 |
| サポート担当 | よくある失敗、確認コマンド、問い合わせ切り分け | FAQ、一次対応フロー |
| 展開計画担当 | 検証順序、展開日、ロールバック条件 | リリース計画表、変更管理チケット |
社内周知文テンプレート
件名: Azure AI Projects SDK for Python 2.1.0の検証開始と設定確認のお願い
Azure AI Projects SDK for Python 2.1.0が公開されたため、対象アプリの検証を開始します。
今回の主な確認点は以下です。
- azure-ai-projectsのバージョン固定
- 環境変数名の確認
- FOUNDRY_PROJECT_ENDPOINT
- FOUNDRY_MODEL_NAME
- FOUNDRY_AGENT_NAME
- トレーシング有効環境でのtrace context propagation確認
- preview機能を使う場合のallow_preview=Trueの承認
- Hosted Agents、Skills、Toolboxes利用時の権限と運用ルール確認
本番反映前に、各チームはステージング環境で主要処理の動作確認を完了してください。
preview機能を利用する場合は、事前にAI基盤チームまたは運用責任者へ申請してください。よくある失敗と対策
古い環境変数名のまま新しいサンプルを実行する
新しいサンプルではFOUNDRY_PROJECT_ENDPOINTなどの名称が使われています。旧名称だけをSecretに登録していると、サンプルや新規コードが環境変数を読めずに失敗します。移行期は旧名称と新名称の両方を読み取る互換コードを入れ、最終的には新名称へ統一してください。
allow_preview=Trueを全アプリに入れてしまう
preview機能を使うアプリだけに限定してください。全アプリへ機械的に入れると、どの処理がpreview機能へ依存しているか分かりにくくなります。特に本番では、設定値ではなく変更申請単位で管理するのがおすすめです。
トレーシング設定を変更したのに反映されない
trace context propagationの設定は、すでに取得済みのOpenAIクライアントには反映されません。トレーシング設定を変更した場合は、OpenAIクライアントを再取得するか、アプリケーションを再起動して初期化順序を揃えてください。(Microsoft Learn)
ログをそのまま外部共有する
Azure AI Projects SDK for Pythonのドキュメントでは、コンソールログやカスタムログの設定が説明されていますが、ログにはトラブルシューティングに有用な情報だけでなく、環境によっては機密性の高い情報が含まれる可能性があります。非マスクログを扱う場合は、保存先、閲覧権限、共有ルールを明確にしてください。(PyPI)
管理者が今日やるべきこと
Azure AI Projects SDK for Python 2.1.0への対応は、次の順で始めると実務に落とし込みやすくなります。
- [ ]
azure-ai-projectsを使っているアプリと担当者を一覧化する - [ ] 現在のSDKバージョンと依存関係の固定方法を確認する
- [ ]
FOUNDRY_PROJECT_ENDPOINT、FOUNDRY_MODEL_NAME、FOUNDRY_AGENT_NAMEへの移行方針を決める - [ ] トレーシング有効環境でtrace context propagationの扱いを確認する
- [ ]
allow_preview=Trueを使える環境と承認者を決める - [ ] Hosted Agents、Skills、Toolboxesを使うチームに限定して2.1.0の検証を始める
- [ ] ステージングで主要処理、評価処理、ログ、ロールバックを確認する
- [ ] 開発者・運用・セキュリティ向けの周知文を配布する
2.1.0は、Azure AI Projects SDK for Pythonの利用範囲を広げる更新です。ただし、管理者にとっての中心は新機能の紹介ではなく、設定差分を見落とさないことです。まずは依存関係を固定し、環境変数とトレーシング設定を確認し、preview機能の利用ルールを決めてから展開しましょう。
コメント