Azure SDKのAgentEndpoint非推奨警告とは？AgentEndpointConfigへの移行手順

Azure SDK documentation updateでまず確認すべき結論は、azure.ai.projects.models から AgentEndpoint をimportしているPythonコードは、できるだけ早く AgentEndpointConfig に置き換えるべき、という点です。古い AgentEndpoint は当面動作しますが、importまたは属性参照の時点で DeprecationWarning が出る設計になっています。警告はインスタンス生成時ではなく、from azure.ai.projects.models import AgentEndpoint のように読み込んだ段階で発生する点が実務上の注意点です。(GitHub)

この変更は、Azure SDK for Pythonの azure-ai-projects に関するPRで示されたものです。PR上では AgentEndpoint を正式なモデル名として扱うのではなく、AgentEndpointConfig を正規のクラス名として使う方向に整理されています。なお、PRタイトルには AgentEndpoingConfig という表記ゆれが見えますが、実際にコードで使う移行先は AgentEndpointConfig です。(GitHub)

Azure SDKのAgentEndpoint非推奨警告で何が変わるのか

今回の変更は、AzureのサービスエンドポイントURLそのものが変わる話ではありません。影響するのは、Python SDKのモデルクラス名です。

AgentEndpoint という旧クラス名を使っていたコードは、後方互換のために引き続き動作します。ただし、SDK側では「この名前は非推奨であり、次のリリースで削除される可能性がある」という警告を出すようになります。PRの説明では、正規のモデル名を AgentEndpointConfig にリネームし、型ヒントやドキュメント、サンプルもそれに合わせて更新する内容が示されています。(GitHub)

確認項目	変更前	変更後
使用するクラス名	`AgentEndpoint`	`AgentEndpointConfig`
旧コードの動作	動作する	当面は動作するが警告対象
警告のタイミング	なし	importまたは属性参照時
主な影響箇所	Hosted Agentのエンドポイント設定	`patch_agent_details`、サンプル、型ヒント、テスト
すぐ壊れるか	基本的には壊れない	CI設定によっては警告で失敗する可能性あり

対応が必要な人

特に確認すべきなのは、Azure AI ProjectsのPython SDKでHosted AgentやAgent endpointを扱っている開発者です。azure-ai-projects はMicrosoft Foundry SDKの一部として、Foundry Project内のAgent、接続、モデル、評価、データセットなどへアクセスするためのクライアントライブラリです。(Microsoft Learn)

次のいずれかに当てはまる場合は、コードを確認してください。

from azure.ai.projects.models import AgentEndpoint を使っている
project_client.beta.agents.patch_agent_details() で agent_endpoint を設定している
Hosted Agentのエンドポイント設定サンプルを参考に実装している
CIで DeprecationWarning をエラー扱いにしている
SDKの型ヒント、スタブ、サンプルコードを社内テンプレート化している
ライブラリや共通モジュールで AgentEndpoint を再exportしている

一方で、単に FOUNDRY_PROJECT_ENDPOINT のようなプロジェクトエンドポイントURLを設定しているだけのコードや、Agent endpointの設定モデルを使っていない処理は、このクラス名変更の直接的な影響を受けにくいです。

変更前後のコード例

最も基本的な対応は、import文と生成するクラス名を置き換えることです。

変更前のコードは次のようになります。

from azure.ai.projects.models import AgentEndpoint, AgentEndpointProtocol

endpoint_config = AgentEndpoint(
    protocols=[AgentEndpointProtocol.A2A]
)

変更後は、AgentEndpointConfig を使います。

from azure.ai.projects.models import AgentEndpointConfig, AgentEndpointProtocol

endpoint_config = AgentEndpointConfig(
    protocols=[AgentEndpointProtocol.A2A]
)

PRの例でも、旧名 AgentEndpoint をimportすると DeprecationWarning が出る一方、作成したオブジェクトの protocols は従来どおり扱えることが示されています。つまり、挙動変更というより「正式な名前に移行するための警告」と考えるのが実務的です。(GitHub)

patch_agent_detailsを使っている場合の確認ポイント

影響を受けやすいのは、Agent endpointの設定を更新する処理です。PRでは同期版・非同期版の patch_agent_details の型ヒントとドキュメントが、AgentEndpointConfig を受け取る形に更新されています。(GitHub)

