Hide agentserver response internals from API surface

[Shivakishore14]

Addresses the APIView feedback from PR #47995 by tightening the azure-ai-agentserver-responses public API surface while preserving contract-bearing types.

Changes:

• Removes root-level public helper leaks from azure.ai.agentserver.responses:
  • get_conversation_id
  • to_output_item
• Keeps the model expansion helpers public under azure.ai.agentserver.responses.models for SDK parity:
  • get_content_expanded
  • get_conversation_expanded
  • get_conversation_id
  • get_input_expanded
  • get_tool_choice_expanded
• Moves validation-only error plumbing from models.errors to private models._errors.
  • Public wire models models.ApiErrorResponse and models.Error remain unchanged.
  • The nested ApiErrorResponse.error: Error shape is preserved.
• Keeps models.runtime public because ResponseExecution, ResponseModeFlags, and StreamEventRecord appear in public signatures.
• Hides implementation-only runtime helpers by renaming them with leading underscores inside models.runtime:
  • _build_cancelled_response
  • _build_failed_response
  • _apply_cancelled_terminal
  • _apply_failed_terminal
  • _resolve_cancelled_response
  • _resolve_failed_response
  • _StreamReplayState
• Removes duplicate generated model aliases from the public models.runtime API surface.
• Adds 2.0.0b1 changelog/version entry for this API cleanup.
• Regenerates api.md and api.metadata.yml.

Validation:

• azpysdk apistub .
• azsdk_package_build_code (Python build no-op)
• azsdk_package_run_check with Linting
• Focused pytest suite: 246 passed, 1 warning

[azure-pipelines]

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.

[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

[Copilot]

Pull request overview

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

Suppressed comments (1)

sdk/agentserver/azure-ai-agentserver-responses/CHANGELOG.md:8

• This release note understates a breaking API change: the public models.errors/models.runtime members are removed, and responses.__init__ also drops the root-level get_conversation_id and to_output_item exports without mentioning them. This package records public removals under ### Breaking Changes (see this file at lines 83–88), so please classify and enumerate these removals rather than presenting them as an unspecified cleanup.

- Cleaned up the public API surface by moving validation-only error helpers and runtime terminal/replay helpers to private implementation modules.

[azure-pipelines]

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.

[azure-pipelines]

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

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

Suppressed comments (1)

sdk/agentserver/azure-ai-agentserver-responses/CHANGELOG.md:7

• This release also removes the public top-level get_conversation_id and to_output_item exports, so existing imports will fail, but the changelog only calls out the error/runtime changes. Please list these removals explicitly so the breaking API change is discoverable.

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

[github-actions]

[Pilot] PR Pipeline Failure Analysis

A CI pipeline failed on this pull request. Here is an automated analysis of what went wrong and how to get the build green.

What failed

One test is consistently failing across 5 platform/build matrix combinations (macOS Python 3.11, Ubuntu Python 3.12 sdist & whl, Ubuntu Python 3.13 sdist & whl, Ubuntu Python 3.14 whl):

• tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill

The failure is in the azure-ai-agentserver-responses package's end-to-end resilience contract test, specifically the "graceful exit (not SIGKILL)" path. The consistent reproduction across all OS/Python-version/package-format combinations suggests a test failure tied to a real behavioral regression introduced by this PR's API surface changes, rather than an infrastructure flake.

Recommended next steps

• Reproduce the failure locally: pytest tests/e2e/resilience_contract/test_row_1_path_b.py -k test_row_1_path_b_graceful_exit_not_sigkill -v
• Review whether the internal renaming of _build_cancelled_response, _build_failed_response, _apply_cancelled_terminal, _apply_failed_terminal, _resolve_cancelled_response, _resolve_failed_response, and _StreamReplayState (all now prefixed with _) inadvertently broke the graceful-exit/cancellation path exercised by this test.
• Check that any code inside the resilience contract test (or the runtime code it exercises) still correctly references the renamed symbols.
• Once fixed, push a new commit — the CI will re-run automatically.
• See the CI troubleshooting guide: https://aka.ms/ci-fix
• Push new commits to address the failures; this comment updates automatically on the next failing run.

Raw pipeline analysis (azsdk ci analyze)

Analyzing pipeline https://github.com/Azure/azure-sdk-for-python/pull/48370...
--------------------------------------------------------------------------------
Failed Tests
--------------------------------------------------------------------------------
{
  "/tmp/6652601/LLM Artifacts - macos311 - 1/agentserver-azure-ai-agentserver-responses-test-junit-whl.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ],
  "/tmp/6652601/LLM Artifacts - Ubuntu2404_313 - 1/agentserver-azure-ai-agentserver-responses-test-junit-sdist.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ],
  "/tmp/6652601/LLM Artifacts - ubuntu2404_312 - 1/agentserver-azure-ai-agentserver-responses-test-junit-sdist.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ],
  "/tmp/6652601/LLM Artifacts - ubuntu2404_312 - 1/agentserver-azure-ai-agentserver-responses-test-junit-whl.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ],
  "/tmp/6652601/LLM Artifacts - Ubuntu2404_314 - 1/agentserver-azure-ai-agentserver-responses-test-junit-whl.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ]
}

Copilot detected the failing pipeline and generated the analysis above. To have it attempt a fix automatically, reply with `@copilot please fix the failing pipeline on this PR`.

Generated by Pipeline Analysis - Next Steps · 19.5 AIC · ⌖ 8.81 AIC · ⊞ 6.6K · ◷