Azure SDKのazure-ai-projects更新でまず確認すべき結論は、Hosted Agentのエンドポイント設定に使うモデル名がAgentEndpointからAgentEndpointConfigへ変更されたことです。from azure.ai.projects.models import AgentEndpointやAgentEndpoint(...)を使っているコードは、将来のSDK更新でインポートエラーや型チェックエラーになる可能性があります。
この変更は、azure-ai-projectsの2.2.0系に向けた破壊的変更として記録されています。2026年5月2日時点で情報を追っている開発者は、すぐに「自分の環境で反映済みか」を確認し、Hosted Agents、patch_agent_details()、get_openai_client(agent_name=...)まわりのコードとサンプルを点検するのが安全です。GitHub上の対象PRでは、TypeSpec由来の変更としてAgentEndpointからAgentEndpointConfigへのリネームと、Hosted Agentサンプルの更新が明記されています。(GitHub)
まず押さえるべき変更点
今回のAzure SDK更新は、単なるドキュメント文言の変更ではなく、Python SDKの公開API名に影響する破壊的変更として扱われています。対象はazure-ai-projectsパッケージ内のHosted Agent関連、特にエージェントのエンドポイント設定を渡す箇所です。
| 確認項目 | 変更前 | 変更後 | 実務上の確認ポイント |
|---|---|---|---|
| モデル名 | AgentEndpoint | AgentEndpointConfig | インポート文とインスタンス生成を置き換える |
AgentDetails.agent_endpointの型 | AgentEndpoint | AgentEndpointConfig | 取得結果を型注釈しているコードを確認する |
patch_agent_details()のagent_endpoint引数 | Optional[AgentEndpoint] | Optional[AgentEndpointConfig] | 同期・非同期どちらの呼び出しも確認する |
| Hosted Agentサンプル | AgentEndpoint(...) | AgentEndpointConfig(...) | 社内サンプル、README、手順書も更新する |
| 追加の破壊的変更 | HeaderIsolationKeySourceの一部必須引数 | 必須扱いが削除 | 同クラスを使っている場合はコンストラクタ呼び出しも点検する |
PRの変更ファイルには、CHANGELOG.md、models/_models.py、同期・非同期の_operations.py、samples/hosted_agents配下のサンプルが含まれています。つまり、変更対象は「名前だけ」ではなく、型定義・操作メソッド・利用例まで横断しています。(GitHub)
この変更はどのバージョンで意識すべきか
azure-ai-projectsの変更履歴では、2.2.0 (Unreleased)のBreaking ChangesとしてAgentEndpointからAgentEndpointConfigへのリネームが記載されています。一方、PyPI上では確認時点の最新公開版が2.1.0、リリース日が2026年4月20日と表示されています。(GitHub)
そのため、対応判断は次のように分けると安全です。
| 利用状況 | 対応方針 |
|---|---|
PyPI公開版のazure-ai-projects==2.1.0を固定している | 直ちに動かなくなる可能性は低いが、次回更新に備えて差分を確認する |
>=2.0.0や>=2.1.0のように上限なしで指定している | 2.2.0公開時にCIで壊れる可能性があるため、先に移行する |
| GitHubの開発ブランチやプレビュー機能を直接追っている | すぐにAgentEndpointConfigへ置き換える |
| Hosted Agentsのサンプルを社内テンプレート化している | サンプルコードと手順書を同時に更新する |
azure-ai-projectsを使っているがHosted Agentsを使っていない | 影響は限定的。ただし依存更新時のテストは必要 |
ポイントは、現時点で自分の環境にまだ反映されていなくても「次のSDK更新で反映される可能性がある変更」として扱うことです。特にCI/CDでpip install --upgrade azure-ai-projectsを実行している場合や、依存バージョンに上限を設けていない場合は、リリース後に突然失敗するリスクがあります。
なぜAgentEndpointConfigへ名前が変わったのか
実装上の役割を見ると、新しいAgentEndpointConfigは「エンドポイントURLそのもの」ではなく、エージェントのエンドポイント動作を設定するモデルです。生成後のモデル定義では、version_selector、protocols、authorization_schemesを持ち、エージェントのバージョンへのトラフィック振り分け、対応プロトコル、認可方式を表す構成オブジェクトとして扱われています。(GitHub)
この観点では、AgentEndpointという名前は「接続先URL」や「リソース上のエンドポイント」と誤解されやすく、AgentEndpointConfigのほうが用途を正確に表しています。特にAzure AI Foundryでは、プロジェクトエンドポイント、OpenAI互換エンドポイント、Hosted Agentのエンドポイント設定が混在します。名前を明確に分けることで、コードを読んだときに「これはURLではなく設定オブジェクトだ」と判断しやすくなります。
Microsoft Foundry SDKの公式説明でも、Foundry SDKはプロジェクトエンドポイントに接続してFoundry固有機能を扱う位置づけであり、エージェントや評価などの用途ではFoundry SDKを使うと整理されています。プロジェクトエンドポイントと、エージェントのエンドポイント設定モデルは混同しないようにしましょう。(Microsoft Learn)
対応が必要な開発者
今回の変更で優先的に確認すべきなのは、Azure AI FoundryのHosted AgentsやAgent endpoint preview機能をPython SDKから操作している開発者です。
具体的には、次のコードや設定に心当たりがある場合は対応対象です。
| 対象 | なぜ確認が必要か |
|---|---|
from azure.ai.projects.models import AgentEndpoint | 新しいSDKではAgentEndpointConfigへ変わるため |
endpoint_config = AgentEndpoint(...) | インスタンス生成名を変更する必要があるため |
project_client.beta.agents.patch_agent_details(...) | agent_endpoint引数の型が更新されているため |
project_client.get_openai_client(agent_name=...) | Agent endpoint経由のOpenAIクライアント利用と関係するため |
samples/hosted_agentsをベースにした社内コード | 公式サンプル側もAgentEndpointConfigへ更新されているため |
| 型チェックや自動生成コードを使っているプロジェクト | 実行前にmypyやpyrightで検出される可能性があるため |
azure-ai-projectsのREADMEでは、Hosted agentsはプレビュー機能として説明され、SDKサンプルはsamples/hosted_agents/に用意されています。Hosted Agentを使っている場合は、単にアプリ本体だけでなく、検証用スクリプト、デモコード、オンボーディング資料も確認してください。(GitHub)
対応しなくてもよい可能性が高いケース
すべてのazure-ai-projects利用者が今回の変更に直撃するわけではありません。以下のようなケースでは、影響は限定的です。
| 利用内容 | 影響 |
|---|---|
AIProjectClientで接続一覧やデプロイ一覧だけを取得している | 直接の影響は小さい |
| Datasets、Indexes、Connectionsだけを使っている | AgentEndpointConfigとは別領域 |
| OpenAI互換クライアントを通常のモデル呼び出しだけに使っている | Hosted Agent endpointを使っていなければ影響は限定的 |
AgentEndpointというクラス名を使っていない | 変更対象コードは少ない可能性が高い |
ただし、依存関係を広く指定しているプロジェクトでは、別の破壊的変更が同時に入ることがあります。今回の変更履歴にもHeaderIsolationKeySourceのコンストラクタ引数変更が記載されています。Hosted Agent関連のβ機能を使っている場合は、AgentEndpointだけでなくHeaderIsolationKeySourceも検索しておくと安全です。(GitHub)
変更前後のコード例
Hosted Agentのエンドポイント設定を行うコードでは、主にインポート名と生成するモデル名を変更します。引数名のagent_endpoint自体は、PR上の差分ではそのまま使われています。(GitHub)
変更前のイメージです。
from azure.ai.projects.models import (
AgentEndpoint,
AgentEndpointProtocol,
FixedRatioVersionSelectionRule,
VersionSelector,
)
endpoint_config = AgentEndpoint(
version_selector=VersionSelector(
version_selection_rules=[
FixedRatioVersionSelectionRule(
agent_version=agent.version,
traffic_percentage=100,
),
]
),
protocols=[AgentEndpointProtocol.RESPONSES],
)
patched_agent = project_client.beta.agents.patch_agent_details(
agent_name=agent_name,
agent_endpoint=endpoint_config,
)変更後は、AgentEndpointをAgentEndpointConfigに置き換えます。
from azure.ai.projects.models import (
AgentEndpointConfig,
AgentEndpointProtocol,
FixedRatioVersionSelectionRule,
VersionSelector,
)
endpoint_config = AgentEndpointConfig(
version_selector=VersionSelector(
version_selection_rules=[
FixedRatioVersionSelectionRule(
agent_version=agent.version,
traffic_percentage=100,
),
]
),
protocols=[AgentEndpointProtocol.RESPONSES],
)
patched_agent = project_client.beta.agents.patch_agent_details(
agent_name=agent_name,
agent_endpoint=endpoint_config,
)公式サンプルでも、AgentEndpointConfig、AgentEndpointProtocol.RESPONSES、FixedRatioVersionSelectionRuleを使い、単一のHosted Agentバージョンへ100%のトラフィックを向ける構成例が示されています。(GitHub)
移行手順
移行は、置換だけで済ませず、依存バージョン、プレビュー設定、実行経路まで確認するのが重要です。
| 手順 | 作業 | コマンド・確認例 |
|---|---|---|
| 1 | インストール済みバージョンを確認する | python -m pip show azure-ai-projects |
| 2 | 旧モデル名を検索する | grep -R "AgentEndpoint" -n . |
| 3 | インポートを置き換える | AgentEndpoint → AgentEndpointConfig |
| 4 | インスタンス生成を置き換える | AgentEndpoint(...) → AgentEndpointConfig(...) |
| 5 | 型注釈とドキュメントを更新する | Optional[AgentEndpoint]を使っていないか確認 |
| 6 | Hosted Agentのプレビュー設定を確認する | AIProjectClient(..., allow_preview=True) |
| 7 | 同期・非同期サンプルの両方をテストする | sample_agent_endpoint.pyとasync相当を確認 |
| 8 | CIで依存更新テストを行う | 上限なしの依存指定を避ける |
特にallow_preview=Trueは見落としやすいポイントです。azure-ai-projects 2.1.0の変更履歴では、get_openai_client()にagent_nameを渡すとAgent endpointのbase URLを使うようになり、Agent endpointsはプレビュー機能のためAIProjectClientのコンストラクタでallow_preview=Trueを設定する必要があると説明されています。(GitHub)
設定確認で見るべきポイント
コードを置き換えたあと、次の設定を確認してください。Hosted Agent関連は、名前の変更だけでなく、プロジェクトエンドポイント、認証、セッション、トラフィックルーティングが組み合わさって動きます。
| 確認項目 | 見るべき内容 | 失敗しやすいポイント |
|---|---|---|
FOUNDRY_PROJECT_ENDPOINT | FoundryプロジェクトのエンドポイントURL | Azure OpenAIの/openai/v1エンドポイントと混同する |
FOUNDRY_HOSTED_AGENT_NAME | 既存のHosted Agent名 | サンプル実行前にHosted Agentが存在しない |
allow_preview=True | プレビュー機能を明示的に有効化 | β操作なのに通常クライアント設定で呼び出す |
version_selector | どのAgentバージョンへ流すか | 古いバージョンに100%流したままになる |
protocols | AgentEndpointProtocol.RESPONSESなど | OpenAI Responses API呼び出しと対応していない |
| セッション削除 | delete_session()の実行 | 例外時にセッションが残る |
| 認証 | DefaultAzureCredentialやRBAC | ローカルでは動くがCIで権限不足になる |
PyPIのプロジェクト説明では、前提条件としてPython 3.9以降、Azureサブスクリプション、Microsoft Foundryプロジェクト、Foundryプロジェクトエンドポイントが挙げられています。また、Entra ID認証ではDefaultAzureCredentialを使う例が示されています。(PyPI)
CIで壊さないための依存関係管理
今回のようなSDKの破壊的変更は、ローカルでは再現しないのにCIや本番デプロイ時に突然出ることがあります。原因は、依存バージョンの指定が広すぎることです。
避けたい指定例です。
azure-ai-projects>=2.0.0この指定では、2.2.0が公開されたタイミングで自動的に取り込まれ、AgentEndpointを使っているコードが失敗する可能性があります。
移行前に安定させたい場合は、一時的に上限を設けます。
azure-ai-projects>=2.1.0,<2.2.0移行後に2.2.0系へ進める場合は、テストを通してから範囲を広げます。
azure-ai-projects>=2.2.0,<3.0.0ただし、実際にどのバージョンを指定するかは、PyPIの公開状況、社内の検証結果、利用しているプレビュー機能に合わせて判断してください。2.2.0は変更履歴上ではUnreleasedとして記載されているため、公開前の段階では直接指定できない場合があります。(GitHub)
よくある失敗と対策
| 失敗例 | 原因 | 対策 |
|---|---|---|
ImportError: cannot import name 'AgentEndpoint' | 新SDKで旧モデル名を読み込んでいる | AgentEndpointConfigへ置換する |
型チェックでAgentEndpointが見つからない | 型定義が更新済み | 型注釈も含めて置換する |
patch_agent_details()は呼べるが期待通りに動かない | Agentバージョンやprotocol設定が不整合 | version_selectorとprotocolsを確認する |
| サンプルだけ更新して本体が古い | 社内テンプレートと本番コードが別管理 | リポジトリ全体でAgentEndpointを検索する |
| CIだけ失敗する | CIで最新SDKを取得している | lockファイルまたは上限指定を使う |
| プレビュー機能が使えない | allow_preview=Trueがない | クライアント生成時の引数を確認する |
| ドキュメントと実コードが違う | 生成SDKやDocs反映に時間差がある | インストール済みSDKのリリース履歴を優先して確認する |
特に注意したいのは、変数名としてのendpoint_configまで無理に変える必要はない点です。むしろ、AgentEndpointConfigを使うなら、変数名はendpoint_configのままのほうが「設定オブジェクト」であることが伝わります。
HeaderIsolationKeySourceも検索しておく
今回のPRで目立つのはAgentEndpointのリネームですが、同じBreaking ChangesにはHeaderIsolationKeySourceのコンストラクタからuser_isolation_keyとchat_isolation_keyの必須パラメータが削除されたことも記載されています。(GitHub)
この変更は、Hosted Agentのセッション分離やヘッダー由来の分離キーを使っているコードに関係する可能性があります。以下のように検索しておくと、将来の差分確認が楽になります。
grep -R "HeaderIsolationKeySource" -n .
grep -R "user_isolation_key" -n .
grep -R "chat_isolation_key" -n .必須パラメータが削除された変更は、古いコードが必ず壊れるという意味ではありません。ただし、コンストラクタのシグネチャが変わると、型チェック、ラッパー関数、社内SDK、テストダブルに影響することがあります。AgentEndpointConfigへの移行と同じタイミングで確認しておくのが効率的です。
TypeSpec由来の変更として見るべき理由
今回のPRは、TypeSpecソースからSDKを生成し、post-emitter fixを適用する流れの中で行われています。Python SDK側のPRでは、TypeSpec SourceとしてAzure/azure-rest-api-specs、ブランチfeature/foundry-release、コミットf6fde1c197adf274a4b344ea27ec26490841ab68、関連PR「Rename AgentEndpoint to AgentEndpointConfig」が示されています。(GitHub)
TypeSpec由来の変更は、Pythonだけで閉じない可能性があります。関連するREST API仕様のPRでは、APIViewがTypeSpec、Python、JavaScript向けのAPIレビューを作成したことが表示されています。Python以外のSDKを使っているチームも、「同じ名前変更が自分の言語SDKに反映されるか」を各言語のリリースノートで確認してください。(GitHub)
ただし、Python SDKのクラス名をそのままJavaScriptや.NETに当てはめるのは避けるべきです。各言語では命名規則、公開時期、パッケージ分割が異なることがあります。実務では、PythonのPRを変更の起点として把握しつつ、最終判断は利用言語の公式CHANGELOGとインストール済みパッケージで行うのが安全です。
レビュー時のチェックリスト
SDK更新のレビューでは、次の項目をそのままチェックリストとして使えます。
[ ] azure-ai-projectsの現在のバージョンを確認した
[ ] requirements.txtやpyproject.tomlのバージョン指定を確認した
[ ] AgentEndpointの使用箇所を全検索した
[ ] AgentEndpointConfigへインポートと生成処理を置換した
[ ] patch_agent_details()の呼び出しを同期・非同期とも確認した
[ ] Hosted Agentサンプル、社内ドキュメント、READMEを更新した
[ ] allow_preview=Trueの必要性を確認した
[ ] FOUNDRY_PROJECT_ENDPOINTとHosted Agent名を確認した
[ ] HeaderIsolationKeySourceの使用箇所も検索した
[ ] CIでクリーンインストールからテストしたこのチェックリストで重要なのは、最後の「クリーンインストールからテスト」です。開発者のローカル環境には古いSDKが残っていることがあり、移行漏れが見えません。CIで新規仮想環境を作り、依存関係を入れ直して実行すると、将来のデプロイ失敗を早めに検出できます。
今回の変更をどう扱うべきか
今回のAzure SDK更新は、AgentEndpointという名前をAgentEndpointConfigへ変える小さな差分に見えます。しかし、Hosted Agentのエンドポイント設定、Responsesプロトコル、プレビュー機能、TypeSpecからのSDK生成が関係しているため、実務では「依存更新時に壊れやすい変更」として扱うべきです。
まずは、リポジトリ全体でAgentEndpointを検索してください。見つかった場合は、AgentEndpointConfigへ置き換え、patch_agent_details()まわりの統合テストを実行します。次に、依存バージョンの上限を確認し、2.2.0系を取り込むタイミングをチームで決めます。Hosted Agentsを本番利用している場合は、サンプルコードだけでなく、運用手順書、CI、デモ環境、検証用スクリプトまで同時に更新するのが安全です。
コメント