[agentserver-responses] Harden response model, type safety, and builder API (#46302)

* Always include model field in response payload

Default model to empty string when not provided in the request,
ensuring the field is always present in the response payload.
The OpenAI SDK requires model to be present to deserialize the
response object.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add e2e tests for model field always present in response

Address PR review feedback: add contract tests verifying the model
field is present in the response payload when omitted from the request,
for both sync (stream=False) and streaming (stream=True) modes.

* fix: DELETE response returns object='response' instead of 'response.deleted'

The OpenAI spec returns {id, object: 'response', deleted: true} for
DELETE /responses/{id}.  Our handler was returning 'response.deleted'
which doesn't match.  Fixed the handler and updated all 5 test
assertions.

* fix: stamp agent_session_id and conversation_id on to_snapshot fallback

ResponseExecution now carries agent_session_id and conversation_id so
that _RuntimeState.to_snapshot can forcibly stamp them (S-038/S-040)
on both the response.as_dict() path and the minimal fallback dict.
All four orchestrator ResponseExecution creation sites pass both
fields from the execution context.

* fix: remove output:list override breaking get_history deserialization

The manual _patch.py override of ResponseObject.output erased the
element type (list instead of list[OutputItem]), preventing the model
framework from deserializing nested dicts into OutputItem instances.
This caused get_history to return plain dicts instead of typed models.

Changes:
- Remove output:list override; use generated list[OutputItem]
- Remove ToolChoiceAllowed override (generated type is identical)
- Move Sphinx docstring fixes into models_patch.py shim so
  make generate-models preserves them instead of overwriting
- Accept emitter upgrade to model_base.py (XML refactor)
- Regenerate _validators.py from current TypeSpec sources

* fix: use polymorphic _deserialize for OutputItem subtypes + contract type tests

- Fix track_completed_output_item to use OutputItem._deserialize(dict, [])
  instead of OutputItem(dict) so response.output contains proper
  discriminated subtypes (OutputItemMessage, OutputItemFunctionToolCall,
  etc.) instead of base OutputItem instances. This ensures handler devs
  can use isinstance() and attribute access on output items.

- Add test_public_contract_types.py with 22 tests covering every public
  handler/consumer surface for type fidelity:
  * context.request → CreateResponse
  * context.get_input_items() → Item subtypes
  * context.get_input_text() → str
  * context.get_history() → OutputItem subtypes (first-ever coverage)
  * stream.response → ResponseObject
  * stream.response.output → OutputItem subtypes
  * Builder emit_* → ResponseStreamEvent subtypes
  * Generator convenience → ResponseStreamEvent subtypes
  * InMemoryProvider round-trip preserves subtypes

- Add isinstance assertions to existing tests in test_builders.py,
  test_event_stream_generators.py, and test_response_event_stream_builder.py

* feat: deterministic session ID derivation from conversational context

Replace random UUID fallback for agent_session_id with deterministic
SHA-256 derivation matching .NET SessionIdDerivation logic:

Priority chain:
1. Explicit agent_session_id from payload (unchanged)
2. Platform env FOUNDRY_AGENT_SESSION_ID (unchanged)
3. Deterministic: SHA256(agent_name:agent_version:partition_hint)
   where partition_hint is extracted from conversation_id or
   previous_response_id via IdGenerator.extract_partition_key
4. Random 63-char lowercase hex (one-shot, no conversational context)

This ensures session affinity: the same conversation + agent identity
always resolves to the same session ID, enabling stateful backends to
route consistently without requiring explicit session IDs.

New functions in _request_parsing.py:
- derive_session_id() — public deterministic derivation
- _compute_hex_hash() — SHA-256 → 63-char hex
- _generate_random_hex() — os.urandom fallback
- _extract_agent_identity() — name/version from agent_reference

Updated _resolve_session_id() signature to accept agent_reference.
Updated call site in _endpoint_handler.py to pass agent_reference.
Updated all tests (unit + contract) from UUID to 63-char hex format.
Added 14 new derivation tests covering determinism, agent isolation,
version isolation, priority, and non-standard ID formats.

* feat: strongly-typed return types for all emit_* builder methods

Port .NET pattern: every emit_* method now returns its specific event
subtype (e.g. ResponseCreatedEvent, ResponseOutputItemAddedEvent) via
typing.cast() instead of the base ResponseStreamEvent.

Covers all builders:
- ResponseEventStream: 6 lifecycle methods
- OutputItemBuilder / BaseOutputItemBuilder: emit_added, emit_done
- OutputItemMessageBuilder, TextContentBuilder, RefusalContentBuilder
- FunctionCallBuilder, FunctionCallOutputBuilder
- ReasoningSummaryPartBuilder, ReasoningItemBuilder
- FileSearchCall, WebSearchCall, CodeInterpreter, ImageGen,
  McpCall, McpListTools, CustomToolCall builders

Adds test_emit_return_types.py with 70 isinstance assertions covering
every public emit_* method across all 16 builder classes.

* refactor: tighten OutputItemBuilder.emit_added/emit_done to accept OutputItem only

Remove dict[str, Any] from the public signature — all item types are
generated models. Internal callers use _emit_added/_emit_done directly.

Also: fix handler guide (emit_failed/emit_incomplete kwargs, request=
pattern), revert CHANGELOG to initial-release form, remove session ID
derivation docs (internal detail).

* refactor: tighten all public API parameters from dict to generated model types

- ResponseEventStream constructor: agent_reference, request, response now
  accept only their respective model types (no dict[str, Any])
- Terminal methods (emit_completed/failed/incomplete): usage accepts only
  ResponseUsage (no dict[str, Any])
- Convenience generators (output_item_computer_call, _computer_call_output,
  _local_shell_call, _function_shell_call, _function_shell_call_output,
  _apply_patch_call): all action/output/environment params accept only their
  respective generated model types (no dict[str, Any])
- Async mirrors: same tightening as sync counterparts
- emit_annotation_added: annotation accepts only Annotation (no dict)
- _set_terminal_fields: usage tightened
- Internal _build_events: coerce dict→AgentReference before passing to
  ResponseEventStream
- Tests updated to use model constructors instead of raw dicts
- Docs updated to show ResponseUsage model usage

* refactor: internalize escape-hatch methods and tighten remaining list[Any] types

- emit_event → _emit_event: internal only, all callers are sibling
  emit_* methods and _builders subpackage
- with_output_item_defaults → _with_output_item_defaults: internal only,
  called only by _builders._base
- validate_response_event_stream → _validate_response_event_stream:
  internal only, called only by _normalize_lifecycle_events
- normalize_lifecycle_events → _normalize_lifecycle_events: internal only,
  called only by hosting._endpoint_handler
- Removed both from streaming/__init__.py exports

- output_item_custom_tool_call_output: output tightened from
  str | list[Any] to str | list[FunctionAndCustomToolCallOutput]
- OutputItemFunctionCallOutputBuilder.emit_added/emit_done: output
  tightened from str | list[Any] to str | list[InputTextContentParam |
  InputImageContentParamAutoParam | InputFileContentParam]
- Removed unused Any import from _function.py

* refactor: reduce public API surface — remove EVENT_TYPE alias, internalize 22 symbols

- Remove EVENT_TYPE alias: replaced all ~80 usages across 10 files with
  generated_models.ResponseStreamEventType directly
- Remove from streaming exports: EVENT_TYPE, encode_sse_event,
  encode_keep_alive_comment
- Remove from hosting exports: CreateSpan, CreateSpanHook,
  InMemoryCreateSpanHook, RecordedSpan, build_create_span_tags,
  build_platform_server_header, start_create_span,
  build_api_error_response, build_invalid_mode_error_response,
  build_not_found_error_response, parse_and_validate_create_response,
  parse_create_response, to_api_error_response, validate_create_response
- Remove from models exports: ResponseExecution, StreamEventRecord,
  StreamReplayState, get_instruction_items, get_output_item_id
- Remove from top-level exports: to_output_item
- Keep public: get_conversation_id, get_input_expanded,
  get_content_expanded, get_conversation_expanded,
  get_tool_choice_expanded, all builder classes, ResponseEventStream,
  TextResponse, all store/Foundry types

---------

Co-authored-by: Ankit Sinha <anksinha@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: rapida <rapida@microsoft.com>

Author: 4 people

sdk/agentserver/azure-ai-agentserver-responses/azure/ai/agentserver/responses/__init__.py

@@ -14,7 +14,6 @@
 from .models._helpers import (
     get_conversation_id,
     get_input_expanded,
-    to_output_item,
 )
 from .store._base import ResponseProviderProtocol, ResponseStreamProviderProtocol
 from .store._foundry_errors import (
@@ -51,5 +50,4 @@
     "ResponseObject",
     "get_conversation_id",
     "get_input_expanded",
-    "to_output_item",
 ]

sdk/agentserver/azure-ai-agentserver-responses/azure/ai/agentserver/responses/hosting/__init__.py

@@ -2,40 +2,8 @@
 # Licensed under the MIT license.
 """HTTP hosting, routing, and request orchestration for the Responses server."""
 
-from ._observability import (
-    CreateSpan,
-    CreateSpanHook,
-    InMemoryCreateSpanHook,
-    RecordedSpan,
-    build_create_span_tags,
-    build_platform_server_header,
-    start_create_span,
-)
 from ._routing import ResponsesAgentServerHost
-from ._validation import (
-    build_api_error_response,
-    build_invalid_mode_error_response,
-    build_not_found_error_response,
-    parse_and_validate_create_response,
-    parse_create_response,
-    to_api_error_response,
-    validate_create_response,
-)
 
 __all__ = [
     "ResponsesAgentServerHost",
-    "CreateSpan",
-    "CreateSpanHook",
-    "InMemoryCreateSpanHook",
-    "RecordedSpan",
-    "build_api_error_response",
-    "build_create_span_tags",
-    "build_invalid_mode_error_response",
-    "build_not_found_error_response",
-    "build_platform_server_header",
-    "parse_and_validate_create_response",
-    "parse_create_response",
-    "start_create_span",
-    "to_api_error_response",
-    "validate_create_response",
 ]

sdk/agentserver/azure-ai-agentserver-responses/azure/ai/agentserver/responses/hosting/_endpoint_handler.py

@@ -22,17 +22,21 @@
 from starlette.responses import JSONResponse, Response, StreamingResponse
 
 from azure.ai.agentserver.core import detach_context, end_span, flush_spans, set_current_span, trace_stream
-from azure.ai.agentserver.responses.models._generated import AgentReference, CreateResponse
+from azure.ai.agentserver.responses.models._generated import (
+    AgentReference,
+    CreateResponse,
+    ResponseStreamEventType,
+)
 
 from .._options import ResponsesServerOptions
 from .._response_context import IsolationContext, ResponseContext
 from ..models._helpers import get_input_expanded, to_output_item
 from ..models.errors import RequestValidationError
 from ..models.runtime import ResponseExecution, ResponseModeFlags, build_cancelled_response, build_failed_response
 from ..store._base import ResponseProviderProtocol, ResponseStreamProviderProtocol
-from ..streaming._helpers import EVENT_TYPE, _encode_sse
+from ..streaming._helpers import _encode_sse
 from ..streaming._sse import encode_sse_any_event
-from ..streaming._state_machine import normalize_lifecycle_events
+from ..streaming._state_machine import _normalize_lifecycle_events
 from ._execution_context import _ExecutionContext
 from ._observability import (
     CreateSpan,
@@ -208,11 +212,11 @@ def __init__(
 
         # Validate the lifecycle event state machine on startup so
         # misconfigured state machines surface immediately.
-        normalize_lifecycle_events(
+        _normalize_lifecycle_events(
             response_id="resp_validation",
             events=[
-                {"type": EVENT_TYPE.RESPONSE_CREATED.value, "response": {"status": "in_progress"}},
-                {"type": EVENT_TYPE.RESPONSE_COMPLETED.value, "response": {"status": "completed"}},
+                {"type": ResponseStreamEventType.RESPONSE_CREATED.value, "response": {"status": "in_progress"}},
+                {"type": ResponseStreamEventType.RESPONSE_COMPLETED.value, "response": {"status": "completed"}},
             ],
         )
 
@@ -342,7 +346,7 @@ def _build_execution_context(
         stream = bool(getattr(parsed, "stream", False))
         store = True if getattr(parsed, "store", None) is None else bool(parsed.store)
         background = bool(getattr(parsed, "background", False))
-        model = getattr(parsed, "model", None)
+        model = getattr(parsed, "model", None) or ""
         _expanded = get_input_expanded(parsed)
         input_items = [out for item in _expanded if (out := to_output_item(item, response_id)) is not None]
         previous_response_id: str | None = (
@@ -469,7 +473,9 @@ async def handle_create(self, request: Request) -> Response:  # pylint: disable=
 
         # B39: Resolve session ID
         config_session_id = getattr(getattr(self._host, "config", None), "session_id", "") or ""
-        agent_session_id = _resolve_session_id(parsed, payload, env_session_id=config_session_id)
+        agent_session_id = _resolve_session_id(
+            parsed, payload, env_session_id=config_session_id, agent_reference=agent_reference
+        )
 
         ctx = self._build_execution_context(
             parsed=parsed,
@@ -833,7 +839,7 @@ async def handle_delete(self, request: Request) -> Response:
                     )
 
         return JSONResponse(
-            {"id": response_id, "object": "response.deleted", "deleted": True},
+            {"id": response_id, "object": "response", "deleted": True},
             status_code=200,
         )
 

sdk/agentserver/azure-ai-agentserver-responses/azure/ai/agentserver/responses/hosting/_orchestrator.py

@@ -33,7 +33,6 @@
 )
 from ..store._base import ResponseProviderProtocol, ResponseStreamProviderProtocol
 from ..streaming._helpers import (
-    EVENT_TYPE,
     _apply_stream_event_defaults,
     _build_events,
     _coerce_handler_event,
@@ -126,20 +125,20 @@ async def _iter_with_winddown(
 
 _OUTPUT_ITEM_EVENT_TYPES: frozenset[str] = frozenset(
     {
-        EVENT_TYPE.RESPONSE_OUTPUT_ITEM_ADDED.value,
-        EVENT_TYPE.RESPONSE_OUTPUT_ITEM_DONE.value,
+        generated_models.ResponseStreamEventType.RESPONSE_OUTPUT_ITEM_ADDED.value,
+        generated_models.ResponseStreamEventType.RESPONSE_OUTPUT_ITEM_DONE.value,
     }
 )
 
 # Response-level lifecycle events whose ``response`` field carries a full Response snapshot.
 # Used by FR-008a output manipulation detection.
 _RESPONSE_SNAPSHOT_TYPES: frozenset[str] = frozenset(
     {
-        EVENT_TYPE.RESPONSE_IN_PROGRESS.value,
-        EVENT_TYPE.RESPONSE_COMPLETED.value,
-        EVENT_TYPE.RESPONSE_FAILED.value,
-        EVENT_TYPE.RESPONSE_INCOMPLETE.value,
-        EVENT_TYPE.RESPONSE_QUEUED.value,
+        generated_models.ResponseStreamEventType.RESPONSE_IN_PROGRESS.value,
+        generated_models.ResponseStreamEventType.RESPONSE_COMPLETED.value,
+        generated_models.ResponseStreamEventType.RESPONSE_FAILED.value,
+        generated_models.ResponseStreamEventType.RESPONSE_INCOMPLETE.value,
+        generated_models.ResponseStreamEventType.RESPONSE_QUEUED.value,
     }
 )
 
@@ -308,7 +307,8 @@ async def _run_background_non_stream(  # pylint: disable=too-many-locals,too-man
                     record.response_created_signal.set()
                 else:
                     # Track output_item.added events for FR-008a
-                    if normalized.get("type") == EVENT_TYPE.RESPONSE_OUTPUT_ITEM_ADDED.value:
+                    _item_added = generated_models.ResponseStreamEventType.RESPONSE_OUTPUT_ITEM_ADDED
+                    if normalized.get("type") == _item_added.value:
                         output_item_count += 1
 
                     # FR-008a: detect direct Output manipulation on response.* events
@@ -510,9 +510,9 @@ class _ResponseOrchestrator:  # pylint: disable=too-many-instance-attributes
 
     _TERMINAL_SSE_TYPES: frozenset[str] = frozenset(
         {
-            EVENT_TYPE.RESPONSE_COMPLETED.value,
-            EVENT_TYPE.RESPONSE_FAILED.value,
-            EVENT_TYPE.RESPONSE_INCOMPLETE.value,
+            generated_models.ResponseStreamEventType.RESPONSE_COMPLETED.value,
+            generated_models.ResponseStreamEventType.RESPONSE_FAILED.value,
+            generated_models.ResponseStreamEventType.RESPONSE_INCOMPLETE.value,
         }
     )
 
@@ -619,7 +619,7 @@ async def _cancel_terminal_sse_dict(
         :rtype: ResponseStreamEvent
         """
         cancel_event: dict[str, Any] = {
-            "type": EVENT_TYPE.RESPONSE_FAILED.value,
+            "type": generated_models.ResponseStreamEventType.RESPONSE_FAILED.value,
             "response": _build_cancelled_response(ctx.response_id, ctx.agent_reference, ctx.model).as_dict(),
         }
         return await self._normalize_and_append(ctx, state, cancel_event)
@@ -640,7 +640,7 @@ async def _make_failed_event(
         :rtype: ResponseStreamEvent
         """
         failed_event: dict[str, Any] = {
-            "type": EVENT_TYPE.RESPONSE_FAILED.value,
+            "type": generated_models.ResponseStreamEventType.RESPONSE_FAILED.value,
             "response": {
                 "id": ctx.response_id,
                 "object": "response",
@@ -685,6 +685,8 @@ async def _register_bg_execution(
             input_items=deepcopy(ctx.input_items),
             previous_response_id=ctx.previous_response_id,
             cancel_signal=ctx.cancellation_signal,
+            agent_session_id=ctx.agent_session_id,
+            conversation_id=ctx.conversation_id,
         )
         execution.set_response_snapshot(generated_models.ResponseObject(initial_payload))
         execution.subject = _ResponseEventSubject()
@@ -899,7 +901,7 @@ async def _process_handler_events(  # pylint: disable=too-many-return-statements
                 # appended to the state machine before we emit response.failed.
                 _pre_coerced = _coerce_handler_event(raw)
                 _pre_type = _pre_coerced.get("type", "")
-                if _pre_type == EVENT_TYPE.RESPONSE_OUTPUT_ITEM_ADDED.value:
+                if _pre_type == generated_models.ResponseStreamEventType.RESPONSE_OUTPUT_ITEM_ADDED.value:
                     output_item_count += 1
                 if _pre_type in _RESPONSE_SNAPSHOT_TYPES:
                     _pre_response = _pre_coerced.get("response") or {}
@@ -1105,6 +1107,8 @@ async def _finalize_stream(self, ctx: _ExecutionContext, state: _PipelineState)
             input_items=deepcopy(ctx.input_items),
             previous_response_id=ctx.previous_response_id,
             cancel_signal=ctx.cancellation_signal if ctx.background else None,
+            agent_session_id=ctx.agent_session_id,
+            conversation_id=ctx.conversation_id,
         )
         execution.set_response_snapshot(generated_models.ResponseObject(response_payload))
         await self._runtime_state.add(execution)
@@ -1381,6 +1385,8 @@ async def run_sync(self, ctx: _ExecutionContext) -> dict[str, Any]:
             input_items=deepcopy(ctx.input_items),
             previous_response_id=ctx.previous_response_id,
             response_context=ctx.context,
+            agent_session_id=ctx.agent_session_id,
+            conversation_id=ctx.conversation_id,
         )
         record.set_response_snapshot(generated_models.ResponseObject(response_payload))
 
@@ -1444,6 +1450,8 @@ async def run_background(self, ctx: _ExecutionContext) -> dict[str, Any]:
             cancel_signal=ctx.cancellation_signal,
             initial_model=ctx.model,
             initial_agent_reference=ctx.agent_reference,
+            agent_session_id=ctx.agent_session_id,
+            conversation_id=ctx.conversation_id,
         )
 
         # Register so GET can observe in-flight state