Hide agentserver response internals from API surface by Shivakishore14 · Pull Request #48370 · Azure/azure-sdk-for-python

Shivakishore14 · 2026-07-30T16:23:00Z

Addresses the initial APIView comments from PR #47995 by keeping implementation helpers out of the public API surface.

Changes:

Removes models.get_content_expanded from the public models export.
Moves response runtime helpers/state from models.runtime to private models._runtime.
Moves validation error helpers from models.errors to private models._errors, preserving the public models.ApiErrorResponse/models.Error wire shape.
Regenerates api.md and api.metadata.yml.

Validation:

azpysdk apistub .
pytest tests/unit/test_validation.py tests/unit/test_generated_payload_validation.py tests/unit/test_error_source_classification.py tests/unit/test_response_execution.py tests/unit/test_runtime_state.py tests/unit/test_public_contract_types.py tests/unit/test_response_context_input_items.py tests/unit/test_resolve_input_items_for_persistence.py tests/unit/test_string_content_expansion.py
pytest tests/contract/test_eager_eviction.py

Move response contracts to local TypedDict wire payloads and remove runtime reliance on generated model constructors, serialization helpers, and nested generated SDK model paths. Keep validation behind a stable local wrapper and update tests to exercise dict-native payloads instead of generated model runtime callability. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Use the source-built TypeSpec Python emitter TypedDict output as the model source instead of the localized bridge artifact. Normalize the emitted package into the local AgentServer generated boundary and remove fake model_base/_models compatibility shims. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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

Pin AgentServer TypeSpec generation to the source PR that removes stale OpenAI usage decorators and enables Python TypeDict generation. Replace the old finalization script with a minimal contract extractor, regenerate API docs and model contracts, and remove unused _types.py output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Regenerate AgentServer response TypedDict contracts, validators, and API docs from the current AgentServer service contract path. Point tsp-location.yaml at the fresh spec PR commit and compile from the clean synced Foundry/src root. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Inline the single-use wire field mutation helper and remove a thin Foundry serializer wrapper that only delegated to to_wire_dict. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

…peddict-local

Generate the TypedDict enum fallback at the root _generated package so validators use the same _enums import shape as latest main. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Point AgentServer Responses generation metadata at the latest spec PR commit after CI-only validation fixes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Address runtime dict-native response compatibility, static analysis, spelling, and Sphinx documentation failures for the AgentServer Responses package. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Update samples to use TypedDict-safe access and required discriminator fields so package Pyright validation passes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Regenerate AgentServer response contracts from the rapida/add-agentserver-view spec branch and restore the SDK TypeSpec pointer layout to the main SDK shape with only the commit updated. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Fix review feedback for dict-native response models by completing ID generation coverage, preserving wire field names, filtering storage-only SSE fields, and restoring ResponseIncompleteReason as a public compatibility enum. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Sanitize generated model docstrings that Sphinx treats as warnings, narrow public model exports to actual generated types, and add package spellcheck words for generated response ID prefixes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Avoid using generated enum fallback objects in runtime code by comparing against the stable wire string values directly, and annotate the ID dispatch table for mypy. Regenerate API stubs after the public export cleanup. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Handle scale service tier validation, tighten input text extraction, preserve required statuses on search output items, reject output-only item types from input conversion, and keep generated union aliases public without exposing enum literal aliases. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Use a correctly spelled invalid enum member name in the generated enum fallback regression test so CSpell does not flag the test-only typo. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Generate runtime enum classes from literal aliases so enum members preserve isinstance and iteration semantics, and materialize response timestamps as Unix integers in emitted wire payloads. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Move custom request validators out of the TypeSpec-emitted _generated package and align validation helper names with TypedDict Literal contracts instead of enum shims. Preserve scale service_tier support by reading the generated CreateResponse field literal before schema alias fallback. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Update the AgentServer responses SDK to consume the spec fix that removes the server-assigned id field from function-call input items. Regenerate TypedDict contracts, request validators, and API stubs, and add a checked typing contract for CreateResponse function-call input without id. Spec PR: Azure/azure-rest-api-specs#44927 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Update the AgentServer responses TypeSpec pin to the spec PR tip that includes the function-call input id fix and CI metadata for the SDK-only contracts folder. Spec PR: Azure/azure-rest-api-specs#44927 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Enforce generated Literal aliases for enum-like schemas, reject unknown discriminators, preserve nullable literal refs, export public Literal aliases, and clean generated validator/temp outputs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

