Anthropic Python SDK: AI-Optimized Technical Reference

Configuration

Installation & Dependencies

pip install anthropic
# For dependency conflicts (common issue):
pip install "httpx>=0.23.0,<0.25.0" anthropic --force-reinstall
# AWS Bedrock: pip install anthropic[bedrock]
# Google Vertex: pip install anthropic[vertex]

Critical Requirements:

• Python 3.8+ supported
• Latest version: ~0.66.0 (frequent updates)
• Uses httpx underneath (not requests)

Production Settings:

client = Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
    timeout=30.0  # Default 600s is too long for production
)

Model Configuration

• Current model names: claude-3-5-sonnet-20241022, claude-3-opus-20240229
• Model deprecation: Names change without warning - pin versions and expect updates
• Context limits: 200K tokens official, 150K practical before performance degradation

Resource Requirements

Cost Structure

Model	Input Cost	Output Cost	Production Viability
Opus	$15/M tokens	$75/M tokens	Expensive - $800/month for 1000 conversations/day
Sonnet	Lower cost	Lower cost	$200/month for same workload
Batch API	50% cheaper	50% cheaper	5+ minute wait required

Performance Thresholds

• Rate limits: More aggressive than documented
• Context degradation: Quality drops after 100K tokens (Opus), 150K tokens (others)
• Production load: Tested at 100K requests/day successfully
• Streaming reliability: Works without buffering issues

Critical Warnings

Rate Limiting Reality

• Documented vs actual: Real limits are more aggressive than published
• Retry strategy: Wait 2x the suggested retry-after time
• Tier impact: Free tier heavily throttled, paid tier still has burst limits
• Tool use penalty: Rate limits more aggressive with function calling

Common Failure Modes

Dependency Conflicts

# httpx vs requests conflicts - common in mixed environments
# Solution: Pin both or use force-reinstall

Timeout Issues

# Default 600s timeout causes random failures
# Production requirement: Set to 30s maximum

Context Window Lies

• Official 200K tokens misleading
• Performance cliff at 150K tokens
• Cost scales exponentially with context size

Model Name Volatility

• Model names deprecated without warning
• Breaking changes between versions
• Requires constant monitoring and updates

AWS Bedrock Integration

• Authentication: IAM setup is complex and poorly documented
• Performance: Solid once configured
• Documentation quality: Terrible - expect 2+ hours setup time

Google Vertex Integration

• Setup complexity: Service account JSON configuration required
• Time investment: ~1 hour for initial setup
• Region limitations: Limited availability

Implementation Patterns

Streaming Implementation

# Reliable streaming pattern
async with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "prompt"}],
    model="claude-3-5-sonnet-20241022"
) as stream:
    async for text in stream.text_stream:
        print(text, end="", flush=True)

    # Check completion status
    message = await stream.get_final_message()
    if message.stop_reason == "max_tokens":
        # Handle token limit reached

Error Handling

from anthropic import RateLimitError
import time

try:
    response = client.messages.create(...)
except RateLimitError as e:
    wait_time = int(e.response.headers.get('retry-after', 60)) * 2
    time.sleep(wait_time)

FastAPI Integration

from anthropic import AsyncAnthropic
# Use async client to prevent blocking
client = AsyncAnthropic()

Tool Use Schema

tools = [{
    "name": "function_name",
    "description": "Clear description",
    "input_schema": {
        "type": "object",
        "properties": {
            "param": {"type": "string"}
        },
        "required": ["param"]
    }
}]

Comparison Matrix

Feature	Anthropic	OpenAI	Assessment
Type hints	✅ Accurate	❌ Mostly Any	Anthropic superior
Async support	✅ httpx-based	✅ httpx-based	Both reliable
Streaming	✅ No buffering issues	✅ Verbose but works	Anthropic simpler
Error messages	✅ Actionable	⚠️ Sometimes helpful	Anthropic better
Documentation	✅ Working examples	❌ Often outdated	Anthropic maintained
Rate limit handling	✅ Built-in retries	✅ Built-in retries	Comparable
Dependencies	⚠️ httpx conflicts	⚠️ requests issues	Both have issues

Decision Criteria

Use Anthropic SDK When:

• Type safety is important (better type hints than OpenAI)
• Streaming reliability is critical
• Clear error messages are valued
• Working with Claude models specifically

Avoid When:

• Budget is extremely tight (Opus costs are high)
• Need immediate responses (rate limits are aggressive)
• Using legacy Python (<3.8)
• Cannot tolerate dependency conflicts

Migration Considerations

• From custom implementation: Always migrate - authentication/retry logic not worth maintaining
• From OpenAI SDK: Worth switching for better type safety and documentation
• Time investment: 1-2 days for full migration including error handling

Breaking Points

Hard Limits

• Context window: 200K tokens (150K practical)
• Rate limits: More restrictive than documented
• Timeout defaults: 600s (unacceptable for production)
• Cost scaling: Exponential with context size and model sophistication

Operational Thresholds

• Production readiness: Requires custom timeout and error handling
• Scale limits: Tested successfully at 100K requests/day
• Quality degradation: Noticeable after 100K-150K tokens depending on model
• Cost viability: Opus prohibitive for high-volume applications

Essential Resources

• Status monitoring: status.anthropic.com (bookmark required)
• Issue tracking: GitHub issues contain real production problems
• Batch processing: 50% cost reduction for non-urgent workloads
• Alternative providers: Google Gemini better for long context, LiteLLM for multi-provider abstraction