[VoiceAgents][Do not merge] Voice Agents private preview

[xitzhang]

Description

Please add an informative description that covers that changes made by the pull request and link all relevant issues.

If an SDK is being regenerated based on a new API spec, a link to the pull request containing these API spec changes should be included above.

All SDK Contribution checklist:

• The pull request does not introduce [breaking changes]
• CHANGELOG is updated for new features, bug fixes or other significant changes.
• I have read the contribution guidelines.

General Guidelines and Best Practices

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

• Pull request includes test coverage for the included changes.

[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

Introduces the private-preview azure-ai-voiceagents SDK for managing voice agents and persisted conversations.

Changes:

• Adds generated synchronous/async clients, models, and metadata.
• Adds an interface-only realtime namespace, samples, and unit tests.
• Configures packaging and CI pipelines.

Reviewed changes

Copilot reviewed 51 out of 54 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
sdk/voiceagents/tests.yml	Adds weekly analysis pipeline.
sdk/voiceagents/ci.yml	Adds package CI configuration.
sdk/voiceagents/azure-ai-voiceagents/tsp-location.yaml	Defines TypeSpec source locations.
sdk/voiceagents/azure-ai-voiceagents/tests/unit/test_unit_realtime.py	Tests the realtime preview interface.
sdk/voiceagents/azure-ai-voiceagents/tests/unit/test_unit_models.py	Tests model serialization.
sdk/voiceagents/azure-ai-voiceagents/tests/unit/test_unit_enums.py	Tests enum wire values.
sdk/voiceagents/azure-ai-voiceagents/tests/unit/test_unit_client.py	Tests client defaults.
sdk/voiceagents/azure-ai-voiceagents/tests/unit/__init__.py	Initializes unit tests.
sdk/voiceagents/azure-ai-voiceagents/tests/conftest.py	Documents offline test configuration.
sdk/voiceagents/azure-ai-voiceagents/tests/__init__.py	Initializes the test package.
sdk/voiceagents/azure-ai-voiceagents/samples/sample_read_conversation.py	Demonstrates reading conversations.
sdk/voiceagents/azure-ai-voiceagents/samples/sample_read_conversation_audio.py	Demonstrates audio retrieval.
sdk/voiceagents/azure-ai-voiceagents/samples/sample_manage_voice_agent_versions.py	Demonstrates version management.
sdk/voiceagents/azure-ai-voiceagents/samples/sample_generate_voice_agent.py	Demonstrates guided agent generation.
sdk/voiceagents/azure-ai-voiceagents/samples/sample_create_voice_agent_with_tools.py	Demonstrates tools and audio configuration.
sdk/voiceagents/azure-ai-voiceagents/samples/sample_create_and_manage_voice_agent.py	Demonstrates the management lifecycle.
sdk/voiceagents/azure-ai-voiceagents/samples/README.md	Documents available samples.
sdk/voiceagents/azure-ai-voiceagents/samples/async_samples/sample_create_and_manage_voice_agent_async.py	Adds the async lifecycle sample.
sdk/voiceagents/azure-ai-voiceagents/README.md	Adds package documentation.
sdk/voiceagents/azure-ai-voiceagents/pyproject.toml	Defines package metadata and dependencies.
sdk/voiceagents/azure-ai-voiceagents/MANIFEST.in	Configures source distribution contents.
sdk/voiceagents/azure-ai-voiceagents/LICENSE	Adds the MIT license.
sdk/voiceagents/azure-ai-voiceagents/dev_requirements.txt	Defines development dependencies.
sdk/voiceagents/azure-ai-voiceagents/CHANGELOG.md	Adds initial release history.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/types.py	Defines generated typed dictionaries.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/py.typed	Marks the package as typed.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/operations/_patch.py	Adds operation customization hook.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/operations/__init__.py	Exports synchronous operations.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/models/_patch.py	Adds model customization hook.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/models/_enums.py	Defines generated enums.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/models/__init__.py	Exports public models.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/operations/_patch.py	Adds async operation customization hook.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/operations/__init__.py	Exports asynchronous operations.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/_realtime.py	Implements the interface-only realtime surface.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/_patch.py	Adds realtime to the async client.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/_configuration.py	Configures the async client.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/_client.py	Implements the generated async client.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/__init__.py	Exports async APIs.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/_version.py	Defines package version.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/_utils/__init__.py	Initializes generated utilities.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/_unions.py	Defines model unions.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/_patch.py	Adds package customization hook.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/_configuration.py	Configures the synchronous client.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/_client.py	Implements the generated sync client.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/__init__.py	Exports package APIs and version.
sdk/voiceagents/azure-ai-voiceagents/azure/ai/__init__.py	Extends the namespace package.
sdk/voiceagents/azure-ai-voiceagents/azure/__init__.py	Extends the Azure namespace.
sdk/voiceagents/azure-ai-voiceagents/apiview-properties.json	Maps cross-language API identities.
sdk/voiceagents/azure-ai-voiceagents/_metadata.json	Records generated API versions.

Comments suppressed due to low confidence (1)

sdk/voiceagents/azure-ai-voiceagents/samples/sample_create_voice_agent_with_tools.py:105

• example_toolbox_tool is also never used and triggers pylint's unused-variable check. Mark this illustrative value as intentionally unused.

[Copilot]

Pull request overview

Copilot reviewed 53 out of 57 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (5)

sdk/voiceagents/azure-ai-voiceagents/tsp-location.yaml:3

• The committed regeneration manifest still contains template placeholders. azpysdk generate delegates to tsp-client update, which needs a real repository and pinned spec commit; sibling TypeSpec packages use values such as repo: Azure/azure-rest-api-specs plus a SHA (sdk/ai/azure-ai-projects/tsp-location.yaml:1-3). Pin the exact source before merge so this generated SDK is reproducible.
  sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/_patch.py:20
• Subclassing the generated client without redeclaring its constructor degrades the published API surface: the generated api.md exposes this constructor as credential: Any and omits the api_version keyword, whereas the generated base client has an AsyncTokenCredential and explicit API-version contract. Add an explicitly typed forwarding __init__, following the customized client pattern in sdk/discovery/azure-ai-discovery/.../aio/_patch.py:30-59, then regenerate the API snapshot.

class VoiceAgentsClient(_GeneratedVoiceAgentsClient):

sdk/voiceagents/azure-ai-voiceagents/README.md:53

• This HTML placeholder is not valid Python, so the primary README example raises SyntaxError when copied. Replace it with a real voice-agent operation that includes the required preview opt-in.

        <!-- write test code here -->

sdk/voiceagents/azure-ai-voiceagents/README.md:13

• Correct the misspelled section heading.

#### Prequisites

sdk/voiceagents/azure-ai-voiceagents/README.md:17

• The client accepts an Azure AI Foundry project endpoint; there is no separate “Voiceagents instance” resource in the setup described by this SDK. State the actual prerequisite and use the product's official capitalization.

- An existing Azure Ai Voiceagents instance.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (7)

sdk/voiceagents/azure-ai-voiceagents/tsp-location.yaml:3

• Replace these placeholders with the exact azure-rest-api-specs repository and commit used for generation. As committed, the package has no reproducible source provenance and the standard regeneration workflow cannot consume this file.
  sdk/voiceagents/azure-ai-voiceagents/samples/README.md:39
• The source says the MCP and toolbox objects are illustrative and are not attached to the agent, but this table claims the sample creates an agent with all four tool kinds. Clarify that only function and system are attached so the sample index accurately describes its behavior.
  sdk/voiceagents/azure-ai-voiceagents/CHANGELOG.md:3
• The 1970-01-01 generator placeholder is not a meaningful release date. Set this to the planned initial-preview release date before publishing the package.

## 1.0.0b1 (Unreleased)

sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/_realtime.py:10

• This says realtime is a standalone client, but the implementation exposes it as VoiceAgentsClient.realtime. Describe the actual entry point to avoid directing users toward a client class that does not exist.

Realtime uses a fundamentally different transport (a persistent WebSocket)
than the request/response HTTP surface, so it is exposed as a **dedicated
standalone client** rather than a member of the HTTP ``VoiceAgentsClient``.

sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/_realtime.py:14

• VoiceAgentsRealtimeClient is not defined or exported by this package; the method belongs to AsyncRealtime. This Sphinx reference will not resolve to the public API.

* :meth:`AsyncRealtime.connect` returns an async context manager.

sdk/voiceagents/azure-ai-voiceagents/README.md:1

• Use the product's canonical capitalization and spacing in the package title.

# Azure AI Voice Agents client library for Python

sdk/voiceagents/azure-ai-voiceagents/README.md:68

• This public README example is not valid Python because it contains an HTML placeholder, and it never closes the client. Replace it with an executable preview operation so users can copy and run the documented example.

>>> client = VoiceAgentsClient(endpoint='<endpoint>', credential=DefaultAzureCredential())
>>> try:
        <!-- write test code here -->
    except HttpResponseError as e:
        print('service responds error: {}'.format(e.response.json()))

[Copilot]

Pull request overview

Copilot reviewed 53 out of 57 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (3)

sdk/voiceagents/azure-ai-voiceagents/README.md:13

• Correct the misspelled section heading so documentation checks and the published README use the standard term.

#### Prequisites

sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/_realtime.py:362

• This class-level example presents connect() as usable, but the method unconditionally raises NotImplementedError. Since this text is part of the public API documentation, replace the guaranteed-to-fail walkthrough with an explicit interface-only notice until streaming is enabled.

        client = VoiceAgentsClient(endpoint, DefaultAzureCredential())
        async with client.realtime.connect(agent_name="my-agent") as conn:

sdk/voiceagents/azure-ai-voiceagents/README.md:66

• This fenced Python example contains an HTML comment and incomplete doctest-style indentation, so copying or executing it raises a SyntaxError. Replace the placeholder with a real SDK operation and make the whole block valid Python.

        <!-- write test code here -->

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (3)

sdk/voiceagents/azure-ai-voiceagents/tsp-location.yaml:3

• Replace these placeholders with the actual azure-rest-api-specs repository URL and source commit before merging. azpysdk generate delegates this file to tsp-client update, so the current values make the generated SDK non-reproducible and also record invalid source provenance in package metadata.
  sdk/voiceagents/azure-ai-voiceagents/samples/README.md:40
• This description says the sample creates an agent with MCP and toolbox tools, but those objects are explicitly illustrative and are not attached to the agent (sample_create_voice_agent_with_tools.py:96-107,133-135). Clarify that only function and system tools are configured so users do not expect the created resource to contain all four kinds.
  sdk/voiceagents/azure-ai-voiceagents/README.md:66
• This placeholder is not Python, so the package's primary example cannot be copied or validated, and it also omits the preview opt-in required by every operation. Replace it with a real request that passes VOICE_AGENTS_V1_PREVIEW.

        <!-- write test code here -->

[Copilot]

Pull request overview

Copilot reviewed 57 out of 61 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (3)

sdk/voiceagents/azure-ai-voiceagents/tsp-location.yaml:3

• These placeholders make the generated SDK non-reproducible: the generation tooling cannot resolve which specification repository and commit produced this package. Replace them with the exact source repository and immutable commit before merging, as done by the other TypeSpec packages (for example, sdk/ai/azure-ai-projects/tsp-location.yaml:2-3).
  sdk/voiceagents/azure-ai-voiceagents/README.md:66
• This HTML placeholder is inside a Python code block, so copying or validating the advertised example produces a SyntaxError. Replace it with a real Voice Agents operation (including the preview opt-in) so the README contains executable Python.

        <!-- write test code here -->

sdk/voiceagents/azure-ai-voiceagents/samples/README.md:40

• This row says the created agent includes mcp and toolbox tools, but the sample deliberately leaves those objects out of tools and attaches only function and system. Reword the description so readers do not expect the sample to configure external MCP/toolbox resources.

[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

Two validation failures were detected in the azure-ai-voiceagents package (build #6616302):

1. CSpell (spell check) — The word Efmt is flagged as unknown in test files:

   • tests/unit/test_unit_operations.py (lines 236, 258)
   • tests/unit/test_unit_operations_async.py (line 228)

2. Pylint — Unused import urllib.parse in two generated source files:

   • azure/ai/voiceagents/operations/_operations.py:13
   • azure/ai/voiceagents/aio/operations/_operations.py:13

Recommended next steps

• CSpell: If Efmt is intentional (e.g., a format string or enum abbreviation), add it to the repository's custom word list (.cspell.json or equivalent). Otherwise, rename the identifier to a recognized English word/abbreviation.
• Pylint: Remove the unused import urllib.parse from both _operations.py files (sync and async). If the import was auto-generated, regenerate the SDK or suppress with # pylint: disable=unused-import and a justification comment.
• 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)

Failed Tasks

### Errors:
[CSpell]
##[error]sdk/voiceagents/azure-ai-voiceagents/tests/unit/test_unit_operations.py:236:28 - Unknown word (Efmt)
##[error]sdk/voiceagents/azure-ai-voiceagents/tests/unit/test_unit_operations.py:258:28 - Unknown word (Efmt)
##[error]sdk/voiceagents/azure-ai-voiceagents/tests/unit/test_unit_operations_async.py:228:32 - Unknown word (Efmt)
##[error]Spelling errors detected. See: https://aka.ms/azsdk/engsys/spellcheck

[Pylint]
azure/ai/voiceagents/operations/_operations.py:13: [W0611(unused-import), ] Unused import urllib.parse
azure/ai/voiceagents/aio/operations/_operations.py:13: [W0611(unused-import), ] Unused import urllib.parse

ERROR: azure-ai-voiceagents main package exited with linting error 4.
See: https://aka.ms/azsdk/python/pylint-guide

SUMMARY: /mnt/vss/_work/1/s/sdk/voiceagents/azure-ai-voiceagents  pylint  FAIL(4)

Pipeline: https://dev.azure.com/azure-sdk/public/_build/results?buildId=6616302

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 · 30.9 AIC · ⌖ 8.74 AIC · ⊞ 6.6K · ◷

[Copilot]

Pull request overview

Copilot reviewed 57 out of 61 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (3)

sdk/voiceagents/azure-ai-voiceagents/tsp-location.yaml:3

• These placeholders are consumed directly by tsp-client update, so this package cannot be regenerated from a pinned source revision. Replace them with the exact azure-rest-api-specs repository and commit used to produce this SDK before merging.
  sdk/voiceagents/azure-ai-voiceagents/README.md:68
• This fenced python example contains an HTML placeholder and invalid indentation, so readers cannot run it and documentation validation may reject it. Replace it with valid Python that demonstrates an actual operation.

>>> try:
        <!-- write test code here -->
    except HttpResponseError as e:
        print('service responds error: {}'.format(e.response.json()))

sdk/voiceagents/azure-ai-voiceagents/samples/README.md:40

• This description says the created agent includes mcp and toolbox tools, but the sample deliberately leaves _example_mcp_tool and _example_toolbox_tool out of tools=[get_weather, end_call]. Clarify that those two are construction examples only.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (3)

sdk/voiceagents/azure-ai-voiceagents/tsp-location.yaml:3

• Replace these placeholders before merging. tsp-client update uses this file to locate the TypeSpec source, so without the exact source repository and commit the SDK cannot be reproducibly regenerated or pass the generation check.
  sdk/voiceagents/azure-ai-voiceagents/azure/ai/voiceagents/aio/_realtime.py:321
• The manager is publicly exported, so callers can instantiate it and call enter() directly, bypassing the connect() guard and attempting the supposedly unavailable WebSocket route. Apply the same NotImplementedError guard here so every public entry path remains interface-only.

        try:

sdk/voiceagents/azure-ai-voiceagents/samples/README.md:40

• This description says the sample creates an agent with MCP and toolbox tools, but those objects are explicitly not attached to the agent. Clarify that only function/system tools are attached so users do not expect this sample to exercise MCP or toolbox integration.