Azure/azure-sdk-for-python azure-ai-agentserver-invocations_1.0.0b4

on GitHub

1.0.0b4 (2026-05-21)

Features Added

• Error source classification headers: All HTTP error responses now include x-platform-error-source with a value of user, platform, or upstream to indicate which component caused the error. Developer handler exceptions and missing handler registrations are classified as upstream. Exceptions tagged with the platform error tag are classified as platform and additionally include x-platform-error-detail with truncated exception details (max 2048 characters) for diagnostics.
• WebSocket protocol support — InvocationAgentServerHost now hosts /invocations_ws alongside POST /invocations. Register the handler with the new @app.ws_handler decorator. The route is registered lazily on first decoration, so hosts without a registered handler return HTTP 404.
• WebSocket Ping/Pong keep-alive — disabled by default; enable by setting the WS_KEEPALIVE_INTERVAL env var (auto-injected by AgentService into hosted-agent containers; surfaced on app.config.ws_ping_interval in azure-ai-agentserver-core>=2.0.0b4). 0 (or unset) disables keep-alive. Wired through to Hypercorn's websocket_ping_interval by AgentServerHost._build_hypercorn_config.
• WebSocket telemetry — structured close-event log line carrying azure.ai.agentserver.invocations_ws.session_id, close_code, and duration_ms (via the standard logging extra dict). Session ID honours the FOUNDRY_AGENT_SESSION_ID env var for HTTP/WS correlation.
• New samples: samples/ws_invoke_agent/ (echo) and samples/ws_bidirectional_streaming_agent/ (concurrent token streaming with cancel/bye control messages).

Breaking Changes

• Removed the automatic invoke_agent server span that was created on each /invocations request. Trace context propagation is now handled by the core TraceContextMiddleware, and user-created spans inside handlers are correctly parented without framework-generated spans.
• Removed _safe_set_attrs and _wrap_streaming_response internal helpers (no longer needed without framework-level span management).

Other Changes

• Platform header name constants (e.g. x-platform-error-source, x-platform-error-detail) are now imported from azure-ai-agentserver-core (_platform_headers module) instead of being defined locally. Error source classification helpers remain internal to this package.
• Simplified request handling: baggage entries (invocation_id, session_id) are still set on each request, but span creation and lifecycle management are left to downstream frameworks.