Claude SDK Integration Patterns

Claude SDK Integration Patterns

Production-ready patterns for integrating Claude API and TypeScript SDK into applications. Master streaming responses, tool execution, error handling, and optimization strategies for AI-powered features.

When to Use This Skill

Use this skill when you need to:

• Integrate Claude API into Node.js/TypeScript applications
• Implement streaming conversations with real-time responses
• Build applications with Claude tool use (function calling)
• Handle API errors gracefully with retry logic
• Optimize token usage and manage costs
• Deploy Claude-powered features to production
• Build multi-turn conversations with context management
• Implement message batching for high-volume processing

Core Concepts

Messages API Fundamentals

The Claude Messages API is the primary interface for conversational AI:

Key Components:

• Model Selection: Choose appropriate model (Opus, Sonnet, Haiku)
• Messages Array: Conversation history with user/assistant roles
• Max Tokens: Control response length
• System Prompts: Guide model behavior
• Streaming: Real-time response generation

SDK Architecture

The TypeScript SDK provides:

• Type-safe API client
• Streaming helpers for real-time responses
• Tool execution framework
• Error handling utilities
• Message batch processing
• Event-driven architecture

Installation and Setup

# Install the SDK
npm install @anthropic-ai/sdk

# Or with yarn
yarn add @anthropic-ai/sdk

import Anthropic from '@anthropic-ai/sdk';

// Initialize client
const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

Messages API Patterns

Pattern 1: Basic Message Creation

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Claude!' }
  ],
});

console.log(message.content);

When to use:

• Simple question-answer interactions
• One-off API calls
• Synchronous workflows

Pattern 2: Multi-Turn Conversations

const messages = [
  { role: 'user', content: 'What is TypeScript?' },
  { role: 'assistant', content: 'TypeScript is a typed superset of JavaScript...' },
  { role: 'user', content: 'Give me an example' },
];

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages,
});

When to use:

• Chatbots and conversational UIs
• Multi-step workflows
• Context-dependent interactions

Pattern 3: System Prompts

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: 'You are a helpful Python programming assistant. Provide concise, tested code examples.',
  messages: [
    { role: 'user', content: 'How do I read a CSV file?' }
  ],
});

When to use:

• Specialized assistants
• Role-playing scenarios
• Consistent behavior across conversations

Streaming Patterns

Pattern 4: Basic Streaming

const stream = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a story' }],
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
    process.stdout.write(event.delta.text);
  }
}

When to use:

• Real-time user interfaces
• Long-form content generation
• Interactive experiences

Pattern 5: Streaming with Event Handlers

const stream = anthropic.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
})
  .on('text', (text) => {
    console.log(text);
  })
  .on('message', (message) => {
    console.log('Complete message:', message);
  })
  .on('error', (error) => {
    console.error('Stream error:', error);
  });

const finalMessage = await stream.finalMessage();

When to use:

• Real-time UIs (chatbots, live editors)
• Progress indicators
• Partial result processing

Pattern 6: Streaming with Abort Control

const stream = anthropic.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Long task...' }],
});

// Abort after timeout
setTimeout(() => stream.abort(), 5000);

try {
  await stream.done();
} catch (error) {
  if (error instanceof Anthropic.APIUserAbortError) {
    console.log('Stream aborted by user');
  }
}

When to use:

• User-cancellable operations
• Timeout handling
• Resource management

Tool Use Patterns

Pattern 7: Tool Definition with Zod

import { betaZodTool } from '@anthropic-ai/sdk/helpers/zod';
import { z } from 'zod';

const weatherTool = betaZodTool({
  name: 'get_weather',
  inputSchema: z.object({
    location: z.string(),
    unit: z.enum(['celsius', 'fahrenheit']).default('fahrenheit'),
  }),
  description: 'Get current weather for a location',
  run: async (input) => {
    // Call weather API
    return `Weather in ${input.location}: 72°F, sunny`;
  },
});

When to use:

• Type-safe tool definitions
• Input validation
• Clear tool contracts

Pattern 8: Tool Runner for Automatic Execution

const finalMessage = await anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1000,
  messages: [
    { role: 'user', content: 'What\'s the weather in San Francisco?' }
  ],
  tools: [weatherTool],
});

console.log(finalMessage.content);

When to use:

• Automated tool execution
• AI agents with function calling
• Complex multi-step workflows

Pattern 9: Streaming Tool Execution

const runner = anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1000,
  messages: [{ role: 'user', content: 'Check weather and calculate travel time' }],
  tools: [weatherTool, travelTimeTool],
  stream: true,
});

for await (const messageStream of runner) {
  for await (const event of messageStream) {
    console.log('Event:', event);
  }
  console.log('Message:', await messageStream.finalMessage());
}

When to use:

• Real-time tool execution feedback
• Multi-tool workflows
• Interactive AI agents

Error Handling Patterns

Pattern 10: Comprehensive Error Handling

async function createMessage(prompt: string) {
  try {
    const message = await anthropic.messages.create({
      model: 'claude-sonnet-4-5-20250929',
      max_tokens: 1024,
      messages: [{ role: 'user', content: prompt }],
    });

    return message;
  } catch (error) {
    if (error instanceof Anthropic.APIError) {
      console.error('API Error:', {
        status: error.status,
        name: error.name,
        message: error.message,
        headers: error.headers,
      });

      // Handle specific errors
      if (error.status === 429) {
        // Rate limit - implement backoff
        console.log('Rate limited, waiting...');
        await new Promise(resolve => setTimeout(resolve, 60000));
        return createMessage(prompt); // Retry
      } else if (error.status === 401) {
        throw new Error('Invalid API key');
      } else if (error.status === 400) {
        throw new Error(`Bad request: ${error.message}`);
      }
    }

    throw error;
  }
}

When to use:

• Production applications
• Robust error recovery
• User-facing applications

Pattern 11: Exponential Backoff Retry

async function createWithRetry(
  params: Anthropic.MessageCreateParams,
  maxRetries = 3,
  baseDelay = 1000
): Promise<Anthropic.Message> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await anthropic.messages.create(params);
    } catch (error) {
      if (error instanceof Anthropic.APIError && error.status === 429) {