Context
The default TTS engine/voice is changing to ElevenLabs "Mark". Our docs currently teach a pattern that only works while the default engine is gcloud.
What breaks
A voice can be specified three ways:
| Form |
Example |
| Bare name |
"en-US-Neural2-F" — a gcloud voice, no engine |
| Explicit fields |
voice="josh", engine="elevenlabs", model="eleven_turbo_v2_5" |
| Combined string |
"elevenlabs.josh:eleven_turbo_v2_5" (engine.voice:model) |
The bare form resolves today only because gcloud is the default engine. Once the default is ElevenLabs, a bare gcloud voice name has no engine to resolve against and fails.
The Agents SDK guide leads with exactly that pattern — the first example under Languages and voices is:
agent.add_language("English", "en-US", "en-US-Neural2-F") # simpleSo the docs are currently pointing people at the thing that is about to break.
Requested changes
1. Qualify every voice example. Use engine.voice or engine.voice:model throughout — elevenlabs.mark, gcloud.en-US-Neural2-F. If a bare-name example is kept, label it explicitly as "uses the default engine, which can change."
2. Document the default change. Dated note plus a one-line migration: if you passed a bare gcloud voice name, prefix it with gcloud. or set engine explicitly.
3. Document languages vs multilingual. They are mutually exclusive — if both are present the server uses multilingual and ignores the languages array. This is stated in the Agents SDK guide (voice_language_media) but I could not find it in the SWML reference or on the docs site. Also worth stating when not to use the languages array at all: a single-language agent should just set the voice.
Blast radius
Small — bare gcloud voice names appear to be uncommon in customer code. The concern is that the docs are the thing directing people to the pattern.
Source
Raised by Anthony Minessale while changing the default voice; verified against the SWML cheatsheet (languages[].voice: elevenlabs.rachel, already qualified) and the Agents SDK guide voice_language_media chapter.
Context
The default TTS engine/voice is changing to ElevenLabs "Mark". Our docs currently teach a pattern that only works while the default engine is gcloud.
What breaks
A voice can be specified three ways:
"en-US-Neural2-F"— a gcloud voice, no enginevoice="josh", engine="elevenlabs", model="eleven_turbo_v2_5""elevenlabs.josh:eleven_turbo_v2_5"(engine.voice:model)The bare form resolves today only because gcloud is the default engine. Once the default is ElevenLabs, a bare gcloud voice name has no engine to resolve against and fails.
The Agents SDK guide leads with exactly that pattern — the first example under Languages and voices is:
So the docs are currently pointing people at the thing that is about to break.
Requested changes
1. Qualify every voice example. Use
engine.voiceorengine.voice:modelthroughout —elevenlabs.mark,gcloud.en-US-Neural2-F. If a bare-name example is kept, label it explicitly as "uses the default engine, which can change."2. Document the default change. Dated note plus a one-line migration: if you passed a bare gcloud voice name, prefix it with
gcloud.or setengineexplicitly.3. Document
languagesvs multilingual. They are mutually exclusive — if both are present the server usesmultilingualand ignores thelanguagesarray. This is stated in the Agents SDK guide (voice_language_media) but I could not find it in the SWML reference or on the docs site. Also worth stating when not to use thelanguagesarray at all: a single-language agent should just set the voice.Blast radius
Small — bare gcloud voice names appear to be uncommon in customer code. The concern is that the docs are the thing directing people to the pattern.
Source
Raised by Anthony Minessale while changing the default voice; verified against the SWML cheatsheet (
languages[].voice: elevenlabs.rachel, already qualified) and the Agents SDK guidevoice_language_mediachapter.