Setting the file. One moment.
Subchapter 53.66
foundry-agent/create/references/voice-agent-settings.mdMarkdown6 KBView on GitHub
For requested/preserved YAML settings. Use kind: voice; preserve unrelated fields.
| Owner | Settings |
|---|
| Prompt Voice | Model, instructions, inputs, audio, tools, behavior, data, telephony |
| Hosted wrapper | Audio, voice, behavior, store only |
| Hosted target | Model, instructions, tools, logic |
structuredInputs: { persona: { description: Persona, defaultValue: Ada } }
audio:
input:
format: { type: audio/pcm, rate: 24000 }
noiseReduction: { type: near_field }
echoCancellation: { type: server_echo_cancellation, channels: 1 }
transcription: { model: azure-speech, language: en-US, prompt: Terms }
turnDetection: { type: server_vad, threshold: 0.6, prefixPaddingMs: 300,
silenceDurationMs: 500, createResponse: true, eagerness: <value>,
speechDurationMs: 120, removeFillerWords: true, interruptResponse: true,
languages: [en-US], autoTruncate: true }
output:
format: { type: audio/pcm, rate: 24000 }
voice: { type: azure-standard, name: <voice-name>,
style: cheerful, pitch: "+0Hz", rate: "+0%", locale: en-US, volume: "+0%" }
speed: 1.1defaultValue maps to wire default_value. Defaults: PCM/24000, server_vad, azure-speech, [audio], azd voice.
| Setting | Values / constraints |
|---|---|
audio.*.format | type: audio/pcm, audio/pcmu, audio/pcma; rate: positive integer. G.711 pcmu/pcma may omit rate. |
audio.input.turnDetection | Known type values: server_vad, semantic_vad, azure_semantic_vad (schema is open, not an enum). threshold: >0 and <=1. prefixPaddingMs, silenceDurationMs, speechDurationMs: nonnegative integers. createResponse, removeFillerWords, interruptResponse, autoTruncate: booleans. languages: string array. Known service eagerness: auto, low, medium, high (schema is open). |
audio.input.noiseReduction | Nonblank type; known values: near_field, far_field, azure_deep_noise_suppression (schema is open). |
audio.input.transcription | model, language, prompt: strings. Known phrase-compatible models: azure-speech, azure-fast-transcription; include: [item.input_audio_transcription.phrases] requires one. Do not author phraseList; azd doesn’t support it. |
audio.output.voice | Nested shape requires nonblank type and name; source-known types: azure-standard / azure_standard, openai. Keep the canonical nested example above. |
audio.output.speed | 0.25-1.5. |
| Responses | outputModalities must be nonempty; known values: audio, text, animation, avatar. maxOutputTokens: integer 1-2147483647 or inf. parallelToolCalls is unsupported and rejected. |
| Telephony | Providers: twilio, acs; each binding requires provider, identifier, connection. Twilio identifier: +<E.164>; ACS: 28:orgid:<guid> or 4:+<E.164>. |
greeting: { type: template, text: "Hello {{persona}}" }
outputModalities: [audio, text]
avatar: { type: video_avatar, character: lisa, output_protocol: webrtc }
tools: [{ type: system, name: end_conversation }]
toolChoice: auto
maxOutputTokens: inf # or integer 1-2147483647
include: [item.input_audio_transcription.phrases]Preserve opaque maps.
store defaults false; true persists transcript, events, audio. Preserve explicit values.
Twilio: If a connection is supplied, show/list without credentials and verify kind Twilio, auth ApiKey, and known SID target. Otherwise resolve name (default telephony-twilio), SID, token availability, and owned voice-capable E.164 number; create before deployment:
AZURE_DEV_USER_AGENT=microsoft_foundry_skill azd ai connection create "$CONNECTION_NAME" \
--kind Twilio --target "$TWILIO_ACCOUNT_SID" --auth-type api-key \
--key "$TWILIO_AUTH_TOKEN" --project-endpoint "$AZURE_AI_PROJECT_ENDPOINT" --no-prompt$env:AZURE_DEV_USER_AGENT = "microsoft_foundry_skill"
azd ai connection create $ConnectionName `
--kind Twilio --target $env:TWILIO_ACCOUNT_SID --auth-type api-key `
--key $env:TWILIO_AUTH_TOKEN --project-endpoint $env:AZURE_AI_PROJECT_ENDPOINT --no-promptArguments can be locally visible; use the portal if concerned. Verify via connection show ... --output json, never --show-credentials. Bind:
telephony:
bindings:
- provider: twilio
identifier: "+14255550123"
connection: telephony-twilioToken: process environment only, never YAML/chat/summaries. Connection must preexist deploy. azd doesn’t create accounts, buy/discover numbers, or prove routing; test a call.
For an explicit Teams Phone extensibility (TPE) (opens in a new tab) or ACS request, reuse a supplied TPE/ACS connection only after checking category AzureCommunicationServices, ACS endpoint, and available metadata.ResourceId. The azd compatibility authoring value is provider: acs; bind a TPE resource account:
telephony:
bindings:
- provider: acs
identifier: "28:orgid:<resource-account-object-id>"
connection: <acs-connection-name>4:+<E.164> is a separate ACS-purchased-number route, not TPE. If no compatible TPE/ACS connection exists, don’t create it with azd or automate RBAC/Event Grid/TPE setup. Use the guide (opens in a new tab) and Foundry portal → Voice Agent → Channels → Phone numbers → Add a number → Microsoft Teams; the portal coordinates the ACS connection, project identity, TPE resource account, secure webhook/Event Grid, and TPE telephony binding. Test a real call; WebSocket smoke doesn’t validate telephony.