…peddict-local # Conflicts: # sdk/agentserver/azure-ai-agentserver-responses/cspell.json Co-authored-by: Shivakishore14 <13432471+Shivakishore14@users.noreply.github.com>

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

Move response runtime and validation error helpers behind private modules and remove get_content_expanded from the public models export so APIView only shows intentional protocol models. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-07-30T16:23:22Z

Azure Pipelines: 10 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Remove undocumented data_url and normalization/conversion helpers from the public response package/model exports while keeping get_input_expanded public for hosted-agents sample compatibility. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Restore the runtime module for types that appear in public signatures and hide only the cancelled/failed response builder helpers behind underscored names. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Keep DataUrl and model expansion helpers public to align with the .NET AgentServer Responses surface while leaving non-parity internals private. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-07-31T19:19:27Z

Azure Pipelines: 10 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Hide internal validation errors and response builder helpers from the public API while preserving public runtime types and model expansion helpers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add a 2.0.0b1 changelog entry for the API surface cleanup. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-07-31T19:58:58Z

Azure Pipelines: Successfully started running 1 pipeline(s). 9 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Copilot

Pull request overview

Attempts to reduce the package’s public API surface by privatizing implementation helpers and updating generated API artifacts.

Changes:

Privatizes validation errors and response builders.
Removes selected top-level helper exports.
Updates tests, documentation, API artifacts, and version metadata.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`tests/unit/test_validation.py`	Uses private validation errors.
`tests/unit/test_response_execution.py`	Tests renamed private builder.
`tests/unit/test_generated_payload_validation.py`	Updates private error import.
`tests/unit/test_error_source_classification.py`	Updates private error import.
`doc/azure.ai.agentserver.responses.models.rst`	Removes public errors documentation.
`CHANGELOG.md`	Records API cleanup release.
`models/runtime.py`	Renames response builders as private.
`models/_errors.py`	Marks validation helpers internal.
`hosting/_validation.py`	Uses private validation errors.
`hosting/_request_parsing.py`	Uses private validation errors.
`_version.py`	Bumps version to `2.0.0b1`.
`responses/__init__.py`	Removes two top-level helper exports.
`api.metadata.yml`	Updates API artifact metadata.
`api.md`	Regenerates the documented API surface.



