Add Anthropic Extended Thinking and Streaming Support

[damithsenanayake]

Summary

This PR adds support for Anthropic's Extended Thinking feature and Interleaved Thinking (beta) for Claude models in the ADK Python SDK. The implementation enables developers to use Claude's reasoning capabilities with thinking block signatures and multi-step tool reasoning, while maintaining full compatibility with existing code.

Key Features

Extended Thinking Support

• Converts ADK ThinkingConfig to Anthropic API format
• Supports disabled (0) and explicit (>0) budget values
• Raises ValueError for unlimited budget (-1) as it's not supported by Claude
• Works in both streaming and non-streaming modes
• Parses thinking blocks as Part(thought=True, thought_signature=...) in standard GenAI format
• Preserves cryptographic signatures from thinking blocks

Interleaved Thinking (Beta)

• Enables Claude to reason between tool calls rather than thinking once upfront
• Opt-in via enable_interleaved_thinking=True configuration
• Sends anthropic-beta: interleaved-thinking-2025-05-14 header when enabled
• Allows more sophisticated multi-step reasoning with tools
• Thinking blocks automatically preserved in assistant message history

Improved Streaming

• Migrated to AsyncAnthropicVertex for async streaming support
• Implements thought suppression pattern to prevent UI fragmentation
• Streaming controlled exclusively by stream parameter
• Converts Anthropic streaming events to ADK LlmResponse format
• Final message built from complete content blocks to preserve signatures

Backward Compatibility

• 100% backward compatible - no breaking changes
• All existing tests pass
• Non-streaming mode supports thinking blocks
• Thinking blocks ordering preserved (must come first per Anthropic API requirement)
• Interleaved thinking disabled by default

Implementation Details

Core Changes

File: src/google/adk/models/anthropic_llm.py

1. Import AsyncAnthropicVertex (line 33)

   • Added async client for streaming support

2. Enhanced content_to_message_param() (lines 142-179)

   • Separates thinking blocks from other content blocks
   • Ensures thinking blocks come FIRST (Anthropic API requirement)

3. Enhanced content_block_to_part() (lines 182-219)

   • Detects thinking blocks via thinking attribute or type='thinking'
   • Extracts and preserves signature (base64-encoded bytes)
   • Returns Part(thought=True, thought_signature=signature) for thinking content
   • Logs signature presence for debugging

4. New streaming_event_to_llm_response() (lines 222-278)

   • Converts Anthropic streaming events to ADK format
   • Handles text_delta, thinking_delta, and message_delta events
   • Returns LlmResponse with proper partial=True flag

5. Rewritten generate_content_async() (lines 366-508)

   • Extracts and converts thinking config from ADK to Anthropic format
   • Raises ValueError for budget=-1 (unlimited not supported)
   • Applies budget directly (no minimum enforcement - handled by API)
   • Configures beta header for interleaved thinking when enabled
   • Streaming controlled only by stream parameter
   • Accumulates thinking deltas and yields as single block (prevents UI fragmentation)
   • Builds final response from final_message.content to preserve signatures
   • Passes thinking and extra_headers parameters to both streaming and non-streaming API calls

6. Added enable_interleaved_thinking field (line 360)

   • Boolean flag to enable interleaved thinking beta feature
   • Default: False (opt-in)

7. Updated _anthropic_client property (lines 510-524)

   • Changed from AnthropicVertex to AsyncAnthropicVertex

Test Coverage

Test Files (50 tests total):

1. test_anthropic_thinking.py (26 tests)

   • Budget validation (raises error on -1, accepts 0 and positive values)
   • Specific budget values (5000, 1024 minimum)
   • Thinking block parsing with signatures (base64-encoded)
   • Type-based thinking detection with signatures
   • No-config baseline testing
   • Streaming mode with thinking enabled
   • NEW: Interleaved thinking tests (10 tests):
     • Beta header NOT sent by default
     • Beta header sent in streaming mode when enabled
     • Beta header sent in non-streaming mode when enabled
     • Beta header only sent when thinking config is active
     • Thinking blocks preserved in assistant message history

2. test_anthropic_streaming.py (8 tests)

   • Event conversion (text_delta, thinking_delta, usage_delta)
   • Start/stop event handling
   • Event-to-response transformation

3. test_anthropic_llm.py (16 tests)

   • Existing tests continue to pass
   • No changes required