たとえば、Hosted AgentのエンドポイントをResponsesプロトコル向けに設定する場合は、次のような形になります。

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,
)

Azure SDK側のサンプルでも、Hosted Agentのセッション作成、Agent endpoint設定、OpenAI Responses API呼び出しの流れで AgentEndpointConfig が使われています。(GitHub)

移行時に見るべきチェックリスト

単純な置換で済むケースが多いものの、実務では「importだけ残っている」「テストだけ古い」「社内テンプレートが古い」といった見落としが起きやすいです。次の順に確認すると、安全に移行できます。

手順	確認内容	実行例
依存関係の確認	使用中の `azure-ai-projects` バージョンを確認する	`python -m pip show azure-ai-projects`
旧クラス名の検索	`AgentEndpoint` の使用箇所を洗い出す	`grep -R "AgentEndpoint" .`
importの置換	`AgentEndpointConfig` に変更する	`from azure.ai.projects.models import AgentEndpointConfig`
型ヒントの修正	関数戻り値や引数の型も更新する	`def build_config() -> AgentEndpointConfig:`
テスト実行	警告が残っていないか確認する	`python -W default -m pytest`
CI確認	警告をエラー扱いにする設定がないか見る	`PYTHONWARNINGS=error::DeprecationWarning` など
ドキュメント更新	README、サンプル、社内Wikiを更新する	コピペ元を修正

Windows環境では、PowerShellで次のように検索できます。

Select-String -Path .\**\*.py -Pattern "AgentEndpoint"

AgentEndpointProtocol や AgentEndpointAuthorizationScheme のように、名前が似ていても非推奨対象ではない型まで一括置換しないよう注意してください。置き換えるのは、旧クラス名としての AgentEndpoint です。

CIで突然失敗する可能性があるケース

この変更は「古いコードが即座に動かなくなる」タイプではありません。ただし、CIやテスト設定によっては影響が大きくなります。

たとえば、次のような設定をしているプロジェクトでは、DeprecationWarning が出た時点でテストが失敗する可能性があります。

python -W error::DeprecationWarning -m pytest

また、警告はインスタンス生成時ではなくimportまたは属性参照時に出ます。そのため、実際にはAgent endpointを使わないテストでも、共通モジュールで AgentEndpoint をimportしているだけで警告が発生する場合があります。PRのテストでも、警告は「インスタンス化」ではなく「属性アクセス」で発生することを確認しています。(GitHub)

実務では、次のような順序で切り分けると早いです。

AgentEndpoint のimport箇所をすべて検索する
AgentEndpointConfig に置き換える
テストを通常モードで実行する
警告をエラー扱いにして再実行する
社内共通パッケージやテンプレートにも旧名が残っていないか確認する

よくある失敗と回避策

PRタイトルの表記ゆれをそのまま使ってしまう

今回のトピックでは AgentEndpoingConfig という表記が出てくることがありますが、実際のクラス名は AgentEndpointConfig です。Endpoint のつづりを間違えると、当然ながらimportに失敗します。

正しい書き方は次のとおりです。

from azure.ai.projects.models import AgentEndpointConfig

誤った書き方は避けてください。

from azure.ai.projects.models import AgentEndpoingConfig

生成箇所だけ直してimport文を残す

次のように、インスタンス生成だけを直しても、古いimportが残っていると警告や不要な依存が残ります。

from azure.ai.projects.models import AgentEndpoint, AgentEndpointConfig

この場合、AgentEndpoint を使っていないなら削除します。

from azure.ai.projects.models import AgentEndpointConfig

ワイルドカードimportに依存している

from azure.ai.projects.models import * のような書き方は、今回のようなモデル名変更に弱くなります。どの型を使っているか分かりにくく、移行漏れも見つけにくいためです。

Agent endpoint設定を扱うコードでは、次のように必要な型を明示したほうが保守しやすくなります。

from azure.ai.projects.models import (
    AgentEndpointConfig,
    AgentEndpointProtocol,
    VersionSelector,
)

「まだ動くから対応しない」と判断する

旧名がまだ動くのは、互換性を保つための猶予です。PRの警告文では、AgentEndpoint は非推奨であり、次のリリースで削除される可能性がある旨が示されています。(GitHub)

本番障害を避けるには、SDKアップデート時に慌てて直すのではなく、警告が出た段階で移行しておくのが安全です。

