Enable voice agents for public preview

[JianW (v1212)]

Summary

• Remove the voice-only AZD_AI_AGENT_ENABLE_PROMPT_VOICE gate; expose existing voice options, help and CLI discovery.
• Document existing managed/BYOM voice, telephony and conversationEngine hosted wrappers. Guide recognized voice invoke attempts to the Foundry portal.
• Preserve main's managed prompt/harness and invocation lifecycle capabilities; help accurately includes prompt, hosted and voice rather than reverting to hosted-only wording.

Dependency / merge order

Merge #9948 first. This branch was rebuilt on main a1243a2c845793868ff91bc30691514e2a965db6 plus #9948 9b54f68fa8ee423a55fc2e7f5d60a5492fc4df3d, then only the public-preview commits were replayed. Both SHAs are ancestors. No writes to #9948's branch.

After #9948 merges, remove dependency history and revalidate the public-preview delta on main. #9697 and #9804 are merged. Closes #9889.

Scope and conflict resolution

• No changes to generated kind, kind alias semantics, model defaults, API headers, managed harness gates or main's invocation lifecycle implementation.
• Preserve --kind hosted/prompt/prompt-voice, --harness, prompt routing, deployed protocol metadata and direct-name fallback.
• Hosted voice uses conversationEngine as required by Support hosted voice conversation engine #9948; old modelType: hosted_agent / targetAgent authoring remains rejected.
• Keep approved schema guidance removing obsolete targetAgent child suggestions; preserve new prompt-agent schema constraints.
• Keep approved voice-only portal guidance and definition override precedence; ordinary hosted targets and prompt agents are not classified as voice. Explicit local HTTP/endpoint and unknown-type paths retain existing behavior.
• No extra WebSocket URL parser, browser launch, standalone voice deploy or voice conversation implementation.

Validation — ec760bf integration, ae6e8e4 help follow-up

• Full Windows go test ./... -count=1, go vet ./..., go fix -diff ./..., go build, Go spelling and whitespace checks passed.
• Voice, managed prompt, invocation lifecycle and help regressions passed three repeated runs.
• Added managed prompt/harness non-voice classification and prompt schema acceptance checks; verify new invocations command remains visible.
• Existing README examples passed resolver/schema validation. Schema annotation assertions follow Support hosted voice conversation engine #9948's updated property-level descriptions.
• Local race unavailable (no CGO/C compiler). CI validates platform lint/builds.
• Voice audio cloud E2E and manual interactive scenarios are not claimed. Updated interactive scenarios remain unexecuted: tier0/0.02-help-root.yaml and tier0/0.10-init-picker-navigation.yaml.

Requires new CI results, #9948 merge/cleanup, and maintainer approval before merge.
Help-only follow-up ae6e8e4 addresses Copilot: --model applies to hosted and prompt agents, with managed prompt voice described separately. Rendered help tests passed three runs; full cmd tests, cmd vet and build passed. New CI is pending. The previously delivered bug bash ZIP remains pinned to ec760bf and has not been silently replaced.

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).
20 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[JianW (v1212)]

/azp run azure-dev - live - ext - azure.ai.agents

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).
20 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[github-actions]

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Thank you for logging this issue; our team is reviewing it. If you need urgent prioritization, tag Rick Winter (@RickWinter) and Kristen Womack (@kristenwomack) to let us know.

[Copilot]

🟡 Changes recommended

The help promises unsupported standalone voice deployment, interactive scenarios are stale, and several added lines violate enforced lint limits.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Enables Voice Agents for public preview by removing the prompt-voice gate and improving CLI discoverability and endpoint guidance.

Changes:

• Exposes prompt-voice initialization flags and picker flow.
• Updates command help and extension metadata for voice agents.
• Recognizes Voice Live WebSocket endpoints and returns targeted guidance.

File summaries

File	Description
internal/pkg/agents/agent_api/models.go	Adds the voice protocol constant.
internal/cmd/show.go	Updates show help text.
internal/cmd/root.go	Updates root command messaging.
internal/cmd/root_test.go	Tests public command visibility.
internal/cmd/invoke.go	Adds Voice Live invocation guidance.
internal/cmd/invoke_test.go	Tests voice invocation rejection.
internal/cmd/init.go	Publicizes prompt-voice initialization.
internal/cmd/init_test.go	Tests public voice flags.
internal/cmd/init_from_templates_helpers.go	Exposes the voice picker option.
internal/cmd/init_from_templates_helpers_test.go	Tests the public picker behavior.
internal/cmd/deploy.go	Updates deployment help text.
internal/cmd/delete.go	Updates deletion help text.
internal/cmd/agent_endpoint.go	Parses and validates voice endpoints.
internal/cmd/agent_endpoint_test.go	Tests voice endpoint parsing.
extension.yaml	Advertises voice support and initialization.

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 6
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

