Azure SDK documentation update: [Release] azure-ai-agentserver-core 2.0.0b4, azure-ai-agentserver-invocations 1.0.0b4 の要点は、Azure AI Agent Server系パッケージのトレーシング基盤が microsoft-opentelemetry に寄せられたことです。公開APIや通常のエンドポイント挙動は変わらないとされていますが、Azure Monitor、OTLP、OpenTelemetry関連の依存関係を管理しているチームは、ロックファイル・環境変数・テレメトリ出力を確認すべき更新です。
特に対応が必要なのは、azure-ai-agentserver-core または azure-ai-agentserver-invocations を使って Azure AI Hosted Agent コンテナーを構築している開発者、CI/CDでPython依存関係を固定している担当者、Application InsightsやOpenTelemetry Collectorでトレースを監視している運用担当者です。PR上のRelease packagesでは2026年5月1日リリース扱いとして、core 2.0.0b4 と invocations 1.0.0b4 の変更が整理されています。(GitHub)
Azure SDK documentation updateの変更点
今回の更新は、新機能追加やAPI破壊的変更というより、監視・トレーシングまわりの実装整理として捉えるのが適切です。
| 対象パッケージ | バージョン | 主な変更 | 実務上の確認ポイント |
|---|---|---|---|
azure-ai-agentserver-core | 2.0.0b4 | トレーシングのエクスポート処理を、従来の azure-monitor-opentelemetry-exporter と opentelemetry-exporter-otlp-proto-grpc から、統合ディストリビューションである microsoft-opentelemetry へ移行 | Azure Monitor、OTLP、OpenTelemetry関連の依存関係と環境変数を確認する |
azure-ai-agentserver-invocations | 1.0.0b4 | azure-ai-agentserver-core>=2.0.0b4 から継承する形で、トレーシング基盤を microsoft-opentelemetry に更新 | invocations だけを直接使っている場合でも、依存先の core 更新による影響を確認する |
| 公開API・挙動 | 変更なしと記載 | PR上では public API / behavior の変更なし | APIコードの全面改修ではなく、依存関係・監視設定・検証が中心 |
PRの差分では、core のCHANGELOGに「unified microsoft-opentelemetry distro への移行」と「環境変数によるexporter自動検出」が記載されています。invocations 側も、core>=2.0.0b4 から継承する形でトレーシング基盤が更新されています。(GitHub)
なお、当初のPR概要では azure-ai-agentserver-responses 1.0.0b6 も候補に含まれていましたが、最終的なタイトルでは core と invocations に絞られています。影響範囲を確認する際は、responses まで一律に対象と決めつけないようにしてください。(GitHub)
そもそも対象パッケージは何に使われるのか
azure-ai-agentserver-core は、Azure AI Hosted Agent コンテナーを構築するための基盤パッケージです。ヘルスチェック、グレースフルシャットダウン、OpenTelemetryトレーシング、ASGIサーバー実行など、エージェントサーバーの土台になる処理を担います。(PyPI)
一方、azure-ai-agentserver-invocations は、POST /invocations、GET /invocations/{id}、POST /invocations/{id}/cancel など、エージェント呼び出しのライフサイクルを扱うプロトコルパッケージです。invocations は core のホストフレームワークに組み込まれるため、core を直接importしていないアプリでも、依存関係として影響を受ける可能性があります。(PyPI)
対応すべき人と対応不要な人
| 利用状況 | 対応優先度 | 取るべき行動 |
|---|---|---|
azure-ai-agentserver-core を直接使っている | 高 | 2.0.0b4 の取得可否、依存関係、トレース出力をステージングで確認する |
azure-ai-agentserver-invocations を使っている | 高 | core>=2.0.0b4 が入る前提で、呼び出しAPIとテレメトリを確認する |
| Azure Monitor / Application Insights にトレースを送っている | 高 | APPLICATIONINSIGHTS_CONNECTION_STRING、Cloud Role名、サンプリング設定を確認する |
| OpenTelemetry CollectorやOTLP endpointを使っている | 中〜高 | OTEL_EXPORTER_OTLP_ENDPOINT などの環境変数と二重送信を確認する |
| Agent Server系パッケージを使っていない | 低 | 今回の更新による直接対応は基本的に不要 |
| 本番でベータ版SDKを使わない方針の組織 | 中 | すぐ更新せず、正式版または社内検証済みバージョンまで待つ判断も妥当 |
Microsoft LearnのAzure SDKパッケージインデックスでは、Python SDKのバージョン番号に b が付くものはベータリリースとして扱われると説明されています。2.0.0b4 や 1.0.0b4 は正式安定版ではないため、本番適用前の検証は必須です。(Microsoft Learn)
public API変更なしでも確認が必要な理由
「public APIやbehaviorに変更なし」と書かれている場合でも、実務では何もしなくてよいとは限りません。今回の変更は、アプリの呼び出しコードよりも、依存関係・監視・環境変数・テレメトリ出力先に影響しやすい内容です。
microsoft-opentelemetry は、Azure Monitor、OTLP互換バックエンド、Microsoft Agent 365連携に向けた観測性の統合的な導入体験を提供するPythonパッケージとして説明されています。また、Azure Monitor接続文字列、OTLP endpoint、A365関連設定など、複数の出力先や環境変数を扱います。(Microsoft Learn)
特に注意したいのは、既存アプリ側で独自に azure-monitor-opentelemetry-exporter や opentelemetry-exporter-otlp-proto-grpc を使っているケースです。SDK内部のトレーシング基盤が移行されたからといって、アプリ側の明示的な exporter 設定まで自動で整理されるわけではありません。古い依存関係を削除する前に、自分のコードで直接importしていないか確認してください。
移行前に確認するコマンド
まず、現在の環境でAgent Server系パッケージとOpenTelemetry関連パッケージがどのように入っているか確認します。
python -m pip freeze | grep -E "azure-ai-agentserver|opentelemetry|azure-monitor|microsoft-opentelemetry"Windows PowerShellの場合は、次のように確認できます。
python -m pip freeze | Select-String "azure-ai-agentserver|opentelemetry|azure-monitor|microsoft-opentelemetry"次に、対象バージョンがパッケージインデックスやPyPIで取得可能か確認します。ベータ版を扱うため、--pre を付けて確認するのが実務上安全です。
python -m pip index versions --pre azure-ai-agentserver-core
python -m pip index versions --pre azure-ai-agentserver-invocations取得可能であることを確認できたら、ステージング環境でバージョンを固定して更新します。
python -m pip install --upgrade --pre \
azure-ai-agentserver-core==2.0.0b4 \
azure-ai-agentserver-invocations==1.0.0b4requirements.txt や pyproject.toml、ロックファイルを使っている場合は、次のようにバージョンを明示して、CIで同じ依存関係が再現されるようにします。
azure-ai-agentserver-core==2.0.0b4
azure-ai-agentserver-invocations==1.0.0b4ただし、invocations だけを使っているプロジェクトでは、core が依存関係として入る構成もあります。両方を明示的に固定するか、依存解決に任せるかは、チームのロックファイル運用に合わせて判断してください。
環境変数と監視設定のチェックポイント
今回の更新で最も確認すべきなのは、トレースの送信先が意図どおりになっているかです。
| 確認項目 | 主な環境変数・設定 | 確認内容 |
|---|---|---|
| Azure Monitor / Application Insights | APPLICATIONINSIGHTS_CONNECTION_STRING | 接続文字列が本番・ステージングで混在していないか |
| OTLP出力 | OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Collectorや外部バックエンドへ二重送信していないか |
| サービス名・ロール名 | OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES | Application Map上のCloud Role Nameが期待どおり表示されるか |
| サンプリング | OTEL_TRACES_SAMPLER、OTEL_TRACES_SAMPLER_ARG | トレース量が急増・急減しないか |
| Agent 365連携を使う場合 | ENABLE_A365_OBSERVABILITY_EXPORTER、ENABLE_OBSERVABILITY | 利用していない環境で誤って有効化していないか |
| 独自exporter設定 | アプリ内のOpenTelemetry初期化コード | SDK側とアプリ側で二重にspan processorを登録していないか |
Azure Monitorの設定では、Application Insights接続文字列を APPLICATIONINSIGHTS_CONNECTION_STRING で指定する方法が案内されています。また、Cloud Role NameやCloud Role Instanceに関わる情報は、OTEL_SERVICE_NAME や OTEL_RESOURCE_ATTRIBUTES で調整できます。(Microsoft Learn)
OTLPについては、microsoft-opentelemetry のドキュメントで OTEL_EXPORTER_OTLP_ENDPOINT などの環境変数が説明されています。環境変数で自動検出される仕組みは便利ですが、古い設定が残っていると、意図しない送信先へテレメトリが流れる可能性があります。(GitHub)
ステージングで実施すべき動作確認
更新後は、単にアプリが起動するかではなく、エージェント呼び出しとトレース出力をセットで確認します。
| テスト | 確認方法 | 期待する結果 |
|---|---|---|
| ヘルスチェック | GET /readiness | 200 OK が返る |
| 基本呼び出し | POST /invocations | エージェント処理が実行され、想定したレスポンスが返る |
| 状態取得 | GET /invocations/{id} | 長時間処理を使う場合、状態や結果を取得できる |
| キャンセル | POST /invocations/{id}/cancel | キャンセル対応を実装している場合、期待どおり中断される |
| トレース確認 | Application Insights、Azure Monitor、OTLP Collectorなどで確認 | invoke_agent などのspanが記録され、サービス名・セッションIDが追跡できる |
| 依存関係確認 | pip freeze、ロックファイル差分、CIログ | 予期しないOpenTelemetry関連パッケージの競合がない |
azure-ai-agentserver-invocations のドキュメントでは、POST /invocations、状態取得、キャンセル、OpenAPI spec提供などのエンドポイントが説明されています。更新後の確認では、実際に使っているエンドポイントだけでなく、運用監視に必要なspan属性やエラータグが記録されているかも確認してください。(PyPI)
失敗しやすいポイント
「API変更なし」だけを見て検証を省略する
今回の変更はAPI互換性よりも、トレーシング基盤の移行が中心です。アプリコードがそのままでも、依存関係やテレメトリ送信先が変わる可能性があります。最低限、ステージングで起動、呼び出し、トレース確認まで実施してください。
古いexporter依存関係をすぐ削除する
azure-monitor-opentelemetry-exporter や opentelemetry-exporter-otlp-proto-grpc を自分のアプリで直接使っている場合、SDK側の移行だけを理由に削除すると、独自の監視処理が壊れる可能性があります。削除する前に、import、初期化コード、CIの依存関係チェックを確認しましょう。
OTLPとAzure Monitorへ二重送信してしまう
環境変数による自動検出は便利ですが、古い OTEL_EXPORTER_OTLP_ENDPOINT が残っていると、Azure Monitorに加えてOTLP Collectorにも送信される場合があります。意図した二重送信であれば問題ありませんが、そうでない場合はコスト、ログ量、トラブルシュートの複雑さが増えます。
ベータ版を本番へ自動適用する
2.0.0b4 や 1.0.0b4 はベータ版です。社内で「ベータSDKは本番禁止」「ベータはステージングのみ」「特定サービスだけ例外」といったルールがある場合は、リリースノートよりも社内ポリシーを優先してください。
Cloud Role Nameが変わったことに気づかない
監視ダッシュボードでサービス名やロール名が変わると、障害時に「トレースが消えた」と誤認しやすくなります。OTEL_SERVICE_NAME と OTEL_RESOURCE_ATTRIBUTES を使って、ステージング・本番で識別しやすい名前に固定しておくと、運用時の混乱を防げます。
更新判断の目安
すぐに試すべきケースは、すでにAgent Server系ベータパッケージを使っており、Azure MonitorやOTLPでトレースを収集している場合です。今回の変更は監視基盤に関わるため、早めにステージングで差分を見ておく価値があります。
一方で、本番環境で安定版SDKのみを使う方針なら、無理に導入する必要はありません。PRやPyPIで対象バージョンが確認できるか、Azure SDKのリリース一覧に反映されているか、既存のCIで依存関係が解決できるかを確認してから進めるのが安全です。Azure SDKのPythonパッケージはPyPIに公開され、最新バージョンやリリース履歴はAzure SDKリリース情報で確認する流れが案内されています。(Microsoft Learn)
まずやるべきこと
今回のAzure SDK documentation updateで最初にやるべきことは、コード修正ではなく現状把握です。以下の順で確認すると、影響範囲を短時間で切り分けられます。
pip freezeやロックファイルで、azure-ai-agentserver-*とOpenTelemetry関連パッケージを確認するAPPLICATIONINSIGHTS_CONNECTION_STRING、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_SERVICE_NAMEなどの環境変数を棚卸しするcore 2.0.0b4とinvocations 1.0.0b4が取得可能であることを確認してから、ステージングで更新する/readinessと/invocationsの動作、Application InsightsまたはOTLP Collectorへのトレース出力を確認する- 問題がなければ、ロックファイル、監視ダッシュボード、ロール名、サンプリング設定を含めて本番反映手順を固める
公開APIに変更がない更新ほど、影響を軽く見積もりがちです。今回のようにトレーシング基盤が変わる場合は、アプリのレスポンスだけでなく「正しい場所に、正しい名前で、必要なトレースが出ているか」まで確認することが、実運用での失敗を防ぐポイントです。
コメント