Enable voice agents for public preview

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

@@ -238,6 +238,65 @@ Details:
 > the other inline agent properties such as `codeConfiguration` and
 > `environmentVariables`.
 
+## Prompt voice telephony bindings
+
+Prompt voice agents can declare Foundry-side telephony bindings in `azure.yaml`.
+This lets `azd deploy` bind an existing phone-provider route to the deployed
+agent. Telephony is only supported for `kind: prompt-voice` services.
+
+```yaml
+services:
+  support-voice:
+    host: azure.ai.agent
+    kind: prompt-voice
+    name: support-voice
+    model:
+      id: gpt-realtime
+    telephony:
+      bindings:
+        - provider: twilio
+          identifier: "+14255550123"
+          connection: telephony-twilio
+        - provider: acs
+          identifier: "28:orgid:00000000-0000-0000-0000-000000000001"
+          connection: telephony-acs
+```
+
+Prerequisites:
+
+- The phone provider account/resource and phone number already exist.
+- The Foundry project connection named by `connection` already exists.
+- Provider-side callbacks, such as Twilio webhooks or ACS Event Subscriptions,
+  are configured by the user/admin.
+
+Supported providers and identifiers:
+
+- `twilio`: use a Twilio phone number in E.164 format, such as `+14255550123`.
+- `acs`: use `28:orgid:<guid>` for Teams Phone Extensibility Resource Accounts
+  or `4:+<E.164>` for ACS-purchased numbers. azd maps `acs` to the service
+  provider value `azure-communication-service`.
+
+Bindings are create-only in this preview. If a remote binding exists and matches
+the YAML, deploy continues. If the remote binding has different configuration,
+azd fails with a remediation message instead of silently keeping stale routing.
+
+Cleanup: delete telephony bindings before deleting test agents. The service may
+leave bindings behind when an agent is deleted, so do not rely on agent deletion
+as binding cleanup.
+
+Delete a binding with the agent-scoped telephony API before deleting the agent:
+
+```bash
+curl -X DELETE \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Foundry-Features: VoiceAgents=V1Preview" \
+  "$PROJECT_ENDPOINT/agents/$AGENT_NAME/telephony/$BINDING_ID?api-version=2025-11-15-preview"
+```
+
+The binding ID is the service provider plus identifier, for example
+`twilio:%2B14255550123` for `+14255550123`, or
+`azure-communication-service:28:orgid:<guid>` for ACS/TPE.
+
 ### Moderating invocations-protocol traffic
 
 For agents that expose the `invocations` protocol, the RAI policy alone is not
@@ -304,6 +363,78 @@ 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 sample `azure.yaml`
+flow as other current Hosted Agent and `invocations_ws` samples:
+
+```powershell
+azd ai agent init -m .\path\to\azure.yaml
+```
+
+The local path can be replaced with its public GitHub URL after the sample is
+published.
+
+When the sample project is already present with its `azure.yaml`, run
+`azd ai agent init` from the project directory to reuse the existing azd
+configuration before provisioning and deployment.
+
+The sample `azure.yaml` contains both services and references the target by its
+service name:
+
+```yaml
+services:
+  ai-project:
+    host: azure.ai.project
+
+  voice-target:
+    host: azure.ai.agent
+    project: ./src/voice-target
+    language: csharp
+    kind: hosted
+    name: voice-target
+    uses:
+      - ai-project
+    protocols:
+      - protocol: invocations_ws
+        version: 1.0.0
+    metadata:
+      voiceLiveCompatible: "true"
+      bridgeProtocolVersion: "1.0"
+    container:
+      resources:
+        cpu: "1"
+        memory: 2Gi
+    codeConfiguration:
+      runtime: dotnet_10
+      entryPoint: VoiceHostedAgent.dll
+      dependencyResolution: bundled
+
+  voice-target-voice:
+    host: azure.ai.agent
+    kind: voice
+    name: voice-target-voice
+    uses:
+      - ai-project
+      - voice-target
+    modelType: hosted_agent
+    targetAgent:
+      service: voice-target
+      version: deployed
+    store: false
+```
+
+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.
+
 ## 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,7 @@ words:
   # Voice (prompt-voice) agents
   - BYOM
   - Nanami
+  - orgid
   - pcma
   - pcmu
   - webrtc

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

@@ -2,7 +2,7 @@
 id: azure.ai.agents
 namespace: ai.agent
 displayName: Foundry agents (Beta)
-description: Ship agents with Microsoft Foundry from your terminal. (Beta)
+description: Ship hosted and voice agents with Microsoft Foundry from your terminal. (Beta)
 usage: azd ai agent <command> [options]
 # NOTE: Make sure version.txt is in sync with this version.
 version: 1.0.0-beta.14
@@ -29,5 +29,8 @@ providers:
     description: Deploys agents to the Foundry Agent Service
 examples:
   - name: init
