claude-sdk-integration-patterns

Claude SDK の統合パターン

Claude API と TypeScript SDK をアプリケーションに統合するための、本番環境対応パターンです。ストリーミング応答、ツールの実行、エラー処理、AI を活用した機能の最適化戦略を習得できます。

このスキルを使う場面

次のような場合に、このスキルを使用してください。

• Claude API を Node.js／TypeScript アプリケーションに統合する
• リアルタイム応答を返すストリーミング会話を実装する
• Claude のツール利用（関数呼び出し）を使ったアプリケーションを構築する
• 再試行ロジックで API エラーを適切に処理する
• トークン使用量を最適化し、コストを管理する
• Claude を活用した機能を本番環境にデプロイする
• コンテキスト管理を伴う複数ターンの会話を構築する
• 大量処理向けにメッセージのバッチ処理を実装する

主な概念

Messages API の基本

Claude Messages API は、会話型 AI の主要なインターフェースです。

主な構成要素：

• モデルの選択：用途に適したモデル（Opus、Sonnet、Haiku）を選択します
• メッセージ配列：ユーザー／アシスタントのロールを含む会話履歴です
• 最大トークン数：応答の長さを制御します
• システムプロンプト：モデルの動作を導きます
• ストリーミング：リアルタイムで応答を生成します

SDK のアーキテクチャ

TypeScript SDK には、次の機能が用意されています。

• 型安全な API クライアント
• リアルタイム応答向けのストリーミングヘルパー
• ツール実行フレームワーク
• エラー処理ユーティリティ
• メッセージのバッチ処理
• イベント駆動型アーキテクチャ

インストールとセットアップ

# 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 のパターン

パターン 1：基本的なメッセージの作成

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 呼び出し
• 同期ワークフロー

パターン 2：複数ターンの会話

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
• 複数ステップのワークフロー
• コンテキストに依存するやり取り

パターン 3：システムプロンプト

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

使用する場面：

• 専門分野に特化したアシスタント
• ロールプレイのシナリオ
• 会話全体で一貫した動作

ストリーミングのパターン

パターン 4：基本的なストリーミング

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

使用する場面：

• リアルタイムのユーザーインターフェース
• 長文コンテンツの生成
• インタラクティブな体験

パターン 5：イベントハンドラーを使ったストリーミング

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（チャットボット、ライブエディター）
• 進行状況インジケーター
• 部分的な結果の処理

パターン 6：中断制御を伴うストリーミング

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

使用する場面：

• ユーザーがキャンセルできる操作
• タイムアウト処理
• リソース管理

ツール利用のパターン

パターン 7：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`;
  },
});

使用する場面：

• 型安全なツール定義
• 入力検証
• 明確なツールの契約

パターン 8：自動実行のためのツールランナー

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 エージェント
• 複雑な複数ステップのワークフロー

パターン 9：ツール実行のストリーミング

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 エージェント

エラー処理のパターン

パターン 10：包括的なエラー処理

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

使用する場面：

• 本番環境のアプリケーション
• 堅牢なエラー復旧
• ユーザー向けアプリケーション

パターン 11：指数バックオフによる再試行

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

使用する場面：

• 大量処理を行うアプリケーション
• レート制限への対応
• ネットワークの信頼性向上

トークン最適化のパターン

パターン 12：トークン数のカウント

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

使用する場面：

• コストの最適化
• トークン予算の管理
• 大きな入力の処理

パターン 13：コンテキストウィンドウの管理

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

使用する場面：

• 長い会話
• コンテキスト管理
• コスト管理

メッセージのバッチ処理パターン

パターン 14：バッチ処理

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

使用する場面：

• 一括処理
• オフラインワークフロー
• コストの最適化（バッチ料金の低減）

本番環境向けパターン

パターン 15：リクエストのタイムアウト設定

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

使用する場面：

• 本番環境へのデプロイ
• ネットワークの信頼性向上
• リソース管理

パターン 16：カスタムヘッダーとメタデータ

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 テスト

ベストプラクティス

API キーの管理

1. API キーをハードコードしないでください

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

2. 環境変数を使用してください

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

モデルの選択

1. タスクに適したモデルを選択してください：

   • Opus：最も高性能で、複雑な推論に適しています
   • Sonnet：性能と速度のバランスに優れています
   • Haiku：最速で、シンプルなタスクに適しています

2. 最新バージョンのモデルを使用してください：

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

ストリーミングに関する考慮事項

1. 次の場合は必ずストリーミングを使用してください：

   • ユーザー向けアプリケーション
   • 長文コンテンツ（500 トークン超）
   • リアルタイムのやり取り

2. 次の場合はストリーミングを避けてください：

   • バックエンドでのバッチ処理
   • 事前に決定的な出力が必要な場合
   • シンプルな API 連携

エラー処理

1. API エラーを必ず捕捉してください
2. 一時的な障害に対する再試行ロジックを実装してください
3. デバッグ用にエラーを記録してください
4. ユーザーにわかりやすいエラーメッセージを表示してください

トークン管理

1. API 呼び出しの前にトークン数を見積もってください
2. 適切な max_tokens を設定してください
3. トークン使用量を監視してください
4. 長い会話ではコンテキストの整理を実装してください

トラブルシューティング

問題：レート制限エラー（429）

解決策：

• 指数バックオフを実装する
• 一括操作ではメッセージをバッチ処理する
• より高いレート制限のプランにアップグレードする

問題：タイムアウトエラー

解決策：

• 長い応答にはストリーミングを使用する
• タイムアウト設定を延長する
• max_tokens を減らす

問題：API キーが無効（401）

解決策：

• 環境変数が設定されていることを確認する
• API キーの形式を確認する（sk-ant- で始まる）
• キーがローテーションされていないことを確認する

問題：コンテキスト長の超過

解決策：

• 会話の整理を実装する
• 古いメッセージを要約する
• 適切なコンテキストウィンドウの上限を使用する

リソース

• Anthropic API ドキュメント
• TypeScript SDK GitHub
• Claude API の料金
• モデルの比較

---

スキルのバージョン：1.0.0 最終更新日：2025年10月 互換性：@anthropic-ai/sdk 0.30.0+ 調査元：Context7 - Anthropic TypeScript SDK（コードスニペット106件、信頼スコア8.8）