[VoiceLive] Release GA version of 1.2.0 (#46960)

* [VoiceLive] Release GA version of 1.2.0

* Update API version to 2026-04-10 and rename AvatarConfig.type to avatar_type

- Updated default API version from 2026-01-01-preview to 2026-04-10 in aio/_patch.py
- Renamed AvatarConfig.type field to avatar_type to avoid conflict with Python built-in
- Updated documentation string and docstring references
- Updated all sample code (async_mcp_sample.py) with new API version
- Updated test parametrization (test_live_realtime_service.py) with new API version
- Updated CHANGELOG.md with breaking change note
- Updated apiview-properties.json metadata

304 unit tests pass, no new test failures introduced.

* Update Foundry connect kwargs API

* fix change log

* add patch for legacy audio format

* fix pylint

* update docs

* update release date

* Update VoiceLive samples

---------

Co-authored-by: Xiting Zhang <xitzhang@microsoft.com>

Author: xitzhang

sdk/voicelive/azure-ai-voicelive/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Release History
 
-## 1.2.0 (Unreleased)
+## 1.2.0 (2026-05-22)
 
 ### Features Added
 
@@ -34,7 +34,7 @@
   - Response & function call ID tracking for end-to-end tracing
   - Agent v2 telemetry with agent identity and configuration tracking
   - MCP telemetry with tool call and approval flow tracking
-- **Agent Session Configuration**: Added `AgentSessionConfig` for configuring Azure AI Foundry agents
+- **Agent Session Configuration**: Added flattened `connect()` keyword arguments for configuring Azure AI Foundry agents
   at connection time with `agent_name`, `project_name`, `agent_version`, `conversation_id`, and more
 - **Transcription Improvements**:
   - Added `TranscriptionPhrase` and `TranscriptionWord` models for detailed transcription data
@@ -56,7 +56,12 @@
 ### Breaking Changes
 
 - Removed Foundry Agent Tool classes (`FoundryAgentTool`, `ResponseFoundryAgentCallItem`, etc.) —
-  use `AgentSessionConfig` with `connect()` instead
+  use flattened Azure AI Foundry keyword arguments with `connect()` instead
+- **Audio Format Values**: Changed `OutputAudioFormat` enum values to use underscore format
+  (`pcm16_8000hz`, `pcm16_16000hz`) instead of the previous hyphenated values.
+  This is a breaking change for code that compares, persists, or serializes the raw enum values.
+  Legacy hyphenated values continue to deserialize for backward compatibility.
+- Renamed `AvatarConfig.type` field to `avatar_type` to avoid conflict with Python's built-in `type`
 
 ### Other Changes
 
@@ -100,7 +105,7 @@
 - **Agent v2 Telemetry**: Added agent identity and configuration tracking on the connect span:
   - `gen_ai.agent.id` and `gen_ai.agent.thread_id` extracted from `session.created`/`session.updated`
     server events.
-  - `gen_ai.agent.version` and `gen_ai.agent.project_name` from `AgentSessionConfig` at connect time.
+  - `gen_ai.agent.version` and `gen_ai.agent.project_name` from Azure AI Foundry `connect()` keyword arguments at connect time.
 - **MCP (Model Context Protocol) Telemetry**: Added tracking for MCP tool calls and approval flows:
   - Per-event: `gen_ai.voice.mcp.server_label`, `gen_ai.voice.mcp.tool_name`,
     `gen_ai.voice.mcp.approval_request_id`, `gen_ai.voice.mcp.approve` on recv/send spans.
@@ -116,7 +121,7 @@
 
 ### Features Added
 
-- **Agent Session Configuration**: Added `AgentSessionConfig` TypedDict for configuring Azure AI Foundry agents at connection time:
+- **Agent Session Configuration**: Added flattened `connect()` keyword arguments for configuring Azure AI Foundry agents at connection time:
   - `agent_name`: The name of the agent (required)
   - `project_name`: The Foundry project containing the agent (required)
   - `agent_version`: Optional version specification
@@ -129,7 +134,7 @@
 ### Breaking Changes
 
 - **Removed Foundry Agent Tools**: The following classes and enums related to Foundry agent tools have been removed:
-  - `FoundryAgentTool` - Use `AgentSessionConfig` with `connect()` instead
+  - `FoundryAgentTool` - Use flattened Azure AI Foundry keyword arguments with `connect()` instead
   - `ResponseFoundryAgentCallItem`
   - `FoundryAgentContextType` enum
   - `ToolType.FOUNDRY_AGENT` enum value

sdk/voicelive/azure-ai-voicelive/apiview-properties.json

@@ -195,5 +195,5 @@
         "azure.ai.voicelive.models.RequestImageContentPartDetail": "VoiceLive.RequestImageContentPartDetail",
         "azure.ai.voicelive.models.ServerEventType": "VoiceLive.ServerEventType"
     },