-    description: Initialize a new AI agent project.
+    description: Initialize a new hosted or voice agent project.
     usage: azd ai agent init
+  - name: init-prompt-voice
+    description: Initialize a new prompt voice agent.
+    usage: azd ai agent init --kind prompt-voice --agent-name my-voice-agent

cli/azd/extensions/azure.ai.agents/internal/cmd/agent_endpoint.go

@@ -27,13 +27,13 @@ const agentEndpointHint = "run `azd ai agent show` to see the agent endpoint URL
 //
 //	[1] project name (URL-escaped),
 //	[2] agent name (URL-escaped),
-//	[3] protocol tail ("invocations", "a2a", or "openai/responses").
+//	[3] protocol tail ("invocations", "a2a", "openai/responses", or "voice").
 //
 // The "openai/v1/responses" tail is also accepted and rebuilt to the canonical
 // query-parameter form when invoked.
 var agentEndpointPathRegex = regexp.MustCompile(
 	`^/api/projects/([^/]+)/agents/([^/]+)/endpoint/protocols/` +
-		`(invocations|a2a|openai/v1/responses|openai/responses)/?$`,
+		`(invocations|a2a|openai/v1/responses|openai/responses|voice)/?$`,
 )
 
 // parsedAgentEndpoint describes a deployed agent invocation endpoint.
@@ -52,6 +52,7 @@ type parsedAgentEndpoint struct {
 //
 //	https://<acct>.services.ai.azure.com/api/projects/<proj>/agents/<name>/endpoint/protocols/invocations[?api-version=…]
 //	https://<acct>.services.ai.azure.com/api/projects/<proj>/agents/<name>/endpoint/protocols/openai/responses?api-version=v1
+//	wss://<acct>.services.ai.azure.com/api/projects/<proj>/agents/<name>/endpoint/protocols/voice?api-version=v1
 //
 // The host must be a `*.services.ai.azure.com` Foundry host. The path must include the
 // protocol-specific suffix; the protocol is derived from the URL.
@@ -73,10 +74,10 @@ func parseAgentEndpoint(rawURL string) (*parsedAgentEndpoint, error) {
 		)
 	}
 
