[DOCS] [Python Agent SDK] Hallucinated `thinking` attribute in `ClaudeAgentOptions` code snippets

Documentation Type

Unclear/confusing documentation

Documentation Location

• platform.claude.com/docs/en/agent-sdk/python - platform.claude.com/docs/en/build-with-claude/extended-thinking - platform.claude.com/docs/en/about-claude/models/extended-thinking-models

Section/Topic

Python SDK code snippets demonstrating the enabling of "Extended Thinking" within the Claude Agent SDK (specifically the ClaudeAgentOptions configuration).

Current Documentation

The documentation provides Python snippets for the Agent SDK that use a dictionary-based thinking parameter:

# Example from docs/en/build-with-claude/extended-thinking
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[...]
)

What's Wrong or Missing?

The thinking dictionary attribute does not exist in the Python Agent SDK's ClaudeAgentOptions class.

According to the SDK source code (src/claude_agent_sdk/types.py), the class expects a flat integer parameter named max_thinking_tokens. Using the code as currently documented in the Platform guides will result in a TypeError: unexpected keyword argument 'thinking' because the SDK is a wrapper around the CLI, which handles the "enabled" state internally when the token count is provided.

Suggested Improvement

Update all Python Agent SDK snippets to use the max_thinking_tokens attribute with an integer value instead of the thinking dictionary.

Corrected Example:

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    max_thinking_tokens=10000, # Use the correct integer attribute
    model="claude-sonnet-4-5"
)

async for message in query(prompt="Your prompt", options=options):
    print(message)

Impact

High - Prevents users from using a feature

Additional Context

• Source Code Evidence: In src/claude_agent_sdk/types.py, the ClaudeAgentOptions dataclass is defined as:

``python
@dataclass
class ClaudeAgentOptions:
# ... other fields
max_thinking_tokens: int | None = None
# There is no 'thinking' field defined here.
``

• Internal Mapping: The SDK internally maps max_thinking_tokens to the CLI flag --max-thinking-tokens in src/claude_agent_sdk/_internal/transport/subprocess_cli.py.
• Confusion Source: The documentation appears to be accidentally copy-pasting the schema from the base Anthropic Client SDK (which does use the thinking dictionary) into the Claude Agent SDK sections.