foundry-agent/create/references/voice-agent-common.md
Voice Agent Common Invariants
Rules shared by Prompt Voice and Hosted Voice services in azure.yaml.
Classification
- Author and maintain Voice Agent services with canonical
kind: voice. - Silently recognize existing
kind: prompt-voicemanifests as Voice Agents for compatibility, and normalize them tokind: voicewhen editing. - Prompt Voice declares
modelwithmodelType: managedorself_deployed. - Hosted Voice uses a managed Voice wrapper whose
conversationEnginenames a distinct hosted target. - A standalone
kind: hostedservice using rawinvocations_wsis not a managed Voice Agent.
Required Rules
- Place Voice fields directly under
services.<service-key>; never use a nestedconfig:block. - Declare exactly one engine:
- Prompt Voice:
modelTypeplusmodel.id. - Voice wrapper:
conversationEngine.
- Prompt Voice:
- Stop when both engines or neither engine are declared.
- Never use obsolete
modelType: hosted_agentortargetAgent. - Keep hosted target and Voice wrapper service keys and
namevalues distinct. - Preserve existing optional settings and omit optional fields the user did not request.
Lifecycle Boundaries
- Deploy Voice services with azd.
- Do not invoke a Voice service with
azd ai agent invoke. - Prompt Voice has no local container.
- Hosted target testing validates only its Voice Live Bridge handler; the Voice wrapper still requires end-to-end testing over the managed
voiceWebSocket.
Load only the selected subtype reference: