Add hosted voice agent support

cli/azd/extensions/azure.ai.agents/README.md

@@ -263,6 +263,164 @@ keys throughout this block (`invocations_moderation`, `response_mode`,
 `input_paths`, `stream_selectors`, `event_type`, and so on). The **values**
 (`non_streaming`, `streaming`, `both`, `json`, `text`) are the same in both.
 
+### Hosted voice wrapper (preview)
+
+A hosted voice wrapper keeps Voice Live responsible for VAD, speech-to-text,
+and text-to-speech while routing conversation logic to a hosted agent in the
+same Foundry project. Hosted Voice samples use the same standard Agent Manifest
+flow as other Hosted Agent and `invocations_ws` samples:
+
+```powershell
+azd ai agent init -m <PUBLIC_AGENT_MANIFEST_URL>
+```
+
+When the sample source is already present, run `azd ai agent init` from its
+directory and accept the detected local manifest. azd reuses a parent project
+when the source is already inside an existing azd project.
+
+Init generates both services and references the target by its `azure.yaml`
+service name:
+
+```yaml
+services:
+  voice-target:
+    host: azure.ai.agent
+    project: ./src/voice-target
+    language: csharp
+    kind: hosted
+    name: voice-target
+    protocols:
+      - protocol: invocations_ws
+        version: 1.0.0
+    metadata:
+      voiceLiveCompatible: "true"
+      bridgeProtocolVersion: "1.0"
+    codeConfiguration:
+      runtime: dotnet_10
+      entryPoint: VoiceHostedAgent.dll
+      dependencyResolution: bundled
+
+  voice:
+    host: azure.ai.agent
+    kind: prompt-voice
+    name: voice
+    uses:
+      - voice-target
+    modelType: hosted_agent
+    targetAgent:
+      service: voice-target
+      version: deployed
+    store: false
+    audio:
+      output:
+        voice:
+          type: azure_standard
+          name: en-US-JennyNeural
+```
+
+The `uses` edge deploys the target before the wrapper. `version: deployed`
+pins the wrapper to the target version produced by the current azd environment.
+Hosted voice wrappers use the unified Voice API.
+
+The target must be active, declare `invocations_ws/1.0.0`, and include
+`voiceLiveCompatible=true` and `bridgeProtocolVersion=1.0` metadata. Model,
+instructions, tools, and other conversation controls belong to the target;
+the wrapper owns audio, voice, store, avatar, and greeting configuration.
+
+For end-to-end validation, lifecycle checks, local dashboard steps, and the
+experience alignment matrix, see [Hosted Voice Agent Test Guide](docs/hosted-voice-test-guide.md).
+
+## Prompt voice advanced configuration
+
+Advanced prompt voice settings are authored on the `azure.ai.agent` service in
+`azure.yaml` and require the unified flat API mode:
+
+```bash
+azd env set AZURE_VOICE_AGENT_API unified-flat
+```
+
+```yaml
+services:
+  voice-agent:
+    host: azure.ai.agent
+    kind: prompt-voice
+    name: voice-agent
+    modelType: managed # or self_deployed for BYOM
+    model:
+      id: gpt-realtime
+    instructions: You are {{persona}}, a concise voice assistant.
+    structuredInputs:
+      persona:
+        description: Assistant persona
+        defaultValue: Ada
+        schema:
+          type: string
+    audio:
+      input:
+        format:
+          type: audio/pcmu
+        noiseReduction:
+          type: near_field
+        echoCancellation:
+          type: server_echo_cancellation
+          reference_source: server
+          channels: 1
+        turnDetection:
+          type: azure_semantic_vad
+          threshold: 0.6
+          speechDurationMs: 120
+          removeFillerWords: true
+          createResponse: true
+          interruptResponse: true
+          languages: [en-US]
+          autoTruncate: true
+        transcription:
+          model: azure-speech
+          language: en-US
+      output:
+        format:
+          type: audio/pcm
+          rate: 24000
+        voice:
+          type: azure_standard
+          name: en-US-AvaNeural
+          locale: en-US
+          style: cheerful
+        speed: 1.0
+    outputModalities: [audio, text]
+    tools:
+      - type: system
+        name: end_conversation
+    avatar:
+      type: video_avatar
+      character: lisa
+      style: casual-sitting
+      output_protocol: webrtc
+    greeting:
+      type: template
+      text: Hello {{persona}}
+    toolChoice: auto
+    maxOutputTokens: inf
+    include:
+      - item.input_audio_transcription.phrases
+```
+
+Notes:
+
+- `voice`, `instructions`, and `store` remain supported for simple prompt voice
+  agents. Missing audio fields keep the existing azd defaults.
+- `audio.output.voice` uses an author-friendly object shape; in `unified-flat`
+  mode azd maps it to the service flat fields `voice`, `voice_type`,
+  `voice_locale`, `style`, `pitch`, `rate`, and `volume`.
+- `structuredInputs.defaultValue` maps to the service wire field
+  `default_value`.
+- Direct voice tool types are `function`, `mcp`, `system`, and `toolbox`.
+  Server-side tools such as `web_search`, `azure_ai_search`, and `openapi` must
+  be packaged through a toolbox.
+- `tools`, `avatar`, `greeting`, `handoff`, `toolChoice`, and
+  `echoCancellation` intentionally remain light pass-through blocks so azd does
+  not block new service-side additions.
+
 ## Session idle timeout
 
 A hosted agent's runtime session sandbox is suspended by Foundry after a period

cli/azd/extensions/azure.ai.agents/cspell.yaml

@@ -11,6 +11,9 @@ words:
   # Voice (prompt-voice) agents
   - BYOM
   - Nanami
+  - pcma
+  - pcmu
+  - webrtc
   # Azure region names
   - australiaeast
   - brazilsouth