Anthropic SDK Patterns
Overview
Production patterns for the @claude-ai/sdk (TypeScript) and anthropic (Python) SDKs.
Client Configuration
Instructions
Step 1: TypeScript
import Anthropic from '@claude-ai/sdk';
const client = new Anthropic();
const client = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY,
maxRetries: 3,
timeout: 60_000,
baseURL: 'https://api.anthropic.com',
defaultHeaders: {
'claude-beta': 'prompt-caching-2024-07-31',
},
});
Step 2: Python
import anthropic
client = anthropic.Anthropic()
client = anthropic.AsyncAnthropic()
client = anthropic.Anthropic(
api_key=os.environ["ANTHROPIC_API_KEY"],
max_retries=3,
timeout=60.0,
base_url="https://api.anthropic.com",
default_headers={"claude-beta": "prompt-caching-2024-07-31"},
)
Output
- Properly configured client with retries, timeouts, and custom headers
- Type-safe error handling with specific exception classes
- Streaming implementation using your preferred pattern
- Prompt caching enabled for repeated system prompts (90% cost savings)
- Batch processing configured for bulk operations (50% cost savings)
Error Handling
import Anthropic from '@claude-ai/sdk';
try {
const message = await client.messages.create({ ... });
} catch (err) {
if (err instanceof Anthropic.AuthenticationError) {
} else if (err instanceof Anthropic.RateLimitError) {
} else if (err instanceof Anthropic.APIError) {
console.error(err.status, err.error?.type, err.message);
} else if (err instanceof Anthropic.APIConnectionError) {
}
}
try:
message = client.messages.create(...)
except anthropic.AuthenticationError:
...
except anthropic.RateLimitError:
...
except anthropic.APIStatusError as e:
print(e.status_code, e.message)
except anthropic.APIConnectionError:
...
Streaming Patterns
Event-Based (TypeScript)
const stream = client.messages.stream({
model: 'claude-sonnet-4-20250514',
max_tokens: 2048,
messages,
});
stream.on('text', (text) => process.stdout.write(text));
stream.on('error', (err) => console.error('Stream error:', err));
stream.on('end', () => console.log('\nDone'));
const finalMessage = await stream.finalMessage();
Async Iterator (TypeScript)
const stream = await client.messages.create({
model: 'claude-sonnet-4-20250514',
max_tokens: 2048,
messages,
stream: true,
});
for await (const event of stream) {
if (event.type === 'content_block_delta') {
process.stdout.write(event.delta.text || '');
}
}
Context Manager (Python)
with client.messages.stream(
model="claude-sonnet-4-20250514",
max_tokens=2048,
messages=messages,
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
message = stream.get_final_message()
TypeScript Types
import Anthropic from '@claude-ai/sdk';
type Message = Anthropic.Message;
type MessageParam = Anthropic.MessageParam;
type ContentBlock = Anthropic.ContentBlock;
type TextBlock = Anthropic.TextBlock;
type ToolUseBlock = Anthropic.ToolUseBlock;
type Tool = Anthropic.Tool;
type ToolResultBlockParam = Anthropic.ToolResultBlockParam;
type MessageCreateParams = Anthropic.MessageCreateParams;
Prompt Caching (Beta)
const message = await client.messages.create({
model: 'claude-sonnet-4-20250514',
max_tokens: 1024,
system: [
{
type: 'text',
text: longSystemPrompt,
cache_control: { type: 'ephemeral' },
},
],
messages: [{ role: 'user', content: userQuestion }],
}, {
headers: { 'claude-beta': 'prompt-caching-2024-07-31' },
});
Message Batches
const batch = await client.messages.batches.create({
requests: items.map((item, i) => ({
custom_id: `item-${i}`,
params: {
model: 'claude-sonnet-4-20250514',
max_tokens: 1024,
messages: [{ role: 'user', content: item.prompt }],
},
})),
});
let status = await client.messages.batches.retrieve(batch.id);
while (status.processing_status !== 'ended') {
await new Promise(r => setTimeout(r, 30000));
status = await client.messages.batches.retrieve(batch.id);
}
Examples
See Client Configuration, Error Handling, Streaming Patterns, TypeScript Types, Prompt Caching, and Message Batches sections above for complete code examples.
Resources
Next Steps
See clade-rate-limits for throughput optimization.
Prerequisites
- Completed
clade-install-auth
- Familiarity with TypeScript generics or Python type hints
- Understanding of async/await patterns
