[DOCS] Use `max_thinking_tokens` first-class property in examples instead of environment variables

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/python#claudeagentoptions - https://platform.claude.com/docs/en/agent-sdk/python#example---include_partial_messagespy

Section/Topic

The ClaudeAgentOptions configuration examples, specifically regarding how to set thinking budgets for models with extended thinking capabilities.

Current Documentation

In the Python SDK examples (such as include_partial_messages.py), the documentation demonstrates setting the thinking budget via an environment variable string inside the env dictionary:

options = ClaudeAgentOptions(
    include_partial_messages=True,
    model="claude-sonnet-4-5",
    max_turns=2,
    env={
        "MAX_THINKING_TOKENS": "8000",
    },
)

However, the ClaudeAgentOptions class definition also lists a dedicated property:
max_thinking_tokens: int | None = None

What's Wrong or Missing?

There is a functional redundancy that leads to confusing "best practice" guidance:

1. Type Safety: The env approach uses a string-mapped dictionary, bypassing the type-checking and IDE autocompletion benefits of the dedicated max_thinking_tokens integer field.
2. Conflicting Patterns: Users may be unsure which method takes precedence or why the environment variable method is being used in an SDK context where programmatic options are preferred.
3. Clarity: First-class properties follow better SDK design patterns than passing environment variables into a dictionary to be parsed by the underlying CLI.

Suggested Improvement

Update all Python SDK examples to use the max_thinking_tokens property directly.

Suggested Text Change:

options = ClaudeAgentOptions(
    include_partial_messages=True,
    model="claude-sonnet-4-5",
    max_turns=2,
    max_thinking_tokens=8000,
)

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: The max_thinking_tokens field is correctly defined in the API reference section of https://platform.claude.com/docs/en/agent-sdk/python but is underutilized in the "Examples" and "Quick Start" sections.
• Consistency: The TypeScript SDK documentation generally uses the first-class maxThinkingTokens property; the Python documentation should maintain parity by using its equivalent field.