claude-sdk-integration-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude SDK Integration Patterns

Claude SDK集成模式

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.

将Claude API和TypeScript SDK集成到应用中的生产级模式。掌握流式响应、工具执行、错误处理以及AI驱动功能的优化策略。

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

当你需要以下功能时使用本技能：

在Node.js/TypeScript应用中集成Claude API
实现带实时响应的流式对话
构建支持Claude工具调用（函数调用）的应用
通过重试逻辑优雅处理API错误
优化令牌使用并管理成本
将Claude驱动的功能部署到生产环境
构建带上下文管理的多轮对话
实现用于高容量处理的消息批处理

Core Concepts

核心概念

Messages API Fundamentals

Messages API基础

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

Claude Messages API是对话式AI的主要接口：

关键组件：

模型选择：选择合适的模型（Opus、Sonnet、Haiku）
消息数组：包含用户/助手角色的对话历史
最大令牌数（Max Tokens）：控制响应长度
系统提示词：引导模型行为
流式传输（Streaming）：实时响应生成

SDK Architecture

SDK架构

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

TypeScript SDK提供：

类型安全的API客户端
用于实时响应的流式助手工具
工具执行框架
错误处理工具
消息批处理功能
事件驱动架构

Installation and Setup

安装与设置

bash

undefined

bash

undefined

Install the SDK

npm install @anthropic-ai/sdk

Or with yarn

yarn add @anthropic-ai/sdk


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

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

yarn add @anthropic-ai/sdk


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

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

Messages API Patterns

Messages API模式

Pattern 1: Basic Message Creation

模式1：基础消息创建

typescript

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

typescript

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);

适用场景：

简单问答交互
一次性API调用
同步工作流

Pattern 2: Multi-Turn Conversations

模式2：多轮对话

typescript

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

typescript

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,
});

适用场景：

聊天机器人与对话式UI
多步骤工作流
依赖上下文的交互

Pattern 3: System Prompts

模式3：系统提示词

typescript

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

typescript

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?' }
  ],
});

适用场景：

专业助手应用
角色扮演场景
对话间的行为一致性保障

Streaming Patterns

流式传输模式

Pattern 4: Basic Streaming

模式4：基础流式传输

typescript

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

typescript

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);
  }
}

适用场景：

实时用户界面
长文本内容生成
交互式体验

Pattern 5: Streaming with Event Handlers

模式5：带事件处理器的流式传输

typescript

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

typescript

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();

适用场景：

实时UI（聊天机器人、在线编辑器）
进度指示器
部分结果处理

Pattern 6: Streaming with Abort Control

模式6：带中止控制的流式传输

typescript

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

typescript

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');
  }
}

适用场景：

用户可取消的操作
超时处理
资源管理

Tool Use Patterns

工具调用模式

Pattern 7: Tool Definition with Zod

模式7：结合Zod的工具定义

typescript

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

typescript

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`;
  },
});

适用场景：

类型安全的工具定义
输入验证
清晰的工具契约

Pattern 8: Tool Runner for Automatic Execution

模式8：自动执行的工具运行器

typescript

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

typescript

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);

适用场景：

自动化工具执行
带函数调用的AI Agent
复杂多步骤工作流

Pattern 9: Streaming Tool Execution

模式9：流式工具执行

typescript

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

typescript

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());
}

适用场景：

实时工具执行反馈
多工具工作流
交互式AI Agent

Error Handling Patterns

错误处理模式

Pattern 10: Comprehensive Error Handling

模式10：全面错误处理

typescript

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

typescript

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;
  }
}

适用场景：

生产环境应用
健壮的错误恢复
面向用户的应用

Pattern 11: Exponential Backoff Retry

模式11：指数退避重试

typescript

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) {
        // Rate limit - exponential backoff
        const delay = baseDelay * Math.pow(2, attempt);
        console.log(`Retry attempt ${attempt + 1} after ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }

  throw new Error('Max retries exceeded');
}

When to use:

High-volume applications
Rate limit handling
Network reliability