-    "CrossLanguageVersion": "86299c665983"
+    "CrossLanguageVersion": "4f7c08a38aa5"
 }

sdk/voicelive/azure-ai-voicelive/azure/ai/voicelive/aio/_patch.py

@@ -14,7 +14,7 @@
 import logging
 from contextlib import AbstractAsyncContextManager
 from urllib.parse import urlparse, urlunparse, urlencode, parse_qs
-from typing import Any, Mapping, Optional, Union, AsyncIterator, cast
+from typing import Any, Mapping, Optional, Sequence, Union, AsyncIterator, cast, overload
 
 # === Third-party ===
 from typing_extensions import TypedDict
@@ -42,19 +42,18 @@
 from azure.core.credentials import AzureKeyCredential
 from azure.core.credentials_async import AsyncTokenCredential
 from azure.core.exceptions import AzureError
+from azure.ai.voicelive.models import ClientEvent, ServerEvent, RequestSession
 
 # === Local ===
-from ..models import ClientEvent, ServerEvent, RequestSession
 
 if sys.version_info >= (3, 11):
-    from typing import NotRequired, Required  # noqa: F401
+    from typing import NotRequired  # noqa: F401
 else:
-    from typing_extensions import NotRequired, Required  # noqa: F401
+    from typing_extensions import NotRequired  # noqa: F401
 
 __all__: list[str] = [
     "connect",
     "WebsocketConnectionOptions",
-    "AgentSessionConfig",
     "VoiceLiveConnection",
     "SessionResource",
     "ResponseResource",
@@ -94,33 +93,31 @@ def _json_default(o: Any) -> Any:
     raise TypeError(f"{type(o).__name__} is not JSON serializable")
 
 
-class AgentSessionConfig(TypedDict, total=False):
-    """
-    Configuration for agent session connection.
-
-    This TypedDict defines the parameters needed to connect to a Voice Live
-    session using an Azure AI Foundry agent.
-
-    :keyword agent_name: The name of the agent to use. Required.
-    :type agent_name: str
-    :keyword project_name: The name of the Foundry project containing the agent. Required.
-    :type project_name: str
-    :keyword agent_version: The version of the agent to use.
-    :type agent_version: str
-    :keyword conversation_id: The ID of an existing conversation to continue.
-    :type conversation_id: str
-    :keyword authentication_identity_client_id: The client ID for authentication identity.
-    :type authentication_identity_client_id: str
-    :keyword foundry_resource_override: An optional override for the Foundry resource.
-    :type foundry_resource_override: str
-    """
-
-    agent_name: Required[str]
-    project_name: Required[str]
-    agent_version: NotRequired[str]
-    conversation_id: NotRequired[str]
-    authentication_identity_client_id: NotRequired[str]
-    foundry_resource_override: NotRequired[str]
+def _build_foundry_agent_config(
+    *,
+    agent_name: Optional[str],
+    project_name: Optional[str],
+    agent_version: Optional[str],
+    conversation_id: Optional[str],
+    authentication_identity_client_id: Optional[str],
+    foundry_resource_override: Optional[str],
+) -> Optional[dict[str, str]]:
+    agent_config = {
+        "agent_name": agent_name,
+        "project_name": project_name,
+        "agent_version": agent_version,
+        "conversation_id": conversation_id,
+        "authentication_identity_client_id": authentication_identity_client_id,
+        "foundry_resource_override": foundry_resource_override,
+    }
+
+    if not any(value is not None for value in agent_config.values()):
+        return None
+
+    if agent_name is None or project_name is None:
+        raise ValueError("Both 'agent_name' and 'project_name' are required when connecting to an Azure AI Foundry agent.")
+
+    return {key: value for key, value in agent_config.items() if value is not None}
 
 
 class ConnectionError(AzureError):
@@ -673,21 +670,21 @@ def __init__(
         *,
         credential: Union["AzureKeyCredential", "AsyncTokenCredential"],
         endpoint: str,
-        api_version: str = "2026-01-01-preview",
+        api_version: str = "2026-04-10",
         model: Optional[str] = None,
-        agent_config: Optional[AgentSessionConfig] = None,
+        agent_config: Optional[Mapping[str, str]] = None,
         extra_query: Mapping[str, Any],
         extra_headers: Mapping[str, Any],
         connection_options: Optional[WebsocketConnectionOptions] = None,
-        **kwargs: Any,
+        credential_scopes: Optional[Union[str, Sequence[str]]] = None,
     ) -> None:
         self._credential = credential
         self._endpoint = endpoint
-        raw_scopes = kwargs.pop("credential_scopes", ["https://ai.azure.com/.default"])
+        raw_scopes = credential_scopes if credential_scopes is not None else ["https://ai.azure.com/.default"]
         self.__credential_scopes = [raw_scopes] if isinstance(raw_scopes, str) else list(raw_scopes)
         self.__api_version = api_version
         self.__model = model
-        self.__agent_config = agent_config
+        self.__agent_config = dict(agent_config) if agent_config is not None else None
 
         self.__connection: Optional["VoiceLiveConnection"] = None
         self.__extra_query = extra_query
@@ -869,16 +866,58 @@ async def __aexit__(self, exc_type, exc, exc_tb) -> None:
             await self.__connection.close()
 
 
+@overload
+def connect(
+    *,
+    credential: Union[AzureKeyCredential, AsyncTokenCredential],
+    endpoint: str,
+    api_version: str = "2026-04-10",
+    model: Optional[str] = None,
+    query: Optional[Mapping[str, Any]] = None,
+    headers: Optional[Mapping[str, Any]] = None,
+    connection_options: Optional[WebsocketConnectionOptions] = None,
+    credential_scopes: Optional[Union[str, Sequence[str]]] = None,
+) -> AbstractAsyncContextManager["VoiceLiveConnection"]:
+    ...
+
+
+@overload
+def connect(
+    *,
+    credential: Union[AzureKeyCredential, AsyncTokenCredential],
+    endpoint: str,
+    api_version: str = "2026-04-10",
+    model: Optional[str] = None,
+    agent_name: str,
+    project_name: str,
+    agent_version: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    authentication_identity_client_id: Optional[str] = None,
+    foundry_resource_override: Optional[str] = None,
+    query: Optional[Mapping[str, Any]] = None,
+    headers: Optional[Mapping[str, Any]] = None,
+    connection_options: Optional[WebsocketConnectionOptions] = None,
+    credential_scopes: Optional[Union[str, Sequence[str]]] = None,
+) -> AbstractAsyncContextManager["VoiceLiveConnection"]:
+    ...
+
+
 def connect(
     *,
     credential: Union[AzureKeyCredential, AsyncTokenCredential],
     endpoint: str,
-    api_version: str = "2026-01-01-preview",
+    api_version: str = "2026-04-10",
     model: Optional[str] = None,
-    agent_config: Optional[AgentSessionConfig] = None,
+    agent_name: Optional[str] = None,
+    project_name: Optional[str] = None,
+    agent_version: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    authentication_identity_client_id: Optional[str] = None,
+    foundry_resource_override: Optional[str] = None,
     query: Optional[Mapping[str, Any]] = None,
     headers: Optional[Mapping[str, Any]] = None,
     connection_options: Optional[WebsocketConnectionOptions] = None,
+    credential_scopes: Optional[Union[str, Sequence[str]]] = None,
     **kwargs: Any,
 ) -> AbstractAsyncContextManager["VoiceLiveConnection"]:
     """
@@ -890,33 +929,58 @@ def connect(
     - Establishes the connection and yields a :class:`~azure.ai.voicelive.aio.VoiceLiveConnection`.
     - Automatically cleans up the connection when the context exits.
 
+    Additional legacy keyword arguments are accepted for backward compatibility.
+    Unknown values are ignored.
+
     :keyword credential: The credential used to authenticate with the service.
-    :paramtype type credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials.AsyncTokenCredential
+    :paramtype credential: ~azure.core.credentials.AzureKeyCredential or ~azure.core.credentials.AsyncTokenCredential
     :keyword endpoint: Service endpoint, e.g., ``https://<region>.api.cognitive.microsoft.com``.
-    :paramtype type endpoint: str
-    :keyword api_version: The API version to use. Defaults to ``"2026-01-01-preview"``.
-    :paramtype type api_version: str
+    :paramtype endpoint: str
+    :keyword api_version: The API version to use. Defaults to ``"2026-04-10"``.
+    :paramtype api_version: str
     :keyword model: Model identifier to use for the session.
      In most scenarios, this parameter is required.
      It may be omitted only when connecting through an **Agent** scenario,
      in which case the service will use the model associated with the Agent.
     :paramtype model: str
-    :keyword agent_config: Optional agent session configuration for connecting to an Azure AI
-     Foundry agent. When provided, the connection will be established with the specified agent
-     and the ``model`` parameter may be omitted.
-    :paramtype agent_config: ~azure.ai.voicelive.aio.AgentSessionConfig
+    :keyword agent_name: Optional Azure AI Foundry agent name. When set, ``project_name`` is also required.
+    :paramtype agent_name: str
+    :keyword project_name: Azure AI Foundry project name. Required when ``agent_name`` is provided.
+    :paramtype project_name: str
+    :keyword agent_version: Optional Azure AI Foundry agent version.
+    :paramtype agent_version: str
+    :keyword conversation_id: Optional Azure AI Foundry conversation ID to continue.
+    :paramtype conversation_id: str
+    :keyword authentication_identity_client_id: Optional client ID used for Foundry authentication identity.
+    :paramtype authentication_identity_client_id: str
+    :keyword foundry_resource_override: Optional override for the Azure AI Foundry resource.
+    :paramtype foundry_resource_override: str
     :keyword query: Optional query parameters to include in the WebSocket URL.
-    :paramtype type query: Mapping[str, Any]
+    :paramtype query: Mapping[str, Any]F
     :keyword headers: Optional HTTP headers to include in the WebSocket handshake.
-    :paramtype type headers: Mapping[str, Any]
+    :paramtype headers: Mapping[str, Any]
     :keyword connection_options: Optional advanced WebSocket options compatible with :mod:`aiohttp`.
-    :paramtype type connection_options: ~azure.ai.voicelive.aio.WebsocketConnectionOptions
+    :paramtype connection_options: ~azure.ai.voicelive.aio.WebsocketConnectionOptions
+    :keyword credential_scopes: Optional scope override for token-based authentication.
+    :paramtype credential_scopes: str | Sequence[str]
     :return: An async context manager yielding a connected :class:`~azure.ai.voicelive.aio.VoiceLiveConnection`.
     :rtype: collections.abc.AsyncContextManager[~azure.ai.voicelive.aio.VoiceLiveConnection]
-
-    .. note::
-        Additional keyword arguments can be passed and will be forwarded to the underlying connection.
+    :raises ValueError: If only one of ``agent_name`` or ``project_name`` is provided.
     """
+    credential_scopes = cast(
+        Optional[Union[str, Sequence[str]]],
+        kwargs.pop("credential_scopes", credential_scopes),
+    )
+
+    agent_config = _build_foundry_agent_config(
+        agent_name=agent_name,
+        project_name=project_name,
+        agent_version=agent_version,
+        conversation_id=conversation_id,
+        authentication_identity_client_id=authentication_identity_client_id,
+        foundry_resource_override=foundry_resource_override,
+    )
+
     return _VoiceLiveConnectionManager(
         credential=credential,
         endpoint=endpoint,
@@ -926,7 +990,7 @@ def connect(
         extra_query=query or {},
         extra_headers=headers or {},
         connection_options=connection_options or {},
-        **kwargs,
+        credential_scopes=credential_scopes,
     )
 
 

sdk/voicelive/azure-ai-voicelive/azure/ai/voicelive/models/_enums.py

@@ -245,6 +245,12 @@ class OpenAIVoiceName(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """Cedar voice."""
 
 
+_LEGACY_OUTPUT_AUDIO_FORMAT_VALUES = {
+    "pcm16-8000hz": "pcm16_8000hz",
+    "pcm16-16000hz": "pcm16_16000hz",
+}
+
+
 class OutputAudioFormat(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """Output audio format types supported."""
 
@@ -259,6 +265,14 @@ class OutputAudioFormat(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     G711_ALAW = "g711_alaw"
     """G.711 A-law audio format at 8kHz sampling rate."""
 
+    @classmethod
+    def _missing_(cls, value):
+        if isinstance(value, str):
+            current_value = _LEGACY_OUTPUT_AUDIO_FORMAT_VALUES.get(value.lower())
+            if current_value is not None:
+                return cls(current_value)
+        return None
+
 
 class PersonalVoiceModels(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """PersonalVoice models."""

sdk/voicelive/azure-ai-voicelive/azure/ai/voicelive/models/_models.py

@@ -512,8 +512,8 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
 class AvatarConfig(_Model):
     """Configuration for avatar streaming and behavior during the session.
 
-    :ivar type: Type of avatar to use. Known values are: "video-avatar" and "photo-avatar".
-    :vartype type: str or ~azure.ai.voicelive.models.AvatarConfigTypes
+    :ivar avatar_type: Type of avatar to use. Known values are: "video-avatar" and "photo-avatar".
+    :vartype avatar_type: str or ~azure.ai.voicelive.models.AvatarConfigTypes
     :ivar ice_servers: Optional list of ICE servers to use for WebRTC connection establishment.
     :vartype ice_servers: list[~azure.ai.voicelive.models.IceServer]
     :ivar character: The character name or ID used for the avatar. Required.
@@ -537,8 +537,8 @@ class AvatarConfig(_Model):
     :vartype output_audit_audio: bool
     """
 
-    type: Optional[Union[str, "_models.AvatarConfigTypes"]] = rest_field(
-        visibility=["read", "create", "update", "delete", "query"]
+    avatar_type: Optional[Union[str, "_models.AvatarConfigTypes"]] = rest_field(
+        name="type", visibility=["read", "create", "update", "delete", "query"]
     )
     """Type of avatar to use. Known values are: \"video-avatar\" and \"photo-avatar\"."""
     ice_servers: Optional[list["_models.IceServer"]] = rest_field(
@@ -575,7 +575,7 @@ def __init__(
         *,
         character: str,
         customized: bool,
-        type: Optional[Union[str, "_models.AvatarConfigTypes"]] = None,
+        avatar_type: Optional[Union[str, "_models.AvatarConfigTypes"]] = None,
         ice_servers: Optional[list["_models.IceServer"]] = None,
         style: Optional[str] = None,
         model: Optional[Union[str, "_models.PhotoAvatarBaseModes"]] = None,