Azure · Shivakishore14 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 15, 2026
@@ -4,6 +4,7 @@
 
 ### Other Changes
 
+- Cleaned up the public API surface by moving validation-only error helpers to a private implementation module and renaming runtime terminal/replay helpers as private.
 - Bumped the minimum `azure-ai-agentserver-core` dependency to `>=2.0.0b10`, which adds an opt-in gate for resilient-task startup recovery. The resilient Responses samples now call `set_resilient_tasks_enabled(True)` to explicitly opt in, mirroring the invocations resilient samples.
 
 ## 2.0.0b0 (2026-07-29)

@@ -1,15 +1,9 @@
 ```py
 namespace azure.ai.agentserver.responses
 
-    def azure.ai.agentserver.responses.get_conversation_id(request: CreateResponse | ResponseObject) -> Optional[str]: ...
-
-
     def azure.ai.agentserver.responses.get_input_expanded(request: CreateResponse) -> list[Item]: ...
 
 
-    def azure.ai.agentserver.responses.to_output_item(item: Item, response_id: str | None = None) -> OutputItem | None: ...
-
-
     class azure.ai.agentserver.responses.ConversationChainMetadataNamespace(Protocol): implements Collection 
 
         def __call__(self, name: Optional[str] = None) -> ConversationChainMetadataNamespace: ...
@@ -5927,108 +5921,8 @@ namespace azure.ai.agentserver.responses.models
         type: Literal[workflow_action]
 
 
-namespace azure.ai.agentserver.responses.models.errors
-
-    class azure.ai.agentserver.responses.models.errors.ApiErrorResponse(TypedDict, total=False):
-        key "error": Required[Error]
-        error: Error
-
-
-    class azure.ai.agentserver.responses.models.errors.Error(TypedDict, total=False):
-        key "code": Required[Optional[str]]
-        key "message": Required[str]
-        key "param": Optional[str]
-        key "type": str
-        additionalInfo: dict[str, Any]
-        additional_info: dict[str, Any]
-        code: str
-        debugInfo: dict[str, Any]
-        debug_info: dict[str, Any]
-        details: list[Error]
-        message: str
-        param: str
-        type: str
-
-
-    class azure.ai.agentserver.responses.models.errors.RequestValidationError(ValueError):
-
-        def __init__(
-                self, 
-                message: str, 
-                *, 
-                code: str = "invalid_request_error", 
-                debug_info: dict[str, Any] | None = ..., 
-                details: list[dict[str, str]] | None = ..., 
-                error_type: str = "invalid_request_error", 
-                param: str | None = ...
-            ) -> None: ...
-
-        def to_api_error_response(self) -> ApiErrorResponse: ...
-
-        def to_error(self) -> Error: ...
-
-
 namespace azure.ai.agentserver.responses.models.runtime
 
-    def azure.ai.agentserver.responses.models.runtime.apply_cancelled_terminal(base: Mapping[str, Any]) -> dict[str, Any]: ...
-
-
-    def azure.ai.agentserver.responses.models.runtime.apply_failed_terminal(
-            base: Mapping[str, Any], 
-            *, 
-            error: dict[str, Any]
-        ) -> dict[str, Any]: ...
-
-
-    def azure.ai.agentserver.responses.models.runtime.build_cancelled_response(
-            response_id: str, 
-            agent_reference: AgentReference | dict[str, Any], 
-            model: str | None, 
-            created_at: datetime | None = None
-        ) -> ResponseObject: ...
-
-
-    def azure.ai.agentserver.responses.models.runtime.build_failed_response(
-            response_id: str, 
-            agent_reference: AgentReference | dict[str, Any], 
-            model: str | None, 
-            created_at: datetime | None = None, 
-            error_message: str = "An internal server error occurred.", 
-            error_code: str = "server_error"
-        ) -> ResponseObject: ...
-
-
-    def azure.ai.agentserver.responses.models.runtime.resolve_cancelled_response(
-            base: Mapping[str, Any] | None, 
-            response_id: str, 
-            agent_reference: AgentReference | dict[str, Any], 
-            model: str | None, 
-            *, 
-            created_at: datetime | None = ...
-        ) -> ResponseObject: ...
-
-
-    def azure.ai.agentserver.responses.models.runtime.resolve_failed_response(
-            base: Mapping[str, Any] | None, 
-            response_id: str, 
-            agent_reference: AgentReference | dict[str, Any], 
-            model: str | None, 
-            *, 
-            created_at: datetime | None = ..., 
-            error_code: str = "server_error", 
-            error_message: str = _DEFAULT_FAILED_ERROR_MESSAGE
-        ) -> ResponseObject: ...
-
-
-    class azure.ai.agentserver.responses.models.runtime.AgentReference(TypedDict, total=False):
-        key "name": Required[str]
-        key "type": Required[Literal["agent_reference"]]
-        key "version": str
-        name: str
-        type: Literal[agent_reference]
-        version: str
-
-
     class azure.ai.agentserver.responses.models.runtime.ResponseExecution:
         property agent_reference: AgentReference | dict[str, Any]    # Read-only
         property is_terminal: bool    # Read-only
@@ -6084,78 +5978,6 @@ namespace azure.ai.agentserver.responses.models.runtime
             ) -> None: ...
 
 
-    class azure.ai.agentserver.responses.models.runtime.ResponseObject(TypedDict, total=False):
-        key "agent_reference": Required[Optional[AgentReference]]
-        key "background": Optional[bool]
-        key "completed_at": Optional[int]
-        key "conversation": Optional[ConversationReference]
-        key "created_at": Required[int]
-        key "error": Required[Optional[ResponseErrorInfo]]
-        key "id": Required[str]
-        key "incomplete_details": Required[Optional[ResponseIncompleteDetails]]
-        key "instructions": Required[Optional[Union[str, list[Item]]]]
-        key "max_output_tokens": Optional[int]
-        key "max_tool_calls": Optional[int]
-        key "metadata": Optional[Metadata]
-        key "model": str
-        key "moderation": Optional[Moderation]
-        key "object": Required[Literal["response"]]
-        key "output": Required[list[OutputItem]]
-        key "output_text": Optional[str]
-        key "parallel_tool_calls": Required[bool]
-        key "previous_response_id": Optional[str]
-        key "prompt": ForwardRef('Prompt', module='types')
-        key "prompt_cache_key": str
-        key "prompt_cache_retention": Optional[Literal["in_memory", "24h"]]
-        key "reasoning": Optional[Reasoning]
-        key "safety_identifier": str
-        key "service_tier": Optional[Literal["auto", "default", "flex", "scale", "priority"]]
-        key "status": Literal["completed", "failed", "in_progress", "cancelled", "queued", "incomplete"]
-        key "temperature": Optional[float]
-        key "text": ForwardRef('ResponseTextParam', module='types')
-        key "tool_choice": Union[Literal["none", "auto", "required"], ToolChoiceParam]
-        key "top_logprobs": Optional[int]
-        key "top_p": Optional[float]
-        key "truncation": Optional[Literal["auto", "disabled"]]
-        key "usage": ForwardRef('ResponseUsage', module='types')
-        key "user": str
-        agent_reference: AgentReference
-        background: bool
-        completed_at: int
-        conversation: ConversationReference
-        created_at: int
-        error: ResponseErrorInfo
-        id: str
-        incomplete_details: ResponseIncompleteDetails
-        instructions: Union[str, list[Item]]
-        max_output_tokens: int
-        max_tool_calls: int
-        metadata: Metadata
-        model: str
-        moderation: Moderation
-        object: Literal[response]
-        output: list[OutputItem]
-        output_text: str
-        parallel_tool_calls: bool
-        previous_response_id: str
-        prompt: Prompt
-        prompt_cache_key: str
-        prompt_cache_retention: Literal[in_memory, 24h]
-        reasoning: Reasoning
-        safety_identifier: str
-        service_tier: Literal[auto, default, flex, scale, priority]
-        status: Literal[completed, failed, in_progress, cancelled, queued, incomplete]
-        temperature: float
-        text: ResponseTextParam
-        tool_choice: Union[ToolChoiceOptions, ToolChoiceParam]
-        tools: list[Tool]
-        top_logprobs: int
-        top_p: float
-        truncation: Literal[auto, disabled]
-        usage: ResponseUsage
-        user: str
-
-
     class azure.ai.agentserver.responses.models.runtime.StreamEventRecord:
         property terminal: bool    # Read-only
 
@@ -6176,19 +5998,6 @@ namespace azure.ai.agentserver.responses.models.runtime
             ) -> StreamEventRecord: ...
 
 
-    class azure.ai.agentserver.responses.models.runtime.StreamReplayState:
-        property terminal_event_seen: bool    # Read-only
-
-        def __init__(
-                self, 
-                *, 
-                events: list[StreamEventRecord] | None = ..., 
-                response_id: str
-            ) -> None: ...
-
-        def append(self, event: StreamEventRecord) -> None: ...
-
-
 namespace azure.ai.agentserver.responses.store
 
     class azure.ai.agentserver.responses.store.ResponseAlreadyExistsError(Exception):

@@ -1,3 +1,3 @@
-apiMdSha256: 2c3ff121746e6028ece71257bcd47d7421233e6f92f2d3f6612a03a5ca34735a
+apiMdSha256: bf36559af5d6dc108cd68fc723cdbc31635cfe70b6439382f8a3d5b3282dd1a4
 parserVersion: 0.3.30
-pythonVersion: 3.12.10
+pythonVersion: 3.11.15
@@ -18,9 +18,7 @@
 from .hosting._routing import ResponsesAgentServerHost
 from .models import CreateResponse, ResponseObject
 from .models._helpers import (
-    get_conversation_id,
     get_input_expanded,
-    to_output_item,
 )
 from .store._base import ResponseProviderProtocol
 from .store._file import FileResponseStore
@@ -59,7 +57,5 @@
     "TextResponse",
     "CreateResponse",
     "ResponseObject",
-    "get_conversation_id",
     "get_input_expanded",
-    "to_output_item",
 ]
@@ -56,8 +56,8 @@
 from ..models.runtime import (
     ResponseExecution,
     ResponseModeFlags,
-    resolve_cancelled_response,
-    resolve_failed_response,
+    _resolve_cancelled_response,
+    _resolve_failed_response,
 )
 from ..store._base import ResponseProviderProtocol, ResponseStoreCorruptionError
 from ..store._foundry_errors import FoundryApiError, FoundryBadRequestError, FoundryResourceNotFoundError
@@ -1552,7 +1552,7 @@ async def handle_cancel(self, request: Request) -> Response:
         if terminal_error is not None:
             if record.status == "cancelled":
                 record.set_response_snapshot(
-                    resolve_cancelled_response(
+                    _resolve_cancelled_response(
                         record.response, record.response_id, record.agent_reference, record.model
                     )
                 )
@@ -1581,7 +1581,7 @@ async def handle_cancel(self, request: Request) -> Response:
 
         # Set cancelled snapshot and transition
         record.set_response_snapshot(
-            resolve_cancelled_response(record.response, record.response_id, record.agent_reference, record.model)
+            _resolve_cancelled_response(record.response, record.response_id, record.agent_reference, record.model)
         )
         # Stamp mode flags so the provider fallback can enforce B1/B2 checks
         # after eager eviction removes the in-memory record.
@@ -1836,7 +1836,7 @@ async def handle_shutdown(self) -> None:
                 # Leave in current state — will be re-entered on restart.
                 continue
             # Non-resilient or foreground: best-effort mark failed.
-            failed_payload = resolve_failed_response(
+            failed_payload = _resolve_failed_response(
                 record.response, record.response_id, record.agent_reference, record.model
             )
             record.set_response_snapshot(failed_payload)

@@ -41,18 +41,10 @@
     ResponseExecution,
     ResponseModeFlags,
     ResponseStatus,
-)
-from ..models.runtime import (
-    apply_cancelled_terminal as _apply_cancelled_terminal,
-)
-from ..models.runtime import (
-    apply_failed_terminal as _apply_failed_terminal,
-)
-from ..models.runtime import (
-    resolve_cancelled_response as _resolve_cancelled_response,
-)
-from ..models.runtime import (
-    resolve_failed_response as _resolve_failed_response,
+    _apply_cancelled_terminal,
+    _apply_failed_terminal,
+    _resolve_cancelled_response,
+    _resolve_failed_response,
 )
 from ..store._base import ResponseAlreadyExistsError, ResponseProviderProtocol
 from ..streaming._checkpoint import ResponseCheckpointEvent

@@ -13,7 +13,7 @@
 from ..models import AgentReference, CreateResponse
 
 from .._id_generator import IdGenerator
-from ..models.errors import RequestValidationError
+from ..models._errors import RequestValidationError
 
 _X_AGENT_RESPONSE_ID_HEADER = "x-agent-response-id"
 

@@ -191,14 +191,14 @@ def _overlay_failed_terminal(
     :returns: A copy of the snapshot transitioned to ``failed``.
     :rtype: ResponseObject
     """
-    from ..models.runtime import apply_failed_terminal  # pylint: disable=import-outside-toplevel
+    from ..models.runtime import _apply_failed_terminal  # pylint: disable=import-outside-toplevel
     from ..models._generated import ResponseObject  # pylint: disable=import-outside-toplevel
 
     error = {
         "code": "server_error",
         "message": message if message is not None else _server_error_message(shutdown_reason),
     }
-    return cast(ResponseObject, apply_failed_terminal(snapshot, error=error))
+    return cast(ResponseObject, _apply_failed_terminal(snapshot, error=error))
 
 
 # (Spec 033 §3.1) Process-local cache of typed :class:`RuntimeRefs` (record,

@@ -17,7 +17,7 @@
 from .._id_generator import IdGenerator
 from .._options import ResponsesServerOptions
 from ..models import ApiErrorResponse, CreateResponse
-from ..models.errors import RequestValidationError
+from ..models._errors import RequestValidationError
 from ..models._validators import (
     validate_create_response_payload,
 )

@@ -1,6 +1,6 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT license.
-"""Error model types for request validation failures."""
+"""Internal error model helpers for request validation failures."""
 
 from __future__ import annotations