anthropic-sdk-guide

Anthropic SDK Guide

Comprehensive reference for building with the Anthropic Python and TypeScript SDKs. Covers initialization, messages API, streaming, prompt caching, batches, and error handling.

When to Use

• User is setting up Anthropic SDK (Python or TypeScript)
• User is calling the Messages API or needs streaming responses
• User wants prompt caching, batch processing, or token counting
• User is debugging API errors or rate limits
• User asks about Claude model IDs or API configuration

Core Patterns

SDK Installation and Setup

# Python
pip install anthropic

# TypeScript
npm install @anthropic-ai/sdk

# Python - client initialization
import anthropic

client = anthropic.Anthropic()  # Uses ANTHROPIC_API_KEY env var
# Or explicit: anthropic.Anthropic(api_key="sk-ant-...")

// TypeScript - client initialization
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();  // Uses ANTHROPIC_API_KEY env var

Messages API - Basic Usage

# Python - simple message
message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    system="You are a helpful coding assistant.",
    messages=[
        {"role": "user", "content": "Explain async/await in Python."}
    ]
)
print(message.content[0].text)

// TypeScript - simple message
const message = await client.messages.create({
  model: "claude-sonnet-4-6-20250514",
  max_tokens: 1024,
  system: "You are a helpful coding assistant.",
  messages: [
    { role: "user", content: "Explain async/await in Python." }
  ],
});
console.log(message.content[0].text);

Streaming Responses

# Python - streaming with context manager
with client.messages.stream(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a short story."}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# Access final message after stream completes
final_message = stream.get_final_message()

// TypeScript - streaming
const stream = client.messages.stream({
  model: "claude-sonnet-4-6-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a short story." }],
});

stream.on("text", (text) => process.stdout.write(text));

const finalMessage = await stream.finalMessage();

Prompt Caching

Use cache_control to cache large system prompts, tool definitions, or conversation prefixes. Cached content costs 90% less on cache hits.

# Python - prompt caching with large system prompt
message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an expert on this large codebase..." + large_context,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "What does the auth module do?"}]
)
# Check cache performance
print(f"Cache read: {message.usage.cache_read_input_tokens}")
print(f"Cache creation: {message.usage.cache_creation_input_tokens}")

Batch Processing

Process up to 10,000 requests at 50% cost with 24-hour turnaround.

# Python - create a batch
batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": f"request-{i}",
            "params": {
                "model": "claude-sonnet-4-6-20250514",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": prompt}]
            }
        }
        for i, prompt in enumerate(prompts)
    ]
)

# Poll for completion
import time
while True:
    status = client.messages.batches.retrieve(batch.id)
    if status.processing_status == "ended":
        break
    time.sleep(60)

# Stream results
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        print(result.custom_id, result.result.message.content[0].text)

Token Counting

# Python - count tokens before sending
count = client.messages.count_tokens(
    model="claude-sonnet-4-6-20250514",
    system="You are a helpful assistant.",
    messages=[{"role": "user", "content": long_document}]
)
print(f"Input tokens: {count.input_tokens}")

Error Handling

import anthropic

try:
    message = client.messages.create(
        model="claude-sonnet-4-6-20250514",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}]
    )
except anthropic.RateLimitError:
    # Back off and retry - SDK has built-in retries (2 by default)
    print("Rate limited. The SDK will auto-retry.")
except anthropic.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
except anthropic.APIConnectionError:
    print("Network connection failed.")

Anti-Patterns

• Hardcoding API keys instead of using environment variables
• Not setting max_tokens (it is required, not optional)
• Ignoring the stop_reason field (could be "end_turn", "max_tokens", or "tool_use")
• Polling batch status too frequently (use 60-second intervals minimum)
• Not using streaming for user-facing applications (causes perceived latency)
• Setting temperature > 0 for deterministic tasks like classification or extraction

Quick Reference

Model ID	Best For
claude-opus-4-6-20250514	Deep reasoning, complex tasks
claude-sonnet-4-6-20250514	Best balance of speed and capability
claude-haiku-4-5-20251001	Fast, lightweight tasks

Feature	Endpoint / Method
Messages	client.messages.create()
Streaming	client.messages.stream()
Batches	client.messages.batches.create()
Token count	client.messages.count_tokens()
Prompt caching	cache_control: {"type": "ephemeral"}

Default retries: 2 (configurable via max_retries on client).