[Docs]: reasoning_mode is undocumented, and two of its five accepted values fail at request time

[dg-edcharbeneau]

Affected page or section

• https://developers.deepgram.com/docs/voice-agent-llm-models
• https://developers.deepgram.com/docs/voice-agent-settings
• also: generated types GroqThinkProviderReasoningMode / OpenAiThinkProviderReasoningMode

What is unclear or wrong?

Two related problems with the same setting.

1. reasoning_mode is entirely undocumented

It appears on neither voice-agent-llm-models nor voice-agent-settings. The only way to discover it is by reading generated SDK types. Neither page mentions reasoning models at all, or that they currently fail on aws_bedrock (see linked issue).

2. The accepted value set is wider than the set that works

Both generated types allow the same five values:

GroqThinkProviderReasoningMode   = Union[Literal["none","minimal","low","medium","high"], Any]
OpenAiThinkProviderReasoningMode = Union[Literal["none","minimal","low","medium","high"], Any]

Against groq + openai/gpt-oss-20b, two of the five fail at request time:

reasoning_mode=(omitted)    REPLIED 'Paris.'
reasoning_mode=none         FAILED THINK_REQUEST_FAILED, FAILED_TO_THINK
reasoning_mode=minimal      FAILED THINK_REQUEST_FAILED, FAILED_TO_THINK
reasoning_mode=low          REPLIED 'Paris.'
reasoning_mode=medium       REPLIED 'Paris.'
reasoning_mode=high         REPLIED 'Paris'

So none and minimal are advertised by the type system and rejected by the service. A user reaching for none — the most intuitive choice for "I don't want reasoning tokens, just answer me" — gets a failed turn with no indication the value itself is the problem.

Whether the fix is docs or service behavior depends on intent: if none/minimal are meant to be unsupported for this model they should be removed from the schema; if they're meant to work, that's a service bug. Either way the current combination is a trap.

Suggested change

1. Document reasoning_mode on voice-agent-settings, including which think providers support it (currently open_ai and groq; not aws_bedrock).
2. State per-provider / per-model which values are valid, rather than presenting a flat five-value enum that is only partly usable.
3. Either drop none and minimal from the schema for models that reject them, or fix the service to honor them. If they're rejected, the error should name the offending value instead of the generic THINK_REQUEST_FAILED.
4. Add a note that reasoning models are not currently usable on aws_bedrock, and that reasoning_mode is not accepted there — sending it rejects the entire Settings message with UNPARSABLE_CLIENT_MESSAGE.

Example code

# Reproduce the value-set discrepancy — groq only, no AWS credentials needed.
provider = {"type": "groq", "model": "openai/gpt-oss-20b", "reasoning_mode": "none"}
settings = {
    "type": "Settings",
    "audio": {
        "input": {"encoding": "linear16", "sample_rate": 24000},
        "output": {"encoding": "linear16", "sample_rate": 24000},
    },
    "agent": {
        "listen": {"provider": {"type": "deepgram", "model": "flux-general-en", "version": "v2"}},
        "think": {"provider": provider, "prompt": "You are a helpful assistant. Keep responses brief."},
        "speak": {"provider": {"type": "deepgram", "model": "flux-alexis-en"}},
    },
}
# Send Settings, wait for SettingsApplied, then InjectUserMessage
# "What is the capital of France?".
#   reasoning_mode="none"    -> THINK_REQUEST_FAILED, FAILED_TO_THINK
#   reasoning_mode="minimal" -> THINK_REQUEST_FAILED, FAILED_TO_THINK
#   reasoning_mode="low" | "medium" | "high" -> replies normally
#   omitted                                  -> replies normally

SDK parity

Relevant. reasoning_mode is present on ThinkSettingsV1Provider_OpenAi and ThinkSettingsV1Provider_Groq and absent from ThinkSettingsV1Provider_AwsBedrock, which is consistent with the service rejecting it there — but none of that is documented anywhere a user would look.

---

Verification note: the value-by-value table above was produced by a direct run against wss://agent.deepgram.com/v1/agent/converse on 2026-08-11 using a raw websockets client that imports no Deepgram SDK code, on Python 3.13.14. Each value was tested in a separate connection, in the order shown.

---

Related: #759 — reasoning_mode is the workaround that does not exist on aws_bedrock; sending it there rejects the whole Settings message.