Public-preview scope confirmation remains unresolved, and the exposed initializer conflicts with the documented preferred authoring kind.

Review details

Suppressed comments (1)

cli/azd/extensions/azure.ai.agents/internal/cmd/init.go:1247

• --kind prompt-voice is now the only public init selector and still generates kind: prompt-voice, but the current schema and README identify kind: voice as the preferred authoring kind and reserve prompt-voice for compatibility (schemas/azure.ai.agent.json:47-50, README.md:243-246). New public-preview projects therefore start on the compatibility alias. Please accept/expose voice (while retaining the old alias if needed) and synthesize the canonical kind, or explicitly reconcile the public documentation before launch.

Use --kind prompt-voice to initialize a managed prompt voice agent without
source code or container scaffolding.

• Files reviewed: 17/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Prompt-voice help claims --model-deployment takes precedence even though that input is silently ignored.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 13/13 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Explicit-protocol invocation can bypass voice guidance, while schema and validation paths still expose contradictory legacy authoring guidance.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

cli/azd/extensions/azure.ai.agents/internal/cmd/invoke.go:1241

• Deployed-name matching is still enabled only when --protocol is omitted. If a voice service's deployed name differs from its azure.yaml key, invoke --protocol responses <deployed-name> ... misses the service, takes the direct-name fallback, and bypasses the new portal guidance; the added deployed-name test does not exercise this production branch. Perform voice-aware deployed-name matching for explicit remote protocols too, while preserving fallback for genuinely unmatched direct names.

	if a.flags.protocol == "" {
		resolutionOptions = append(
			resolutionOptions,
			withDeployedProtocolEndpoints(),
			withDeployedAgentNameLookup(),

• Files reviewed: 27/27 changed files
• Comments generated: 2
• Review effort level: Balanced

[JianW (v1212)]

Rebase completed at a7c610e onto main 57ca1f6, including #9948 71ab929. Local full tests/vet/build/spelling passed; GitHub tests/lint/coverage passed. Hosted authoring guidance now reflects #9948 requiring conversationEngine; kind aliases and scaffold kind are unchanged. ADO builds 6823270 (extension) and 6823271 (live) were requested and are queued for merge SHA 2f400e5, whose parents match these exact revisions; no pass is claimed yet. Two new Copilot findings concern the dependency implementation (target_agent-only migration diagnostic and schema legacy property descriptions/enums); they remain unresolved for dependency review, not silently changed in this exposure PR. The #9948 branch was not modified.

[Copilot]

🔵 Needs a closer look

Explicit-protocol invocation can bypass voice guidance when the deployed agent name differs from its service name.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

cli/azd/extensions/azure.ai.agents/internal/cmd/invoke.go:1235

• When --protocol is explicit, the deployed-name lookup below is omitted. A positional deployed voice name therefore misses the service-name lookup and is treated as an unmatched direct target, so azd ai agent invoke --protocol responses <deployed-voice-name> ... bypasses this voice guard and attempts HTTP invocation. Keep deployed-name matching enabled independently of protocol endpoint auto-detection, while preserving fallback for truly unmatched direct names, and add a command-level regression for this case.

• Files reviewed: 28/28 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[JianW (v1212)]

Addressed both approved review findings in ba9b880: target_agent-only configurations now receive conversation_engine migration guidance; schema modelType options and removed targetAgent annotations match the existing rejection contract. Added parser/schema regressions; full local Windows tests, vet, build, go-fix diff, documentation schema checks and spelling passed. Both review threads resolved. GitHub tests/lint/coverage passed. ADO 6823861/6823862 remain queued: timeline shows actual build/live jobs pending with no startTime (only agentless tagging completed). No current ADO/live success is claimed; merge still requires CI completion, #9948 merge/cleanup and maintainer approval.

[Copilot]

🟡 Changes recommended

A new line violates the enforced Go line-length limit, and the updated model help omits supported prompt-agent behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

cli/azd/extensions/azure.ai.agents/internal/cmd/root.go:19

• This line is 131 columns after tab expansion, exceeding the repository's 125-column lll limit (cli/azd/AGENTS.md:118-130) and will fail lint. Split the format string across lines.

			"Ship prompt, hosted, and voice agents with Microsoft Foundry from your terminal. %s", color.YellowString("(Preview)"),

• Files reviewed: 28/28 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Explicit-protocol invocation can bypass voice guidance, and one added Go line violates the enforced line-length limit.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

cli/azd/extensions/azure.ai.agents/internal/cmd/invoke.go:1276

• When --protocol is explicit, withDeployedAgentNameLookup is skipped below. A positional deployed name (AGENT_<SERVICE>_NAME) then misses the service-key lookup, the direct-name fallback swallows that miss, and this voice guard never sees the known voice service. The command consequently attempts an HTTP invocation instead of returning portal guidance. Please perform a best-effort deployed-name match for this path while retaining fallback for names that truly do not map to the project, and cover --protocol ... <deployed-voice-name> in the regression test.

cli/azd/extensions/azure.ai.agents/internal/cmd/root.go:19

• This newly added line is 131 columns wide after tab expansion, exceeding the repository's enforced 125-column lll limit (cli/azd/AGENTS.md:118-129). Split the message into concatenated string literals.

			"Ship prompt, hosted, and voice agents with Microsoft Foundry from your terminal. %s", color.YellowString("(Preview)"),

• Files reviewed: 28/28 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[JianW (v1212)]

Real cloud bug bash results — ae6e8e4 (2026-09-11)

Tested the rebuilt Windows PR bundle with no voice CLI opt-in, in an isolated azd config and the existing West US 2 test project. No source changes made.

• Scenarios 1–5: init, deploy, active show, portal invoke guidance, and real PCM input → transcription → completed response → nonempty output PCM passed. Output bytes: managed 102400; BYOM realtime 70400; BYOM cascaded 102400; hosted wrapper 121800; advanced managed 128400.
• Hosted sample's original /help and audio smoke scripts also passed.
• Advanced settings confirmed in service session: resolved persona/greeting, semantic VAD and configured voice; no session overrides were used for successful audio probes.
• Scenario 6 advanced BYOM realtime: intermittent, NOT a clean pass. Three sessions produced failure / success / failure. Failures: byom_realtime_connection_error, upstream status 400 / Invalid response status. Root cause not established. Advanced cascaded variant passed separately (83400 output PCM bytes); it does not erase realtime failures.
• Twilio binding: created active, redeploy succeeded, ETag-conditional deletion succeeded and subsequent GET returned 404. Real PSTN calling/two-way audio was NOT tested; binding state is not call success.
• Plan corrections: explicitly install connections/toolboxes as well as inspector/projects; read telephony ETag from response headers when absent from JSON body. Test phone number updated/confirmed in the internal plan, not posted here.
• All eight created agents, three test model deployments and the new binding were removed; original demo/binding preserved. No shared azd down.

Coverage gaps: reused existing project with --project-id, so fresh-project provision/RBAC was NOT tested. Portal/Dashboard manual UI, microphone listening quality, interactive picker and actual phone calls were NOT executed (no interactive/dialer tools available). Overall plan is therefore not fully passed.

Updated internal bug bash ZIP includes SCENARIO-RESULTS.md and build provenance for ae6e8e4, without auth/project state or raw resource logs. Detailed evidence retained locally for service-team diagnosis. No blanket merge-readiness claim is made from these results.

[JianW (v1212)]

Follow-up bug bash validation — ae6e8e4

• Closed the fresh-project gap for managed voice: init without project-id, azd provision in West US 2, deploy, active show, invoke portal guidance and real audio all passed. Audio returned 108800 PCM bytes. No manual IAM correction was needed for these operations (not an exhaustive IAM audit).
• Investigated intermittent BYOM Realtime 400 using a newly provisioned account/project and one gpt-realtime deployment (2025-08-28, GlobalStandard capacity 1). Fixed interleaved matrix: basic 2/3 successful, advanced 2/3, advanced without greeting 1/3, audio-only advanced 1/3. Total 6 successes / 12; failures precede session creation and input audio.
• Direct Azure OpenAI control, bypassing azd and Voice Agent, only waited for session.created at /openai/v1/realtime. Fixed 6 attempts: 2 successes, 4 HTTP 400 handshake failures. This disproves attribution solely to advanced settings or this CLI PR; exact upstream root cause remains unestablished and needs service-team investigation. Direct response bodies/correlation headers were not captured, so this is not proof of an identical backend exception.
• No retry-until-green, feature changes, session configuration overrides or speculative product fixes. All outcomes retained locally. Five follow-up agents and the exclusive test resource group/model were deleted; group existence verified false.
• Actual PSTN call/two-way listening and Portal/Dashboard manual UI are still NOT tested: no browser/interactive-tester/dialer tools are exposed, and no Twilio environment credentials are available. Shared connection secrets were not extracted; API binding/WebSocket success is not phone success.

The internal ZIP and SCENARIO-RESULTS.md have been updated (same ae6e8e4 binary). Overall bug bash is not a complete pass: upstream Realtime stability and human/UI/phone validation remain open. PR source remains unchanged.