対応優先度の判断基準

すべてのプロジェクトで緊急対応が必要とは限りません。次の基準で優先度を決めるとよいでしょう。

状況	優先度	理由
CIでDeprecationWarningをエラー扱いしている	高	ビルドやテストが失敗する可能性がある
共通ライブラリで `AgentEndpoint` をexportしている	高	利用側全体に警告が広がる
Hosted Agentのendpoint設定を本番で更新している	高	将来のSDK更新時に影響が出やすい
サンプルコードや検証環境だけで使っている	中	早めに直せば十分
`azure-ai-projects` は使っているがAgent endpoint設定は使っていない	低	直接影響は限定的
別言語のSDKだけを使っている	要確認	今回の具体例はPython SDK中心の変更

特に、社内でAzure SDKのサンプルをコピーしてプロジェクトの雛形にしている場合は、テンプレート側を先に直してください。アプリ本体だけを修正しても、新規プロジェクトで同じ警告が再発します。

実務での安全な移行方針

おすすめの進め方は、まず機械的に置換し、その後に型チェックとテストで確認する方法です。

# 使用箇所を検索
grep -R "AgentEndpoint" .

# 警告を表示してテスト
python -W default -m pytest

# 必要に応じて警告をエラー扱いにして確認
python -W error::DeprecationWarning -m pytest

ただし、AgentEndpointProtocol や AgentEndpointAuthorizationScheme など、関連する型まで置換しないようにしてください。検索結果を見ながら、旧クラス名としての AgentEndpoint だけを対象にするのが安全です。

また、今回の情報はGitHub PRベースの内容です。PRページでは2026年5月2日に承認が付いている一方で、表示上はOpenの状態です。実際に手元のSDKバージョンへ反映されているかは、利用中の azure-ai-projects のバージョン、リリースノート、インストール済みパッケージで確認してください。(GitHub)

まとめ：AgentEndpointは早めにAgentEndpointConfigへ置き換える

今回のAzure SDK documentation updateで重要なのは、AgentEndpoint から AgentEndpointConfig への移行です。旧名は当面動作しますが、非推奨警告が出るため、CIやテスト、社内共通コードでは早めに対応したほうが安全です。

まずはプロジェクト内で AgentEndpoint を検索し、import文、インスタンス生成、型ヒント、サンプル、READMEを確認してください。patch_agent_details でAgent endpointを設定しているコードは特に優先度が高いです。

次に取るべき行動はシンプルです。AgentEndpoint を使っている箇所を洗い出し、AgentEndpointConfig に置き換え、警告を表示した状態でテストを実行することです。これだけで、将来のSDK更新時に不要なビルド失敗や移行作業の手戻りを減らせます。

この記事を書いた人

佐藤健司

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

Azure SDKのAgentEndpoint非推奨警告とは？AgentEndpointConfigへの移行手順

Azure SDKのAgentEndpoint非推奨警告で何が変わるのか

対応が必要な人

変更前後のコード例

patch_agent_detailsを使っている場合の確認ポイント

移行時に見るべきチェックリスト

CIで突然失敗する可能性があるケース

よくある失敗と回避策

PRタイトルの表記ゆれをそのまま使ってしまう

生成箇所だけ直してimport文を残す

ワイルドカードimportに依存している

「まだ動くから対応しない」と判断する

対応優先度の判断基準

実務での安全な移行方針

まとめ：AgentEndpointは早めにAgentEndpointConfigへ置き換える

この記事を書いた人

コメント

コメントするコメントをキャンセル

Azure SDKのAgentEndpoint非推奨警告とは？AgentEndpointConfigへの移行手順

Azure SDKのAgentEndpoint非推奨警告で何が変わるのか

対応が必要な人

変更前後のコード例

patch_agent_detailsを使っている場合の確認ポイント

移行時に見るべきチェックリスト

CIで突然失敗する可能性があるケース

よくある失敗と回避策

PRタイトルの表記ゆれをそのまま使ってしまう

生成箇所だけ直してimport文を残す

ワイルドカードimportに依存している

「まだ動くから対応しない」と判断する

対応優先度の判断基準

実務での安全な移行方針

まとめ：AgentEndpointは早めにAgentEndpointConfigへ置き換える

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

コメントするコメントをキャンセル