typescript

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) {
        // Rate limit - exponential backoff
        const delay = baseDelay * Math.pow(2, attempt);
        console.log(`Retry attempt ${attempt + 1} after ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }

  throw new Error('Max retries exceeded');
}

适用场景：

高容量应用
速率限制处理
网络可靠性保障

Token Optimization Patterns

令牌优化模式

Pattern 12: Token Counting

模式12：令牌计数

typescript

import { encode } from 'gpt-tokenizer';

function estimateTokens(text: string): number {
  // Approximate token count (Claude uses similar tokenization to GPT)
  return encode(text).length;
}

function optimizePrompt(userMessage: string, maxTokens: number = 1024): string {
  const tokens = estimateTokens(userMessage);

  if (tokens > maxTokens) {
    // Truncate or summarize
    return userMessage.slice(0, maxTokens * 4); // Rough char estimate
  }

  return userMessage;
}

When to use:

Cost optimization
Token budget management
Large input handling

typescript

import { encode } from 'gpt-tokenizer';

function estimateTokens(text: string): number {
  // Approximate token count (Claude uses similar tokenization to GPT)
  return encode(text).length;
}

function optimizePrompt(userMessage: string, maxTokens: number = 1024): string {
  const tokens = estimateTokens(userMessage);

  if (tokens > maxTokens) {
    // Truncate or summarize
    return userMessage.slice(0, maxTokens * 4); // Rough char estimate
  }

  return userMessage;
}

适用场景：

成本优化
令牌预算管理
大输入内容处理

Pattern 13: Context Window Management

模式13：上下文窗口管理

typescript

interface ConversationMessage {
  role: 'user' | 'assistant';
  content: string;
  tokens?: number;
}

class ConversationManager {
  private messages: ConversationMessage[] = [];
  private maxContextTokens = 100000;

  addMessage(role: 'user' | 'assistant', content: string) {
    const tokens = estimateTokens(content);
    this.messages.push({ role, content, tokens });
    this.pruneIfNeeded();
  }

  private pruneIfNeeded() {
    const totalTokens = this.messages.reduce((sum, msg) => sum + (msg.tokens || 0), 0);

    if (totalTokens > this.maxContextTokens) {
      // Remove oldest messages (keep system prompt if present)
      this.messages = this.messages.slice(-10); // Keep last 10 messages
    }
  }

  getMessages() {
    return this.messages.map(({ role, content }) => ({ role, content }));
  }
}

When to use:

Long conversations
Context management
Cost control

typescript

interface ConversationMessage {
  role: 'user' | 'assistant';
  content: string;
  tokens?: number;
}

class ConversationManager {
  private messages: ConversationMessage[] = [];
  private maxContextTokens = 100000;

  addMessage(role: 'user' | 'assistant', content: string) {
    const tokens = estimateTokens(content);
    this.messages.push({ role, content, tokens });
    this.pruneIfNeeded();
  }

  private pruneIfNeeded() {
    const totalTokens = this.messages.reduce((sum, msg) => sum + (msg.tokens || 0), 0);

    if (totalTokens > this.maxContextTokens) {
      // Remove oldest messages (keep system prompt if present)
      this.messages = this.messages.slice(-10); // Keep last 10 messages
    }
  }

  getMessages() {
    return this.messages.map(({ role, content }) => ({ role, content }));
  }
}

适用场景：

长对话场景
上下文管理
成本控制

Message Batching Patterns

消息批处理模式

Pattern 14: Batch Processing

模式14：批处理

typescript

const batchResult = await anthropic.messages.batches.create({
  requests: [
    {
      custom_id: 'request-1',
      params: {
        model: 'claude-sonnet-4-5-20250929',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Summarize this article...' }],
      },
    },
    {
      custom_id: 'request-2',
      params: {
        model: 'claude-sonnet-4-5-20250929',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Translate this text...' }],
      },
    },
  ],
});

// Poll for results
const batch = await anthropic.messages.batches.retrieve(batchResult.id);

When to use:

Bulk processing
Offline workflows
Cost optimization (lower batch pricing)

typescript

const batchResult = await anthropic.messages.batches.create({
  requests: [
    {
      custom_id: 'request-1',
      params: {
        model: 'claude-sonnet-4-5-20250929',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Summarize this article...' }],
      },
    },
    {
      custom_id: 'request-2',
      params: {
        model: 'claude-sonnet-4-5-20250929',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Translate this text...' }],
      },
    },
  ],
});

// Poll for results
const batch = await anthropic.messages.batches.retrieve(batchResult.id);

适用场景：

批量处理
离线工作流
成本优化（批量定价更低）

Production Patterns

生产环境模式

Pattern 15: Request Timeout Configuration

模式15：请求超时配置

typescript

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  timeout: 60000, // 60 seconds
  maxRetries: 3,
});

When to use:

Production deployments
Network reliability
Resource management

typescript

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  timeout: 60000, // 60 seconds
  maxRetries: 3,
});

适用场景：

生产环境部署
网络可靠性保障
资源管理

Pattern 16: Custom Headers and Metadata

模式16：自定义头部与元数据

typescript

const message = await anthropic.messages.create(
  {
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello' }],
  },
  {
    headers: {
      'anthropic-beta': 'max-tokens-3-5-sonnet-2024-07-15',
    },
  }
);

When to use:

Beta features
Custom tracking
A/B testing

typescript

const message = await anthropic.messages.create(
  {
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello' }],
  },
  {
    headers: {
      'anthropic-beta': 'max-tokens-3-5-sonnet-2024-07-15',
    },
  }
);

适用场景：

测试版功能
自定义追踪
A/B测试

Best Practices

最佳实践

API Key Management

API密钥管理

Never hardcode API keys

typescript

// ❌ Bad
const anthropic = new Anthropic({ apiKey: 'sk-ant-...' });

// ✅ Good
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

Use environment variables

bash

# .env file
ANTHROPIC_API_KEY=sk-ant-your-key-here

切勿硬编码API密钥

typescript

// ❌ Bad
const anthropic = new Anthropic({ apiKey: 'sk-ant-...' });

// ✅ Good
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

使用环境变量

bash

# .env file
ANTHROPIC_API_KEY=sk-ant-your-key-here

Model Selection

模型选择

Choose appropriate model for task:
- Opus: Most capable, complex reasoning
- Sonnet: Balanced performance/speed
- Haiku: Fastest, simple tasks

Use latest model versions:

typescript

model: 'claude-sonnet-4-5-20250929' // Latest

根据任务选择合适的模型：
- Opus：能力最强，适用于复杂推理
- Sonnet：性能与速度平衡
- Haiku：速度最快，适用于简单任务

使用最新模型版本：

typescript

model: 'claude-sonnet-4-5-20250929' // Latest

Streaming Considerations

流式传输注意事项

Always use streaming for:
- User-facing applications
- Long-form content (>500 tokens)
- Real-time interactions
Avoid streaming for:
- Backend batch processing
- Deterministic outputs needed upfront
- Simple API integrations

以下场景建议始终使用流式传输：
- 面向用户的应用
- 长文本内容（超过500令牌）
- 实时交互
以下场景避免使用流式传输：
- 后端批处理
- 需要提前获取确定性输出
- 简单API集成

Error Handling

错误处理

Always catch API errors
Implement retry logic for transient failures
Log errors for debugging
Provide user-friendly error messages

始终捕获API错误
为临时故障实现重试逻辑
记录错误用于调试
提供用户友好的错误提示

Token Management

令牌管理

Estimate tokens before API calls
Set appropriate max_tokens
Monitor token usage
Implement context pruning for long conversations

API调用前预估令牌数
设置合适的max_tokens值
监控令牌使用情况
为长对话实现上下文修剪

Troubleshooting

故障排除

Issue: Rate Limit Errors (429)

问题：速率限制错误（429）

Solution:

Implement exponential backoff
Use message batching for bulk operations
Upgrade to higher rate limit tier

解决方案：

实现指数退避
批量操作使用消息批处理
升级到更高速率限制套餐

Issue: Timeout Errors

问题：超时错误

Solution:

Use streaming for long responses
Increase timeout configuration
Reduce max_tokens

解决方案：

长响应使用流式传输
增加超时配置
减少max_tokens值

Issue: Invalid API Key (401)

问题：无效API密钥（401）

Solution:

Verify environment variable is set
Check API key format (starts with
```
sk-ant-
```
)
Ensure key hasn't been rotated

解决方案：

验证环境变量是否正确设置
检查API密钥格式（以
```
sk-ant-
```
开头）
确认密钥未被轮换

Issue: Context Length Exceeded

问题：上下文长度超出限制

Solution:

Implement conversation pruning
Summarize older messages
Use appropriate context window limits

解决方案：

实现对话修剪
总结旧消息
使用合适的上下文窗口限制

Resources

资源

Skill Version: 1.0.0 Last Updated: October 2025 Compatibility: @anthropic-ai/sdk 0.30.0+ Research Source: Context7 - Anthropic TypeScript SDK (106 code snippets, Trust Score 8.8)