Recipe: Thinking and Reasoning

Goal

Use provider-appropriate thinking configuration for deeper reasoning.

Example

from doc_processing_toolkit import Agent

agent = Agent(
    model="claude-sonnet-4-5",
    instructions="Think carefully before answering.",
    thinking={"budget_tokens": 10000},
)

result = await agent.run("What is 7 multiplied by 8?")
print(result.output)
print(result.reasoning_tokens)   # a SUBSET of result.output_tokens — already billed
print(result.reasoning_content)  # the thinking text, or the summary the provider returned

Both fields are populated on every provider and every run shape — with or without local tools, streaming or not. See Thinking tokens in results.

Adaptive thinking example (Anthropic-compatible models):

agent = Agent(
    model="claude-opus-4-7",
    instructions="Think carefully before answering.",
    thinking={"type": "adaptive"},
    effort_config="medium",
)

Turning Claude thinking off (0.5.2). What is sent depends on the model's registry row, and a model that cannot turn thinking off runs adaptive thinking with a warning; see Turning thinking off:

agent = Agent(
    model="claude-sonnet-5",
    instructions="Answer directly.",
    thinking={"type": "disabled"},
)

OpenAI reasoning-effort style example:

agent = Agent(
    model="gpt-5.2-pro",
    instructions="Think carefully before answering.",
    thinking={"effort": "high"},
)

OpenAI pro-mode example (GPT-5.6 models only — pro-grade reasoning at standard token rates; effort must be at least "medium"):

agent = Agent(
    model="gpt-5.6-sol",
    instructions="Think carefully before answering.",
    thinking={"effort": "high", "mode": "pro"},
)

Google thinking-level style example:

agent = Agent(
    model="gemini-3-flash-preview",
    instructions="Think carefully and then respond.",
    thinking_level="high",
)

Alternatively, the universal thinking parameter also works for Google (for both budget_tokens and level keys):

agent = Agent(
    model="gemini-3-flash-preview",
    instructions="Think carefully and then respond.",
    thinking={"budget_tokens": 10000},
)

What to validate

• output correctness
• reasoning fields are present when returned by provider
• iteration behavior remains within configured limits when tools are enabled

Notes

• Thinking configuration semantics differ by provider and model generation.
• Validate model support for adaptive/effort/level options before rollout.

Test sources

• tests/e2e/test_agent_e2e.py (test_thinking_with_tools, test_thinking_with_structured_output, test_adaptive_thinking_with_structured_output, test_adaptive_thinking_with_tools)
• tests/integration/test_anthropic_function_calling.py (test_tools_with_thinking, test_tools_with_adaptive_thinking)
• tests/integration/test_combination_openai.py (reasoning + built-in/custom combinations)
• tests/integration/test_combination_google.py (thinking + media/tool combinations)