docs: explain model capability overrides

sdk/guides/llm-reasoning.mdx

@@ -9,13 +9,52 @@
 
 This guide demonstrates two provider-specific approaches:
 1. **Anthropic Extended Thinking** - Claude's thinking blocks for complex reasoning
 2. **OpenAI Reasoning via Responses API** - GPT's reasoning effort parameter
 
+## Configure New Or Proxied Models
+
+Use `reasoning_effort` as the provider-neutral reasoning control. Common values include `"none"`, `"minimal"`,
+`"low"`, `"medium"`, `"high"`, `"xhigh"`, and `"max"`. Supported values depend on the model and provider. The SDK
+passes the value to LiteLLM, which translates it to the provider's request format.
+
+By default, the SDK resolves reasoning, sampling, prompt caching, and endpoint support from LiteLLM model metadata.
+For a gateway alias, provide the underlying model name so capability discovery does not depend on the alias:
+
+```python icon="python" wrap
+llm = LLM(
+    model="litellm_proxy/customer-sonnet",
+    model_canonical_name="anthropic/claude-sonnet-5",
+    reasoning_effort="high",
+)
+```
+
+Adaptive-thinking models use `reasoning_effort`; the SDK does not send a legacy manual `thinking` block for them.
+`extended_thinking_budget` remains available only for models confirmed to use manual extended thinking.
+
+If a custom gateway cannot expose model metadata, override only the missing capabilities:
+
+```python icon="python" wrap
+llm = LLM(
+    model="litellm_proxy/customer-sonnet",
+    reasoning_effort="high",
+    api_mode="chat",
+    capability_overrides={
+        "supports_reasoning_effort": True,
+        "thinking_mode": "adaptive",
+        "supports_sampling_params": False,
+        "supports_prompt_cache": True,
+    },
+)
+```
+
+`api_mode` accepts `"auto"` (the default), `"chat"`, or `"responses"`. Explicit capability overrides take precedence
+over gateway metadata, local LiteLLM metadata, and SDK fallbacks.
+
 ## Anthropic Extended Thinking
 
 > A ready-to-run example is available [here](#ready-to-run-example-antrophic)!
 
 Anthropic's Claude models support extended thinking, which allows you to access the model's internal reasoning process
 through thinking blocks. This is useful for understanding how Claude approaches complex problems step-by-step.
 
 ### How It Works
@@ -26,12 +65,12 @@
 def show_thinking(event: Event):
     if isinstance(event, LLMConvertibleEvent):
         message = event.to_llm_message()
         if hasattr(message, "thinking_blocks") and message.thinking_blocks:
             print(f"🧠 Found {len(message.thinking_blocks)} thinking blocks")
             for block in message.thinking_blocks:
                 if isinstance(block, RedactedThinkingBlock):
                     print(f"Redacted: {block.data}")
                 elif isinstance(block, ThinkingBlock):
                     print(f"Thinking: {block.thinking}")
 
 conversation = Conversation(agent=agent, callbacks=[show_thinking])
@@ -139,7 +178,7 @@
 Configure the LLM with the `reasoning_effort` parameter to enable reasoning:
 
 ```python focus={5} icon="python" wrap
 llm = LLM(
     model="openhands/gpt-5-codex",
     api_key=SecretStr(api_key),
     base_url=base_url,
@@ -148,8 +187,8 @@
 )
 ```
 
-The `reasoning_effort` parameter can be set to `"none"`, `"low"`, `"medium"`, or `"high"` to control the amount of
-reasoning performed by the model.
+The values supported by `reasoning_effort` depend on the selected model. For example, many models accept `"low"`,
+`"medium"`, or `"high"`, while newer models may also accept values such as `"minimal"`, `"xhigh"`, or `"max"`.
 
 Then capture reasoning traces in your callback:
 
@@ -164,7 +203,7 @@
 
 The OpenAI Responses API provides reasoning traces that show how the model approached the problem.
 These traces are available in the LLM messages and can be inspected to understand the model's decision-making process.
 Unlike Anthropic's thinking blocks, OpenAI's reasoning is more tightly integrated with the response generation process.
 
 ### Ready-to-run Example OpenAI