Code Quality

• Style: Google Python Style Guide compliant
• Formatting: Applied isort and pyink formatting
• Documentation: Comprehensive inline comments explaining logic
• Type Safety: Proper type hints and assertions
• Signature Handling: Proper base64 encoding/decoding for cryptographic signatures

Testing Results

tests/unittests/models/test_anthropic_llm.py ............ 16/16 PASSED
tests/unittests/models/test_anthropic_thinking.py ...... 26/26 PASSED
tests/unittests/models/test_anthropic_streaming.py .....  8/8 PASSED

Total: 50/50 tests PASSED

No regressions - all existing tests continue to pass.

Breaking Changes

None. This PR is 100% backward compatible.

Usage Examples

Basic Extended Thinking

from google.genai import types
from google.adk.models.anthropic_llm import Claude
from google.adk.agents import Agent

# Enable extended thinking with explicit budget
agent = Agent(
    model=Claude(
        model="claude-opus-4-1@20250805",
        max_tokens=4096
    ),
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            include_thoughts=True,
            thinking_budget=2048  # Explicit budget (min 1024)
        )
    )
)

# Disable thinking
config=types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(
        include_thoughts=True,
        thinking_budget=0  # Disabled
    )
)

Interleaved Thinking with Tool Use

# Enable interleaved thinking for multi-step tool reasoning
agent = Agent(
    model=Claude(
        model="claude-opus-4-1@20250805",
        max_tokens=4096,
        enable_interleaved_thinking=True  # Beta: reason between tool calls
    ),
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            include_thoughts=True,
            thinking_budget=2048
        )
    ),
    tools=[calculator_tool, database_tool]
)

Accessing Thinking Blocks

# Streaming mode (explicit control)
async for response in model.generate_content_async(request, stream=True):
    if response.content:
        for part in response.content.parts:
            if part.thought:
                # Access thinking block with signature
                print(f"Thought: {part.text}")
                print(f"Signature: {part.thought_signature}")

Streaming Decision Logic

Streaming is controlled exclusively by the stream parameter:

• stream=True: Uses streaming mode via messages.stream()
• stream=False: Uses non-streaming mode via messages.create()

Both modes support thinking blocks when thinking parameter is provided.

Interleaved Thinking Details

When to Use:

• Multi-step problems requiring reasoning between tool calls
• Complex tool chains where intermediate results inform next steps
• Scenarios where Claude needs to "think about" tool results before proceeding

How It Works:

• Non-interleaved (default): Claude thinks once, makes all tool decisions upfront
• Interleaved (beta): Claude can reason about tool results before deciding what to do next
• Thinking blocks are automatically preserved when passing assistant messages back to API
• Beta header only sent when BOTH enable_interleaved_thinking=True AND thinking is enabled

Requirements:

• Claude 4 models (Opus 4, Sonnet 4, etc.)
• Thinking config must be enabled (thinking_budget > 0)
• Only supports automatic tool selection (tool_choice: auto)

Key Implementation Notes

1. Signature Preservation: Thinking blocks now preserve cryptographic signatures from Anthropic API
2. Thinking Block Ordering: Content blocks automatically reordered to place thinking blocks first (Anthropic requirement)
3. Non-Streaming Thinking: Non-streaming mode correctly passes thinking parameter to API
4. Budget Validation: Unlimited budget (-1) raises clear error message
5. Final Message: Streaming builds final response from content blocks (not accumulated strings) to preserve signatures
6. Beta Header: Conditionally set based on enable_interleaved_thinking flag and thinking config

[pandemosth]

Does this support tool use with interleaved thinking?
https://docs.claude.com/en/docs/build-with-claude/extended-thinking#tool-use-with-interleaved-thinking

[pandemosth]

If Anthropic doesn't support automatic thinking budget we shouldn't fake it here. Throw an error instead as its important that the end user considers thinking budget for their use case as per https://docs.claude.com/en/docs/build-with-claude/extended-thinking#working-with-thinking-budgets

[damithsenanayake]

done...

[pandemosth]

Anthropic only supports extended thinking if streaming?

[damithsenanayake]

nope... only for larger thinking budgets. now revised.

[damithsenanayake]

Does this support tool use with interleaved thinking? https://docs.claude.com/en/docs/build-with-claude/extended-thinking#tool-use-with-interleaved-thinking

not yet: on it