-	if !strings.EqualFold(u.Scheme, "https") {
+	if !strings.EqualFold(u.Scheme, "https") && !strings.EqualFold(u.Scheme, "wss") {
 		return nil, exterrors.Validation(
 			exterrors.CodeInvalidParameter,
-			"--agent-endpoint must use https",
+			"--agent-endpoint must use https or wss",
 			agentEndpointHint,
 		)
 	}
@@ -139,6 +140,22 @@ func parseAgentEndpoint(rawURL string) (*parsedAgentEndpoint, error) {
 		protocol = agent_api.AgentProtocolA2A
 	case "openai/responses", "openai/v1/responses":
 		protocol = agent_api.AgentProtocolResponses
+	case "voice":
+		protocol = agent_api.AgentProtocolVoice
+	}
+	if protocol == agent_api.AgentProtocolVoice && !strings.EqualFold(u.Scheme, "wss") {
+		return nil, exterrors.Validation(
+			exterrors.CodeInvalidParameter,
+			"--agent-endpoint voice URLs must use wss",
+			agentEndpointHint,
+		)
+	}
+	if protocol != agent_api.AgentProtocolVoice && !strings.EqualFold(u.Scheme, "https") {
+		return nil, exterrors.Validation(
+			exterrors.CodeInvalidParameter,
+			"--agent-endpoint HTTP protocol URLs must use https",
+			agentEndpointHint,
+		)
 	}
 
 	// Reject an explicit but empty api-version query parameter; the default fallback would

cli/azd/extensions/azure.ai.agents/internal/cmd/agent_endpoint_test.go

@@ -74,6 +74,14 @@ func TestParseAgentEndpoint(t *testing.T) {
 			wantAgent: "hello",
 			wantProto: agent_api.AgentProtocolA2A,
 		},
+		{
+			name:       "voice websocket with api-version",
+			raw:        "wss://acct.services.ai.azure.com/api/projects/proj/agents/hello/endpoint/protocols/voice?api-version=v1",
+			wantProj:   "https://acct.services.ai.azure.com/api/projects/proj",
+			wantAgent:  "hello",
+			wantProto:  agent_api.AgentProtocolVoice,
+			wantAPIVer: "v1",
+		},
 		{
 			name:        "empty url",
 			raw:         "",
@@ -84,7 +92,19 @@ func TestParseAgentEndpoint(t *testing.T) {
 			name:        "http scheme rejected",
 			raw:         "http://acct.services.ai.azure.com/api/projects/proj/agents/hello/endpoint/protocols/invocations",
 			wantErr:     true,
-			errContains: "https",
+			errContains: "https or wss",
+		},
+		{
+			name:        "wss rejected for HTTP protocol endpoint",
+			raw:         "wss://acct.services.ai.azure.com/api/projects/proj/agents/hello/endpoint/protocols/invocations",
+			wantErr:     true,
+			errContains: "must use https",
+		},
+		{
+			name:        "https rejected for voice protocol endpoint",
+			raw:         "https://acct.services.ai.azure.com/api/projects/proj/agents/hello/endpoint/protocols/voice",
+			wantErr:     true,
+			errContains: "must use wss",
 		},
 		{
 			name:        "non-foundry host rejected",

cli/azd/extensions/azure.ai.agents/internal/cmd/delete.go

@@ -37,8 +37,8 @@ func newDeleteCommand(extCtx *azdext.ExtensionContext) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "delete [name]",
-		Short: "Delete a hosted agent.",
-		Long: `Delete a hosted agent and all of its versions.
+		Short: "Delete a hosted or voice agent.",
+		Long: `Delete a hosted or voice agent and all of its versions.
 
 If --version is specified, only that version is deleted (the agent itself remains).
 
@@ -253,6 +253,8 @@ func (a *DeleteAction) cleanupEnvVars(
 		fmt.Sprintf("AGENT_%s_NAME", serviceKey),
 		fmt.Sprintf("AGENT_%s_VERSION", serviceKey),
 		fmt.Sprintf("AGENT_%s_ENDPOINT", serviceKey),
+		fmt.Sprintf("AGENT_%s_TARGET_NAME", serviceKey),
+		fmt.Sprintf("AGENT_%s_TARGET_VERSION", serviceKey),
 		envkey.AgentProjectEndpoint(serviceName),
 	}
 	for _, protocol := range project.DisplayableProtocolEnvSuffixes() {
@@ -292,6 +294,8 @@ func (a *DeleteAction) clearDeletedVersionMarker(
 	keys := []string{
 		versionKey,
 		fmt.Sprintf("AGENT_%s_ENDPOINT", serviceKey),
+		fmt.Sprintf("AGENT_%s_TARGET_NAME", serviceKey),
+		fmt.Sprintf("AGENT_%s_TARGET_VERSION", serviceKey),
 	}
 	for _, protocol := range project.DisplayableProtocolEnvSuffixes() {
 		keys = append(keys, fmt.Sprintf("AGENT_%s_%s_ENDPOINT", serviceKey, protocol.Suffix))

cli/azd/extensions/azure.ai.agents/internal/cmd/delete_test.go

@@ -33,6 +33,8 @@ func TestDeleteMarkerCleanup(t *testing.T) {
 			"AGENT_MY_AGENT_NAME",
 			"AGENT_MY_AGENT_VERSION",
 			"AGENT_MY_AGENT_ENDPOINT",
+			"AGENT_MY_AGENT_TARGET_NAME",
+			"AGENT_MY_AGENT_TARGET_VERSION",
 			"AGENT_MY_AGENT_PROJECT_ENDPOINT",
 			"AGENT_MY_AGENT_RESPONSES_ENDPOINT",
 			"AGENT_MY_AGENT_INVOCATIONS_ENDPOINT",
@@ -82,6 +84,8 @@ func TestDeleteMarkerCleanup(t *testing.T) {
 		for _, key := range []string{
 			"AGENT_MY_AGENT_VERSION",
 			"AGENT_MY_AGENT_ENDPOINT",
+			"AGENT_MY_AGENT_TARGET_NAME",
+			"AGENT_MY_AGENT_TARGET_VERSION",
 			"AGENT_MY_AGENT_RESPONSES_ENDPOINT",
 			"AGENT_MY_AGENT_INVOCATIONS_ENDPOINT",
 			"AGENT_MY_AGENT_INVOCATIONS_WS_ENDPOINT",

cli/azd/extensions/azure.ai.agents/internal/cmd/deploy.go

@@ -67,12 +67,13 @@ func newAgentDeployCommand(extCtx *azdext.ExtensionContext) *cobra.Command {
 	flags := &agentDeployFlags{}
 	cmd := &cobra.Command{
 		Use:   "deploy [path]",
-		Short: "Deploy an agent directly from agent.yaml.",
-		Long: `Deploy an agent definition to the configured Foundry project.
+		Short: "Deploy a hosted or voice agent directly from agent.yaml.",
+		Long: `Deploy a hosted or voice agent definition to the configured Foundry project.
 
 The path defaults to ./agent.yaml. A hosted agent uploads source code from the
 definition directory unless --code specifies another path. If toolbox.yaml is
-present next to agent.yaml, it is deployed first through the toolbox extension.`,
+present next to agent.yaml, it is deployed first through the toolbox extension.
+Prompt voice and hosted voice definitions deploy through the unified Voice API.`,
 		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			path := "agent.yaml"