Coordinated Azure AI Agent Server Python beta wave updates core, invocations, and responses packages は、Azure AI Agent Server SDK for Python を使う開発者が、最初に「ログ」「相関ID」「Responsesのチャット分離」「ID検証」「SSE replay」「Foundryストレージ連携」を確認すべきベータ更新です。
結論から言うと、今回の更新は大きな新機能の追加というより、エージェントサーバーを実運用に近い形で検証しやすくするための改善です。2026年4月20日時点で確認対象になるのは、Pre-releaseとして公開されている azure-ai-agentserver-core_2.0.0b2、azure-ai-agentserver-invocations_1.0.0b2、azure-ai-agentserver-responses_1.0.0b2 の3パッケージです。(GitHub)
すぐに取るべき初動は、依存関係を固定したステージング検証、ログ量とアラート条件の見直し、x-agent-chat-isolation-key の引き継ぎ確認、400/404などのエラー期待値の更新です。特にResponses protocolを使っている場合は、クライアント、API gateway、BFF、ストレージ連携、E2Eテストまで影響範囲を広めに見てください。
まず押さえるべき変更点
今回のbeta waveは、core、invocations、responses が連動して更新されています。単体のパッケージだけを見ると小さな変更に見えますが、実務ではログ設計、トレース、テスト、セキュリティ境界に影響します。
| パッケージ | 対象バージョン | 主な変更 | 最初に確認すること |
|---|---|---|---|
azure-ai-agentserver-core | 2.0.0b2 | 起動時設定ログ、インバウンドHTTPログ、trace-id 抽出、重複コンソールログ修正 | 既存ログとの重複、アラート増加、相関IDの出方 |
azure-ai-agentserver-invocations | 1.0.0b2 | InvocationAgentServerHost のOpenAPI設定ログ、core由来のインバウンドログ | OpenAPI specの設定有無、呼び出しログの粒度 |
azure-ai-agentserver-responses | 1.0.0b2 | handler診断ログ、チャット分離キー、ID検証、Foundry storage logging、SSE replay修正 | 分離キーの引き継ぎ、400/404期待値、SSEとinput_itemsの回帰テスト |
core の InboundRequestLoggingMiddleware は、すべてのインバウンドHTTPリクエストに対して、メソッド、クエリ文字列を除いたパス、ステータスコード、処理時間、x-request-id、x-ms-client-request-id などの相関ヘッダーを記録します。4xx以上はWARNING、未処理例外は500相当のWARNINGとして扱われ、W3C traceparent からの trace-id 抽出も強化されています。(GitHub)
つまり、アップデート後は「ログが増える」だけでなく、「どのログを監視や障害調査の一次情報にするか」を決め直す必要があります。
Azure AI Agent Server SDK for Pythonの3パッケージの役割
Azure AI Agent Server SDK for Pythonは、ホスト基盤とプロトコル実装を分けて理解すると整理しやすくなります。
azure-ai-agentserver-core は、Azure AI Hosted Agentコンテナ向けの基盤ホストフレームワークです。ヘルスプローブ、グレースフルシャットダウン、OpenTelemetry tracing、ASGI servingなど、プロトコルに依存しない部分を担います。Microsoft Learnでは、protocol packagesがこのAgentServerHostを継承してエンドポイントを追加する構成として説明されています。(Microsoft Learn)
azure-ai-agentserver-invocations は、Invocations protocolのエンドポイントを提供するパッケージです。POST /invocations、GET /invocations/{id}、POST /invocations/{id}/cancel、GET /invocations/docs/openapi.json などを扱い、InvocationAgentServerHost を通じてハンドラーを登録します。(Microsoft Learn)
azure-ai-agentserver-responses は、Responses protocolのエンドポイントを提供するパッケージです。レスポンス作成、SSE stream、cancel、delete、replay、input-item listingなど、レスポンスのライフサイクル全体を扱います。(Microsoft Learn)
| 利用シーン | 主に見るパッケージ | 実務上の確認ポイント |
|---|---|---|
| ホスト起動、ヘルスチェック、OpenTelemetry、ASGI | core | /readiness、ログ設定、トレース、シャットダウン |
| シンプルな呼び出し型エージェント | invocations | invoke_handler、OpenAPI spec、invocation ID、session ID |
| Responses API型のエージェント | responses | SSE、cancel、delete、replay、input_items、チャット分離 |
| 複数プロトコルを同じサーバーに載せる構成 | core + protocol packages | ルーティング、ログ重複、middleware、トレース相関 |
1.x利用者はb2の前にパッケージ分割を確認する
今回のb2更新は、直前のアーキテクチャ変更の上に乗っています。azure-ai-agentserver-core 2.0.0b1 では、パッケージが軽量なホスト基盤に再設計され、Responses API関連の型やSSE streamingは azure-ai-agentserver-responses、Invocations関連の型は azure-ai-agentserver-invocations に移動しました。(GitHub)
そのため、1.x系から一気に追う場合は、「b2で壊れた」と判断する前に、2.0.0b1のパッケージ分割と破壊的変更を確認する必要があります。
| 現在の状態 | 先に確認すること | b2で追加確認すること |
|---|---|---|
core 1.xでResponses系を使っている | responses パッケージへの移行、import修正 | Responsesのログ、ID検証、チャット分離 |
旧FoundryCBAgentに依存している | AgentServerHostへの置き換え | 起動ログ、middleware、トレース |
/healthy をヘルスチェックにしている | /readiness への変更 | コンテナ、ロードバランサー、監視設定 |
| OpenTelemetryを任意依存と見ていた | 必須依存として扱う | trace-id、Application Insights、OTLP連携 |
| 複数プロトコルを組み合わせたい | cooperative mixin inheritanceの確認 | ログ、ルート、エラー処理の衝突確認 |
初期リリース時点で、invocations はハンドラー登録、任意のGET/CANCELエンドポイント、OpenAPI spec serving、invocation ID tracking、session correlation、分散トレーシング、構造化ログ、streaming response supportなどを提供していました。(GitHub)
同様に、responses は ResponsesAgentServerHost、Responses protocol endpoints、SSE event stream、ResponseContext、各種execution mode、SSE replay、InMemoryResponseProvider、OpenTelemetry integrationなどを初期機能として提供しています。(GitHub)
core 2.0.0b2の実務ポイント
起動時設定ログで環境差分を見つけやすくなる
core 2.0.0b2 では、AgentServerHost の起動時にINFOレベルの設定ログが出るようになりました。対象には、agent name、version、port、session ID、SSE keep-alive、project endpoint、OTLP endpoint、Application Insightsの設定有無、shutdown timeout、登録プロトコルなどが含まれます。Application Insights connection stringのようなセンシティブ値はログに出さないとされています。(GitHub)
これは、ステージングと本番で環境変数がずれている場合や、コンテナ起動時に想定と違うportで待ち受けている場合の切り分けに役立ちます。
一方で、INFOログをすべてログ基盤へ送っている環境では、デプロイ、スケールアウト、再起動のたびに設定ログが増えます。導入直後は、次の観点を確認してください。
| 確認項目 | 理由 | 対応例 |
|---|---|---|
| 起動ログが何行増えるか | ログ転送料や保存量に影響する | ステージングでデプロイ時のログ量を測る |
| マスキングが期待通りか | 接続先や設定値がログに出るため | 機密値、トークン、connection stringが出ないか確認 |
| Application Insights / OTLP設定が正しいか | トレースが出ない原因を早期に見つけられる | 起動直後のログをデプロイ検証に含める |
| 登録プロトコルが想定通りか | 複数プロトコル構成で設定漏れを見つけやすい | core、responses、invocationsの組み合わせを確認 |
インバウンドHTTPログは監視ルールに影響する
InboundRequestLoggingMiddleware は、AgentServerHost により自動的に組み込まれます。これにより、アプリ側で明示的にmiddlewareを追加しなくても、HTTPリクエストの開始・完了ログが出ます。(GitHub)
ここで注意したいのは、4xx以上がWARNINGとして扱われる点です。API利用者の入力ミス、存在しないIDへのアクセス、チャット分離キー不一致などもWARNINGとして見えるため、従来の「WARNING以上は即インシデント」という運用だとアラートが増える可能性があります。
監視設計では、4xxと5xxを分けて扱うのが現実的です。4xxはクライアント起因やセキュリティ制御による正常な拒否を含むため、件数の急増や特定pathの偏りを監視します。5xxはサーバー側障害の可能性が高いため、短時間でも強めのアラートにする判断ができます。
重複コンソールログ修正はコンテナ運用で効く
core 2.0.0b2 では、root loggerに既存の StreamHandler がある場合にSDK側のconsole logが重複する問題が修正されています。logging.basicConfig() やフレームワーク側の設定で既にハンドラーがある場合でも、SDKが重複追加しにくくなっています。(GitHub)
これは地味ですが、コンテナ運用では重要です。同じログが二重に出ると、ログ転送料、エラー件数、アラート集計、障害調査の読みやすさに影響します。アップデート後は、同じ1リクエストで同一メッセージが重複していないかを確認しましょう。
invocations 1.0.0b2の実務ポイント
azure-ai-agentserver-invocations 1.0.0b2 では、InvocationAgentServerHost がOpenAPI specの設定有無をINFOレベルでログに出すようになりました。また、core由来の InboundRequestLoggingMiddleware が自動的に組み込まれるため、Invocations protocolのHTTPリクエストも一貫した形式で記録されます。(GitHub)
Invocationsを使っているチームは、次の3点を最初に確認すると効率的です。
GET /invocations/docs/openapi.jsonを使う構成で、OpenAPI specの設定有無が期待通りログに出るかPOST /invocations、GET /invocations/{id}、POST /invocations/{id}/cancelのログが既存のアクセスログと重複しすぎないかinvocation_id、session_id、trace-idを使って、1回の呼び出しをログとトレースで追えるか
Invocationsは、比較的シンプルな「呼び出し型」のエージェントに向いています。長時間処理やキャンセル、OpenAPIによる発見可能性を重視する場合は、今回のログ強化により運用時の見通しが良くなります。
ただし、既に独自の構造化ログで invocation_id や session_id を出している場合、SDKログとアプリログの両方に同じ情報が出ることがあります。ログを削るのではなく、役割を分けるのがおすすめです。SDKログはHTTP境界と相関ID、アプリログはビジネス処理やモデル呼び出しの詳細、という切り分けにすると読みやすくなります。
responses 1.0.0b2の実務ポイント
Responses利用者は今回の影響が最も大きい
今回のbeta waveで確認項目が最も多いのは azure-ai-agentserver-responses 1.0.0b2 です。起動時ログ、インバウンドログ、handler-level diagnostic logging、orchestrator handler invocation logging、チャット分離キー、response ID検証、Foundry storage logging、SSE replay、item_reference の解決、エラーコードの仕様準拠など、多数の変更が含まれます。(GitHub)
Responses protocolは、作成、取得、ストリーミング、キャンセル、削除、入力アイテム取得までを扱います。そのため、変更の影響はPythonコードだけでは終わりません。フロントエンド、BFF、API gateway、ストレージ、監視、E2Eテストまで含めて確認する必要があります。
x-agent-chat-isolation-key は最優先で確認する
responses 1.0.0b2 では、レスポンス作成時に x-agent-chat-isolation-key ヘッダーを付けた場合、後続のGET、DELETE、Cancel、InputItemsリクエストでも同じキーが必要になります。キーが不足または不一致の場合、クロスチャット情報漏えいを避けるため、区別しにくい404を返します。作成時にキーがなかったレスポンスでは、この強制は行われません。(GitHub)
実務でよく失敗するのは、作成リクエストと取得リクエストの経路が違うケースです。たとえば、POST /responses はフロントエンドから直接送る一方、GET /responses/{id} はBFFや管理画面から送る構成では、後続リクエストで同じヘッダーを付け忘れる可能性があります。
| シナリオ | 起きやすい問題 | 確認ポイント |
|---|---|---|
フロントエンドがPOST /responsesを送る | 後続GETで分離キーを保持していない | response IDと分離キーを同じライフサイクルで管理する |
| API gatewayを通す | カスタムヘッダーが落ちる | x-agent-chat-isolation-key を転送許可する |
| 管理画面からcancel/deleteする | 管理系リクエストに分離キーがない | 操作対象のchat contextを復元できるようにする |
| 404を自動リトライする | 分離キー不一致を「未作成」と誤判定する | 404の発生条件をログと相関IDで確認する |
簡易検証では、次のように「キーあり作成」「キーなし取得」「同じキーで取得」を分けて確認します。
# 作成時にチャット分離キーを付ける
curl -X POST "$BASE_URL/responses" \
-H "Content-Type: application/json" \
-H "x-agent-chat-isolation-key: chat-a" \
-d '{"input":"hello"}'
# 後続GETでキーを付けない場合、404になることを確認
curl -X GET "$BASE_URL/responses/{response_id}"
# 同じキーを付けた場合、取得できることを確認
curl -X GET "$BASE_URL/responses/{response_id}" \
-H "x-agent-chat-isolation-key: chat-a"このテストは、セキュリティ境界の確認にもなります。マルチテナント、複数会話、ユーザー別履歴を扱うアプリでは、E2Eテストに組み込む価値があります。
response ID検証で400と404の期待値を分ける
responses 1.0.0b2 では、response_id path parameterの形式が不正な場合、ストレージに触れる前にHTTP 400を返すようになりました。previous_response_id も検証対象です。(GitHub)
この変更で落ちやすいのが契約テストです。「存在しないIDなら404」とだけテストしていると、不正な形式のIDでも404を期待してしまいます。b2では、形式が不正なIDは400、形式は正しいが存在しないIDは404、というように分けて考える必要があります。
| テストケース | 期待する扱い |
|---|---|
prefixが違う、短すぎるなど形式が不正なresponse_id | HTTP 400 |
形式は正しいが存在しないresponse_id | HTTP 404 |
previous_response_id が不正 | HTTP 400 |
| 削除済みresponseへのGET | HTTP 404 |
| 削除済みresponseへの2回目のDELETE | HTTP 404 |
また、エラーの code フィールドは、400/404系で "invalid_request_error"、500系で "server_error" など、仕様準拠の値に整理されています。RequestValidationError のデフォルトコードや、terminal stateのresponseをcancelした場合のメッセージも更新されています。(GitHub)
フロントエンドやクライアントSDK側でエラー文字列を直接見て分岐している場合は、ここも更新対象です。可能であれば、表示文言ではなくHTTPステータス、error.type、error.code、paramを使って分岐する設計に寄せると、今後の変更にも強くなります。
SSE replayとinput_itemsは回帰テストに入れる
SSE stream replayでは、レスポンスプロバイダーが ResponseStreamProviderProtocol を実装していない場合でも動作するよう修正されています。たとえば FoundryStorageProvider のような構成で、以前は GET /responses/{id}?stream=true がHTTP 400になり得たケースに対し、ホスト側がインメモリのstream providerをfallbackとして用意するようになりました。(GitHub)
また、POST /responses の入力に item_reference が含まれる場合、永続化前にprovider経由でbatch resolveされるようになりました。以前はinput expansion中に item_reference が落ち、GET /responses/{id}/input_items でinline itemしか返らないケースがありました。(GitHub)
Responsesを使っているなら、最低限次の回帰テストを用意してください。
| 回帰テスト | 目的 |
|---|---|
POST /responses → GET /responses/{id}?stream=true | SSE replayが動くか |
| background + streamの組み合わせ | 接続断後やreplay時の挙動確認 |
item_reference を含む入力 | input_items に期待通り反映されるか |
| Foundry storage利用時の4xx/5xx | エラーが正しくHTTPステータスへマッピングされるか |
| delete後のGET/DELETE | 削除済みリソースが404になるか |
| isolation key不一致 | 情報漏えいを避ける404になるか |
ログと監視で見直すべき設計
今回の更新では、SDK側から出るログが増えます。ここで大切なのは、ログの量を増やすことではなく、障害調査で使う順番を決めることです。
| ログの種類 | b2で得られる情報 | 実務での使い方 |
|---|---|---|
| 起動時設定ログ | agent名、version、port、接続先、OTLP、Application Insights設定有無 | デプロイ直後の設定確認 |
| インバウンドリクエストログ | method、path、status、duration、相関ヘッダー | APIレイテンシ、4xx/5xx、リクエスト追跡 |
| Responses handlerログ | endpoint entry、success、response ID、status、output count | Responses lifecycleの追跡 |
| Orchestrator invocationログ | handler function name、response ID | どのハンドラーが呼ばれたかの確認 |
| Foundry storageログ | storage HTTP call、duration、相関ヘッダー、4xx/5xx | 上流ストレージの遅延や失敗の切り分け |
FoundryStorageLoggingPolicy は、Foundry storageへのHTTP呼び出しについて、method、URI、status code、duration、correlation headersを azure.ai.agentserver loggerで記録します。4xx/5xxではWARNINGへ昇格し、x-request-id、apim-request-id、x-ms-client-request-id、x-ms-request-id などの相関ヘッダーも記録対象です。(GitHub)
監視ダッシュボードでは、次のように分けて見ると実用的です。
| 指標 | 見る理由 | 注意点 |
|---|---|---|
| 総リクエスト数 | デプロイ後のトラフィック変化を見る | SDKログとプロキシログの二重計上に注意 |
| 4xx率 | クライアント起因、ID不正、分離キー不一致を見る | すべてを障害扱いしない |
| 5xx率 | サーバー側障害を検知する | 短時間でも強めに監視する |
| p95/p99 latency | 体感遅延やストレージ遅延を見る | path別、endpoint別に分ける |
| trace-id有無 | 分散トレースとログの接続を見る | gatewayがtraceparentを落としていないか確認 |
アップデート前の初動チェックリスト
Azure AI Agent Server SDK for Pythonのbeta waveを検証する場合、最初にやるべきことは依存関係の棚卸しです。requirements.txtだけでなく、constraints.txt、poetry.lock、uv.lock、Dockerfile、CIキャッシュ、ベースイメージのpip layerまで確認してください。
pip freeze | grep -E 'azure-ai-agentserver-(core|invocations|responses)'検証環境では、対象バージョンを明示的に固定します。
azure-ai-agentserver-core==2.0.0b2
azure-ai-agentserver-invocations==1.0.0b2
azure-ai-agentserver-responses==1.0.0b2ただし、実際に固定するパッケージは使っているプロトコルに合わせます。Responsesだけを使う構成で、無理にInvocationsを追加する必要はありません。Invocationsパッケージはcoreを依存関係として自動的にインストールすると説明されていますが、検証時はロックファイル上で実際に入っているバージョンを確認する方が安全です。(Microsoft Learn)
ステージングで確認する順番
| 順番 | 確認内容 | 合格ライン |
| -: | ———————- | ———————————————- |
| 1 | パッケージバージョン | b2対象が明示的に入っている |
| 2 | 起動ログ | 想定したport、endpoint、protocol、tracing設定が出る |
| 3 | ヘルスチェック | /readiness が期待通り返る |
| 4 | インバウンドログ | method、path、status、duration、相関IDが出る |
| 5 | Invocations smoke test | POST /invocations と必要なGET/CANCELが動く |
| 6 | Responses smoke test | create、get、stream、cancel、delete、input_itemsが動く |
| 7 | チャット分離 | isolation keyあり/なし/不一致の挙動を確認する |
| 8 | エラー期待値 | 不正IDは400、存在しないIDは404などを確認する |
| 9 | SSE replay | ?stream=true の再取得が期待通り動く |
| 10 | 監視ルール | 4xx WARNING増加で誤検知しない |
失敗しやすいポイント
ベータ版をワイルドカードで上げる
>= や --pre を広く使っていると、意図したb2ではなく、より新しいプレビュー版を取り込む可能性があります。2026年4月20日時点のb2更新を検証するなら、まずは対象バージョンを固定して比較してください。
悪い例です。
azure-ai-agentserver-responses>=1.0.0b2検証で使いやすい例です。
azure-ai-agentserver-responses==1.0.0b2404をすべて「存在しない」と扱う
Responsesのチャット分離では、分離キーの不足や不一致でも404が返ります。これは情報漏えいを避けるための挙動です。クライアント側で「404なら新規作成すればよい」と単純に処理していると、分離キーの引き継ぎ漏れを見逃します。
404が増えた場合は、response ID、path、相関ID、クライアント種別、分離キーの有無を組み合わせて原因を見てください。
カスタムヘッダーをgatewayで落とす
x-agent-chat-isolation-key、x-request-id、x-ms-client-request-id、traceparent などのヘッダーは、セキュリティ、ログ、トレースに関わります。API gateway、ロードバランサー、BFF、リバースプロキシがこれらを落とすと、SDK側の改善を活かせません。
特にグローバルチームでフロントエンドとバックエンドの担当が分かれている場合、ヘッダー仕様をAPI contractに明記しておくとトラブルを防げます。
ログ増加を障害と誤認する
今回の更新後、WARNINGログが増えることがあります。ただし、4xxのWARNINGは必ずしもサーバー障害ではありません。不正なID、削除済みリソース、分離キー不一致、クライアント入力ミスなども含まれます。
初回導入では、いきなり本番アラートへ接続せず、ステージングで1日分のログを見てから、4xxと5xxの閾値を分けるのが安全です。
導入判断の目安
今回のbeta waveをすぐ検証すべきかどうかは、利用状況によって変わります。
| 状況 | 判断 |
|---|---|
| Azure AI Agent Server SDK for PythonをPoCで使っている | 早めにb2を試し、ログとテストを更新する |
Responses protocolでSSEやinput_itemsを使っている | 優先度高。SSE replayとitem_referenceの回帰テストを行う |
| マルチチャット、マルチテナント構成 | 優先度高。x-agent-chat-isolation-key の設計を確認する |
| Invocationsだけを使っている | ログとOpenAPI設定の確認を中心に進める |
| 本番相当のワークロードで使っている | betaであることを前提に、ステージング、ロールバック、監視調整を必須にする |
| まだ1.x系の設計を使っている | b2より前に2.0.0b1のパッケージ分割を確認する |
ベータ版SDKは変更が続く可能性があります。実務では、「最新版を入れる」よりも「検証したバージョンを固定し、ログ・テスト・監視の差分を把握する」ことが重要です。
次に取るべき行動
Coordinated Azure AI Agent Server Python beta wave updates core, invocations, and responses packages を確認する際は、まず利用中のプロトコルを切り分けてください。coreだけのホスト基盤なのか、invocations中心なのか、responsesでSSEやストレージ連携まで使っているのかで、見るべき場所が変わります。
最初の作業は、次の4つで十分です。
- 現在の
azure-ai-agentserver-*パッケージバージョンを棚卸しする - ステージングでb2対象バージョンを固定して起動する
- ログ、相関ID、4xx/5xx、trace-idの出方を確認する
- Responses利用時は、チャット分離、ID検証、SSE replay、
input_itemsを回帰テストに入れる
今回の更新は、アプリの見た目を大きく変えるものではありません。しかし、運用で「何が起きたか」を追う力を高め、チャット間の安全性やエラー処理の一貫性を改善する更新です。Azure AI Agent Server SDK for Pythonを継続利用するなら、コード変更だけでなく、監視、テスト、ヘッダー設計まで含めて確認するのが最短ルートです。
コメント