Azure · ankitbko · Mar 17, 2026 · Mar 17, 2026 · Mar 18, 2026 · Mar 19, 2026
@@ -23,12 +23,14 @@
 from ._base import AgentServerHost
 from ._config import AgentConfig
 from ._errors import create_error_response
+from ._server_version import build_server_version
 from ._tracing import end_span, flush_spans, record_error, trace_stream
 from ._version import VERSION
 
 __all__ = [
     "AgentConfig",
     "AgentServerHost",
+    "build_server_version",
     "create_error_response",
     "end_span",
     "flush_spans",

@@ -18,30 +18,33 @@
 from starlette.routing import Route
 
 from . import _config, _tracing
+from ._server_version import build_server_version
 from ._version import VERSION as _CORE_VERSION
 
 logger = logging.getLogger("azure.ai.agentserver")
 
 # Pre-built health-check response to avoid per-request allocation.
 _HEALTHY_BODY = b'{"status":"healthy"}'
 
-# Server identity header per spec: {sdk}/{version} (python/{runtime})
-_PLATFORM_SERVER_VALUE = (
-    f"azure-ai-agentserver-core/{_CORE_VERSION} "
-    f"(python/{sys.version_info.major}.{sys.version_info.minor})"
-)
-
 # Sentinel attribute name set on the console handler to prevent adding duplicates
 # across multiple AgentServerHost instantiations.
 _CONSOLE_HANDLER_ATTR = "_agentserver_console"
 
 
 class _PlatformHeaderMiddleware(BaseHTTPMiddleware):
-    """Middleware that adds x-platform-server identity header to all responses."""
+    """Middleware that adds ``x-platform-server`` version header to all responses.
+
+    Takes a callable that returns the current header value so protocol
+    hosts can register additional segments after construction.
+    """
+
+    def __init__(self, app: Any, *, get_server_version: Callable[[], str]) -> None:  # type: ignore[override]
+        super().__init__(app)
+        self._get_server_version = get_server_version
 
     async def dispatch(self, request: Request, call_next):  # type: ignore[no-untyped-def, override]
         response = await call_next(request)
-        response.headers["x-platform-server"] = _PLATFORM_SERVER_VALUE
+        response.headers["x-platform-server"] = self._get_server_version()
         return response
 
 
@@ -103,6 +106,14 @@ def __init__(
         # Shutdown handler slot (server-level lifecycle) -------------------
         self._shutdown_fn: Optional[Callable[[], Awaitable[None]]] = None
 
+        # Server version segments for the x-platform-server header.
+        # Protocol packages call register_server_version() to add their
+        # own portion; the middleware joins them at response time.
+        self._server_version_segments: list[str] = []
+        self.register_server_version(
+            build_server_version("azure-ai-agentserver-core", _CORE_VERSION)
+        )
+
         # Logging ----------------------------------------------------------
         resolved_level = _config.resolve_log_level(log_level)
         logger.setLevel(resolved_level)
@@ -171,10 +182,46 @@ async def _lifespan(_app: Starlette) -> AsyncGenerator[None, None]:  # noqa: RUF
         super().__init__(
             routes=all_routes,
             lifespan=_lifespan,
-            middleware=[Middleware(_PlatformHeaderMiddleware)],
+            middleware=[
+                Middleware(_PlatformHeaderMiddleware, get_server_version=self._build_server_version),
+            ],
             **kwargs,
         )
 
+    # ------------------------------------------------------------------
+    # Server version (x-platform-server header)
+    # ------------------------------------------------------------------
+
+    def register_server_version(self, version_segment: str) -> None:
+        """Register a version segment for the ``x-platform-server`` header.
+
+        Protocol packages (e.g. responses, invocations) call this in their
+        ``__init__`` to add their own portion.  Handler developers can also
+        call it to append a custom version string.  Duplicates are ignored.
+
+        Use :func:`~azure.ai.agentserver.core.build_server_version` to
+        build a standard segment::
+
+            from azure.ai.agentserver.core import build_server_version
+
+            app.register_server_version(
+                build_server_version("my-library", "2.0.0")
+            )
+
+        :param version_segment: The version string to register.
+        :type version_segment: str
+        :raises ValueError: If *version_segment* is empty or whitespace-only.
+        """
+        if not version_segment or not version_segment.strip():
+            raise ValueError("Version segment must not be empty.")
+        normalized = version_segment.strip()
+        if normalized not in self._server_version_segments:
+            self._server_version_segments.append(normalized)
+
+    def _build_server_version(self) -> str:
+        """Join all registered segments into the header value."""
+        return " ".join(self._server_version_segments)
+
     # ------------------------------------------------------------------
     # Tracing (for protocol subclasses)
     # ------------------------------------------------------------------

@@ -32,7 +32,7 @@
 _ENV_SSE_KEEPALIVE_INTERVAL = "SSE_KEEPALIVE_INTERVAL"
 
 _DEFAULT_PORT = 8088
-_DEFAULT_SSE_KEEPALIVE_INTERVAL = 15
+_DEFAULT_SSE_KEEPALIVE_INTERVAL = 0
 
 
 # ======================================================================
@@ -292,7 +292,7 @@ def resolve_sse_keepalive_interval(interval: Optional[int] = None) -> int:
     """Resolve the SSE keep-alive interval from argument, env var, or default.
 
     Resolution order: explicit *interval* → ``SSE_KEEPALIVE_INTERVAL`` env var
-    → ``15`` (seconds).  A value of ``0`` disables keep-alive.
+    → ``0`` (seconds).  A value of ``0`` disables keep-alive.
 
     :param interval: Explicitly requested interval in seconds, or None.
     :type interval: Optional[int]

@@ -0,0 +1,33 @@
+# ---------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# ---------------------------------------------------------
+"""Utility for building ``x-platform-server`` version strings."""
+
+from __future__ import annotations
+
+import sys
+
+
+def build_server_version(sdk_name: str, version: str) -> str:
+    """Build a standard version segment for the ``x-platform-server`` header.
+
+    Format: ``{sdk_name}/{version} (python/{major}.{minor})``
+
+    Protocol packages call this during host initialisation and pass the
+    result to :meth:`AgentServerHost.register_server_version`.
+
+    :param sdk_name: The SDK identifier
+        (e.g., ``"azure-ai-agentserver-responses"``).
+    :type sdk_name: str
+    :param version: The package version string (e.g., ``"1.0.0b1"``).
+    :type version: str
+    :returns: A formatted version string.
+    :rtype: str
+    :raises ValueError: If *sdk_name* or *version* is empty.
+    """
+    if not sdk_name or not sdk_name.strip():
+        raise ValueError("sdk_name must not be empty.")
+    if not version or not version.strip():
+        raise ValueError("version must not be empty.")
+    runtime = f"python/{sys.version_info.major}.{sys.version_info.minor}"
+    return f"{sdk_name}/{version} ({runtime})"
@@ -0,0 +1,19 @@
+# Release History
+
+## 1.0.0b1 (Unreleased)
+
+### Features Added
+
+- Initial release of `azure-ai-agentserver-responses`.
+- `ResponsesAgentServerHost` — Starlette-based host with Responses protocol endpoints (`POST /responses`, `GET /responses/{id}`, `POST /responses/{id}/cancel`, `DELETE /responses/{id}`, `GET /responses/{id}/input_items`).
+- `TextResponse` — high-level convenience for text-only responses with automatic SSE lifecycle (`create_text` and `create_text_stream` modes).
+- `ResponseEventStream` — low-level builder API for emitting SSE events with full control over output items (message, function call, reasoning, file search, web search, code interpreter, image gen, MCP, custom tool).
+- Convenience generators (`output_item_message()`, `output_item_function_call()`, `output_item_reasoning_item()`) and async streaming variants (`aoutput_item_message()`, etc.) for common patterns.
+- `ResponseContext` providing `response_id`, conversation history loading, input item access via `get_input_items()` (returns `Item` subtypes), `get_input_text()` convenience for extracting text content, isolation context, and client headers.
+- `ResponsesServerOptions` for configuring default model, SSE keep-alive, shutdown grace period, and other runtime options.
+- Support for all execution modes: default (synchronous), streaming (SSE), background, and streaming + background.
+- Automatic SSE event replay for previously streamed responses via `?stream=true`.
+- Cooperative cancellation via `asyncio.Event` and graceful shutdown integration.
+- `InMemoryResponseProvider` as the default in-process state store.
+- `ResponseProviderProtocol` and `ResponseStreamProviderProtocol` for custom storage implementations.
+- Built-in distributed tracing with OpenTelemetry integration.
@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,9 @@
+include *.md
+include LICENSE
+recursive-include tests *.py
+recursive-include samples *.py *.md
+recursive-include doc *.rst *.md
+include azure/__init__.py
+include azure/ai/__init__.py
+include azure/ai/agentserver/__init__.py
+include azure/ai/agentserver/responses/py.typed