-def build_cancelled_response(
+def _build_cancelled_response(


-    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]: ...


…i-review-public-surface # Conflicts: # sdk/agentserver/azure-ai-agentserver-responses/CHANGELOG.md

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (2)

sdk/agentserver/azure-ai-agentserver-responses/azure/ai/agentserver/responses/models/runtime.py:344

Prefixing these two builders with _ does not perform the described move of runtime helpers/state to a private module. models/runtime.py remains public, and the regenerated API still exposes the resolver/apply helpers plus ResponseExecution, ResponseModeFlags, StreamEventRecord, and StreamReplayState under models.runtime (api.md:5924-6124). Move this implementation to models._runtime, update its imports/docs/tests, and regenerate the API artifacts.

def _build_cancelled_response(

sdk/agentserver/azure-ai-agentserver-responses/api.metadata.yml:1

The regenerated surface still exposes azure.ai.agentserver.responses.models.get_content_expanded at api.md:1755 because models/__init__.py continues to import it and list it in __all__. This contradicts the PR's stated removal; remove those export entries and regenerate both API artifacts.

apiMdSha256: 791aa262be4b10719e1a9ddde5516041bdad4d169806f83d5ebaef26474ccb30

Shivakishore14 and others added 30 commits July 10, 2026 11:01

Reduce redundant agentserver wire conversions

2e9a3b1

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

Merge remote-tracking branch 'origin/main' into sshiva/agentserver-ty…

039fbd2

…peddict-local

Sync AgentServer spec pointer

e97042d

Point AgentServer Responses generation metadata at the latest spec PR commit after CI-only validation fixes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Fix AgentServer Responses sample typing

01233dd

Update samples to use TypedDict-safe access and required discriminator fields so package Pyright validation passes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Merge branch 'main' into sshiva/agentserver-typeddict-local

6fe830f

Address AgentServer review and API consistency

92db0e3

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Fix AgentServer stream TTL contract tests

1ec49f6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Hide internal AgentServer message models

34b2061

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Remove AgentServer generated enum shim

26383d8

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Merge branch 'main' into sshiva/agentserver-typeddict-local

af85d78

Merge branch 'main' into sshiva/agentserver-typeddict-local

2762371

Fix agentserver generated docs warnings

adc5760

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Copilot AI and others added 5 commits July 29, 2026 07:40

Merge remote-tracking branch 'origin/main' into sshiva/agentserver-ty…

5160464

…peddict-local # Conflicts: # sdk/agentserver/azure-ai-agentserver-responses/cspell.json Co-authored-by: Shivakishore14 <13432471+Shivakishore14@users.noreply.github.com>

Merge main into agentserver TypeDict PR

0dadb89

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

Document agentserver TypedDict migration

79b4d5e

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

Fix agentserver CI validation

cc43307

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

github-actions Bot added the Hosted Agents sdk/agentserver/* label Jul 30, 2026

Shivakishore14 and others added 3 commits July 31, 2026 18:44

Keep public runtime signature types importable

34af68e

Restore the runtime module for types that appear in public signatures and hide only the cancelled/failed response builder helpers behind underscored names. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Restore response helper exports for SDK parity

fc0beea

Keep DataUrl and model expansion helpers public to align with the .NET AgentServer Responses surface while leaving non-parity internals private. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Shivakishore14 marked this pull request as ready for review July 31, 2026 19:19

Shivakishore14 requested review from RaviPidaparthi, ankitbko and vangarp as code owners July 31, 2026 19:19

Shivakishore14 changed the base branch from sshiva/agentserver-typeddict-local to main July 31, 2026 19:27

Shivakishore14 marked this pull request as draft July 31, 2026 19:29

Shivakishore14 and others added 2 commits July 31, 2026 19:41

Clean up agentserver responses API surface

98b984f

Hide internal validation errors and response builder helpers from the public API while preserving public runtime types and model expansion helpers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Bump agentserver responses version to 2.0.0b1

dd08324

Add a 2.0.0b1 changelog entry for the API surface cleanup. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Shivakishore14 marked this pull request as ready for review July 31, 2026 19:58

Copilot AI review requested due to automatic review settings July 31, 2026 19:58

Copilot started reviewing on behalf of Shivakishore14 July 31, 2026 19:59 View session

Copilot AI reviewed Jul 31, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into sshiva/agentserver-ap…

54fe469

…i-review-public-surface # Conflicts: # sdk/agentserver/azure-ai-agentserver-responses/CHANGELOG.md

Copilot AI review requested due to automatic review settings August 3, 2026 16:14

Copilot started reviewing on behalf of Shivakishore14 August 3, 2026 16:15 View session

Copilot AI reviewed Aug 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Hide agentserver response internals from API surface - #48370

Hide agentserver response internals from API surface#48370
Shivakishore14 wants to merge 41 commits into
mainfrom
sshiva/agentserver-api-review-public-surface

Shivakishore14 commented Jul 30, 2026

Uh oh!

azure-pipelines Bot commented Jul 30, 2026

Uh oh!

azure-pipelines Bot commented Jul 31, 2026

Uh oh!

azure-pipelines Bot commented Jul 31, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		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]: ...

Uh oh!

Conversation

Shivakishore14 commented Jul 30, 2026

Uh oh!

azure-pipelines Bot commented Jul 30, 2026

Uh oh!

azure-pipelines Bot commented Jul 31, 2026

Uh oh!

azure-pipelines Bot commented Jul 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants