fix(voice): support custom OpenAI TTS voice IDs

[sylvesterkaczmarek]

Summary

Allow TTSModelSettings.voice to represent the custom voice objects currently supported by the OpenAI speech API.

The OpenAI speech API accepts either a built-in voice name or a custom voice reference such as {"id": "voice_1234"}. OpenAITTSModel already forwards the configured voice directly to audio.speech, but the Agents SDK's public TTSVoice type only represented built-in literals, so valid custom voice configurations were rejected by static type checkers.

Fix

• add a typed TTSCustomVoice shape with the required id field
• widen TTSVoice to include that custom voice shape while preserving the existing built-in literals
• export TTSCustomVoice from agents.voice
• keep runtime request construction unchanged

This also aligns the voice pipeline with the existing Realtime API surface, which already supports custom voice objects.

Test plan

Updated the existing TTS voice type-contract coverage to verify both the current built-in voice set and a custom voice_1234 reference accepted through TTSModelSettings.

The branch is based directly on current main at e26a7d8aed59141ee13fb0a1fa16445017b0ccf1 and is 0 commits behind it.

Risk

Very low. Existing built-in voice values and runtime behavior are unchanged. This only widens the public type contract to include a request shape already supported by the underlying OpenAI speech client.

Issue number

None. Found while checking voice type parity with the current OpenAI speech API.

[seratch]

The underlying type-contract gap is valid: the Speech API supports custom voice objects with an id, and OpenAITTSModel already forwards TTSModelSettings.voice unchanged, so widening TTSVoice is the right narrow fix.

Before merge, please make the regression test exercise the public import path by importing TTSCustomVoice, TTSModelSettings, and TTSVoice from agents.voice. Please also assert that TTSCustomVoice is included in agents.voice.__all__, or add equivalent public API coverage. The current test imports from agents.voice.model, so it does not protect the new intended export. Once that is covered and CI is green, this should be ready for another review.

[sylvesterkaczmarek]

The underlying type-contract gap is valid: the Speech API supports custom voice objects with an id, and OpenAITTSModel already forwards TTSModelSettings.voice unchanged, so widening TTSVoice is the right narrow fix.

Before merge, please make the regression test exercise the public import path by importing TTSCustomVoice, TTSModelSettings, and TTSVoice from agents.voice. Please also assert that TTSCustomVoice is included in agents.voice.__all__, or add equivalent public API coverage. The current test imports from agents.voice.model, so it does not protect the new intended export. Once that is covered and CI is green, this should be ready for another review.

Addressed. The regression now imports TTSCustomVoice, TTSModelSettings, and TTSVoice through the public agents.voice API and explicitly verifies that TTSCustomVoice is included in agents.voice.all. Ready for re-review once CI completes.