ガイド

コストと使用量の追跡

Claude Agent SDKにおける課金のためのトークン使用量の理解と追跡

SDKコスト追跡

Claude Agent SDKは、Claudeとの各インタラクションに関する詳細なトークン使用量情報を提供します。このガイドでは、特に並列ツール使用やマルチステップの会話を扱う際に、コストを適切に追跡し、使用量レポートを理解する方法を説明します。

完全なAPIドキュメントについては、TypeScript SDKリファレンスを参照してください。

トークン使用量の理解

Claudeがリクエストを処理する際、メッセージレベルでトークン使用量を報告します。この使用量データは、コストの追跡とユーザーへの適切な課金に不可欠です。

主要な概念

ステップ: ステップとは、アプリケーションとClaude間の単一のリクエスト/レスポンスのペアです
メッセージ: ステップ内の個々のメッセージ（テキスト、ツール使用、ツール結果）
使用量: アシスタントメッセージに付随するトークン消費データ

使用量レポートの構造

単一ツール使用 vs 並列ツール使用

Claudeがツールを実行する際、ツールが順次実行されるか並列実行されるかによって、使用量レポートが異なります：

import { query } from "@anthropic-ai/claude-agent-sdk";

// 例: 会話での使用量追跡
const result = await query({
  prompt: "Analyze this codebase and run tests",
  options: {
    onMessage: (message) => {
      if (message.type === 'assistant' && message.usage) {
        console.log(`Message ID: ${message.id}`);
        console.log(`Usage:`, message.usage);
      }
    }
  }
});

メッセージフローの例

典型的なマルチステップ会話でのメッセージと使用量の報告方法は以下の通りです：

<!-- ステップ1: 並列ツール使用を含む初期リクエスト -->
assistant (text)      { id: "msg_1", usage: { output_tokens: 100, ... } }
assistant (tool_use)  { id: "msg_1", usage: { output_tokens: 100, ... } }
assistant (tool_use)  { id: "msg_1", usage: { output_tokens: 100, ... } }
assistant (tool_use)  { id: "msg_1", usage: { output_tokens: 100, ... } }
user (tool_result)
user (tool_result)
user (tool_result)

<!-- ステップ2: フォローアップレスポンス -->
assistant (text)      { id: "msg_2", usage: { output_tokens: 98, ... } }

重要な使用量ルール

1. 同じID = 同じ使用量

同じidフィールドを持つすべてのメッセージは同一の使用量を報告します。Claudeが同じターンで複数のメッセージを送信する場合（例：テキスト + ツール使用）、それらは同じメッセージIDと使用量データを共有します。

// これらのメッセージはすべて同じIDと使用量を持つ
const messages = [
  { type: 'assistant', id: 'msg_123', usage: { output_tokens: 100 } },
  { type: 'assistant', id: 'msg_123', usage: { output_tokens: 100 } },
  { type: 'assistant', id: 'msg_123', usage: { output_tokens: 100 } }
];

// ユニークなメッセージIDごとに1回だけ課金する
const uniqueUsage = messages[0].usage; // このIDを持つすべてのメッセージで同じ

2. ステップごとに1回だけ課金

ユーザーへの課金はステップごとに1回だけにすべきであり、個々のメッセージごとではありません。同じIDを持つ複数のアシスタントメッセージが表示された場合、そのうちのいずれか1つの使用量を使用してください。

3. 結果メッセージには累積使用量が含まれる

最終的なresultメッセージには、会話内のすべてのステップからの合計累積使用量が含まれます：

// 最終結果には合計使用量が含まれる
const result = await query({
  prompt: "Multi-step task",
  options: { /* ... */ }
});

console.log("Total usage:", result.usage);
console.log("Total cost:", result.usage.total_cost_usd);

4. モデルごとの使用量内訳

結果メッセージにはmodelUsageも含まれており、モデルごとの正式な使用量データを提供します。total_cost_usdと同様に、このフィールドは正確で課金目的に適しています。これは、複数のモデルを使用する場合（例：サブエージェントにHaiku、メインエージェントにOpus）に特に便利です。

// modelUsageはモデルごとの内訳を提供する
type ModelUsage = {
  inputTokens: number
  outputTokens: number
  cacheReadInputTokens: number
  cacheCreationInputTokens: number
  webSearchRequests: number
  costUSD: number
  contextWindow: number
}

// 結果メッセージからアクセス
const result = await query({ prompt: "..." });

// result.modelUsageはモデル名からModelUsageへのマップ
for (const [modelName, usage] of Object.entries(result.modelUsage)) {
  console.log(`${modelName}: $${usage.costUSD.toFixed(4)}`);
  console.log(`  Input tokens: ${usage.inputTokens}`);
  console.log(`  Output tokens: ${usage.outputTokens}`);
}

完全な型定義については、TypeScript SDKリファレンスを参照してください。

実装：コスト追跡システム

コスト追跡システムの実装の完全な例を以下に示します：

import { query } from "@anthropic-ai/claude-agent-sdk";

class CostTracker {
  private processedMessageIds = new Set<string>();
  private stepUsages: Array<any> = [];
  
  async trackConversation(prompt: string) {
    const result = await query({
      prompt,
      options: {
        onMessage: (message) => {
          this.processMessage(message);
        }
      }
    });
    
    return {
      result,
      stepUsages: this.stepUsages,
      totalCost: result.usage?.total_cost_usd || 0
    };
  }
  
  private processMessage(message: any) {
    // 使用量を持つアシスタントメッセージのみ処理
    if (message.type !== 'assistant' || !message.usage) {
      return;
    }
    
    // このメッセージIDが既に処理済みの場合はスキップ
    if (this.processedMessageIds.has(message.id)) {
      return;
    }
    
    // 処理済みとしてマークし、使用量を記録
    this.processedMessageIds.add(message.id);
    this.stepUsages.push({
      messageId: message.id,
      timestamp: new Date().toISOString(),
      usage: message.usage,
      costUSD: this.calculateCost(message.usage)
    });
  }
  
  private calculateCost(usage: any): number {
    // ここに料金計算を実装
    // これは簡略化された例です
    const inputCost = usage.input_tokens * 0.00003;
    const outputCost = usage.output_tokens * 0.00015;
    const cacheReadCost = (usage.cache_read_input_tokens || 0) * 0.0000075;
    
    return inputCost + outputCost + cacheReadCost;
  }
}

// 使用方法
const tracker = new CostTracker();
const { result, stepUsages, totalCost } = await tracker.trackConversation(
  "Analyze and refactor this code"
);

console.log(`Steps processed: ${stepUsages.length}`);
console.log(`Total cost: $${totalCost.toFixed(4)}`);

エッジケースの処理

出力トークンの不一致

まれに、同じIDを持つメッセージで異なるoutput_tokens値が観察される場合があります。この場合：

最大値を使用する - グループ内の最後のメッセージが通常、正確な合計を含んでいます
合計コストと照合する - 結果メッセージのtotal_cost_usdが正式な値です
不整合を報告する - Claude Code GitHubリポジトリでイシューを提出してください

キャッシュトークンの追跡

プロンプトキャッシュを使用する場合、これらのトークンタイプを個別に追跡してください：

interface CacheUsage {
  cache_creation_input_tokens: number;
  cache_read_input_tokens: number;
  cache_creation: {
    ephemeral_5m_input_tokens: number;
    ephemeral_1h_input_tokens: number;
  };
}

ベストプラクティス

重複排除にメッセージIDを使用する: 二重課金を避けるため、処理済みのメッセージIDを常に追跡する
結果メッセージを監視する: 最終結果には正式な累積使用量が含まれる
ログを実装する: 監査とデバッグのためにすべての使用量データをログに記録する
障害を適切に処理する: 会話が失敗した場合でも部分的な使用量を追跡する
ストリーミングを考慮する: ストリーミングレスポンスの場合、メッセージの到着に応じて使用量を蓄積する

使用量フィールドリファレンス

各使用量オブジェクトには以下が含まれます：

input_tokens: 処理されたベース入力トークン
output_tokens: レスポンスで生成されたトークン
cache_creation_input_tokens: キャッシュエントリの作成に使用されたトークン
cache_read_input_tokens: キャッシュから読み取られたトークン
service_tier: 使用されたサービスティア（例：「standard」）
total_cost_usd: USD単位の合計コスト（結果メッセージのみ）

例：課金ダッシュボードの構築

課金ダッシュボード用に使用量データを集計する方法は以下の通りです：

class BillingAggregator {
  private userUsage = new Map<string, {
    totalTokens: number;
    totalCost: number;
    conversations: number;
  }>();
  
  async processUserRequest(userId: string, prompt: string) {
    const tracker = new CostTracker();
    const { result, stepUsages, totalCost } = await tracker.trackConversation(prompt);
    
    // ユーザーの合計を更新
    const current = this.userUsage.get(userId) || {
      totalTokens: 0,
      totalCost: 0,
      conversations: 0
    };
    
    const totalTokens = stepUsages.reduce((sum, step) => 
      sum + step.usage.input_tokens + step.usage.output_tokens, 0
    );
    
    this.userUsage.set(userId, {
      totalTokens: current.totalTokens + totalTokens,
      totalCost: current.totalCost + totalCost,
      conversations: current.conversations + 1
    });
    
    return result;
  }
  
  getUserBilling(userId: string) {
    return this.userUsage.get(userId) || {
      totalTokens: 0,
      totalCost: 0,
      conversations: 0
    };
  }
}

コストと使用量の追跡

Claude Agent SDKにおける課金のためのトークン使用量の理解と追跡

SDKコスト追跡

完全なAPIドキュメントについては、TypeScript SDKリファレンスを参照してください。

トークン使用量の理解

主要な概念

ステップ: ステップとは、アプリケーションとClaude間の単一のリクエスト/レスポンスのペアです
メッセージ: ステップ内の個々のメッセージ（テキスト、ツール使用、ツール結果）
使用量: アシスタントメッセージに付随するトークン消費データ

使用量レポートの構造

単一ツール使用 vs 並列ツール使用

Claudeがツールを実行する際、ツールが順次実行されるか並列実行されるかによって、使用量レポートが異なります：

import { query } from "@anthropic-ai/claude-agent-sdk";

// 例: 会話での使用量追跡
const result = await query({
  prompt: "Analyze this codebase and run tests",
  options: {
    onMessage: (message) => {
      if (message.type === 'assistant' && message.usage) {
        console.log(`Message ID: ${message.id}`);
        console.log(`Usage:`, message.usage);
      }
    }
  }
});

メッセージフローの例

典型的なマルチステップ会話でのメッセージと使用量の報告方法は以下の通りです：

<!-- ステップ1: 並列ツール使用を含む初期リクエスト -->
assistant (text)      { id: "msg_1", usage: { output_tokens: 100, ... } }
assistant (tool_use)  { id: "msg_1", usage: { output_tokens: 100, ... } }
assistant (tool_use)  { id: "msg_1", usage: { output_tokens: 100, ... } }
assistant (tool_use)  { id: "msg_1", usage: { output_tokens: 100, ... } }
user (tool_result)
user (tool_result)
user (tool_result)

<!-- ステップ2: フォローアップレスポンス -->
assistant (text)      { id: "msg_2", usage: { output_tokens: 98, ... } }

重要な使用量ルール

1. 同じID = 同じ使用量

// これらのメッセージはすべて同じIDと使用量を持つ
const messages = [
  { type: 'assistant', id: 'msg_123', usage: { output_tokens: 100 } },
  { type: 'assistant', id: 'msg_123', usage: { output_tokens: 100 } },
  { type: 'assistant', id: 'msg_123', usage: { output_tokens: 100 } }
];

// ユニークなメッセージIDごとに1回だけ課金する
const uniqueUsage = messages[0].usage; // このIDを持つすべてのメッセージで同じ

2. ステップごとに1回だけ課金

3. 結果メッセージには累積使用量が含まれる

最終的なresultメッセージには、会話内のすべてのステップからの合計累積使用量が含まれます：

// 最終結果には合計使用量が含まれる
const result = await query({
  prompt: "Multi-step task",
  options: { /* ... */ }
});

console.log("Total usage:", result.usage);
console.log("Total cost:", result.usage.total_cost_usd);

4. モデルごとの使用量内訳

// modelUsageはモデルごとの内訳を提供する
type ModelUsage = {
  inputTokens: number
  outputTokens: number
  cacheReadInputTokens: number
  cacheCreationInputTokens: number
  webSearchRequests: number
  costUSD: number
  contextWindow: number
}

// 結果メッセージからアクセス
const result = await query({ prompt: "..." });

// result.modelUsageはモデル名からModelUsageへのマップ
for (const [modelName, usage] of Object.entries(result.modelUsage)) {
  console.log(`${modelName}: $${usage.costUSD.toFixed(4)}`);
  console.log(`  Input tokens: ${usage.inputTokens}`);
  console.log(`  Output tokens: ${usage.outputTokens}`);
}

完全な型定義については、TypeScript SDKリファレンスを参照してください。

実装：コスト追跡システム

コスト追跡システムの実装の完全な例を以下に示します：

import { query } from "@anthropic-ai/claude-agent-sdk";

class CostTracker {
  private processedMessageIds = new Set<string>();
  private stepUsages: Array<any> = [];
  
  async trackConversation(prompt: string) {
    const result = await query({
      prompt,
      options: {
        onMessage: (message) => {
          this.processMessage(message);
        }
      }
    });
    
    return {
      result,
      stepUsages: this.stepUsages,
      totalCost: result.usage?.total_cost_usd || 0
    };
  }
  
  private processMessage(message: any) {
    // 使用量を持つアシスタントメッセージのみ処理
    if (message.type !== 'assistant' || !message.usage) {
      return;
    }
    
    // このメッセージIDが既に処理済みの場合はスキップ
    if (this.processedMessageIds.has(message.id)) {
      return;
    }
    
    // 処理済みとしてマークし、使用量を記録
    this.processedMessageIds.add(message.id);
    this.stepUsages.push({
      messageId: message.id,
      timestamp: new Date().toISOString(),
      usage: message.usage,
      costUSD: this.calculateCost(message.usage)
    });
  }
  
  private calculateCost(usage: any): number {
    // ここに料金計算を実装
    // これは簡略化された例です
    const inputCost = usage.input_tokens * 0.00003;
    const outputCost = usage.output_tokens * 0.00015;
    const cacheReadCost = (usage.cache_read_input_tokens || 0) * 0.0000075;
    
    return inputCost + outputCost + cacheReadCost;
  }
}

// 使用方法
const tracker = new CostTracker();
const { result, stepUsages, totalCost } = await tracker.trackConversation(
  "Analyze and refactor this code"
);

console.log(`Steps processed: ${stepUsages.length}`);
console.log(`Total cost: $${totalCost.toFixed(4)}`);

エッジケースの処理

出力トークンの不一致

まれに、同じIDを持つメッセージで異なるoutput_tokens値が観察される場合があります。この場合：

最大値を使用する - グループ内の最後のメッセージが通常、正確な合計を含んでいます
合計コストと照合する - 結果メッセージのtotal_cost_usdが正式な値です
不整合を報告する - Claude Code GitHubリポジトリでイシューを提出してください

キャッシュトークンの追跡

プロンプトキャッシュを使用する場合、これらのトークンタイプを個別に追跡してください：

interface CacheUsage {
  cache_creation_input_tokens: number;
  cache_read_input_tokens: number;
  cache_creation: {
    ephemeral_5m_input_tokens: number;
    ephemeral_1h_input_tokens: number;
  };
}

ベストプラクティス

重複排除にメッセージIDを使用する: 二重課金を避けるため、処理済みのメッセージIDを常に追跡する
結果メッセージを監視する: 最終結果には正式な累積使用量が含まれる
ログを実装する: 監査とデバッグのためにすべての使用量データをログに記録する
障害を適切に処理する: 会話が失敗した場合でも部分的な使用量を追跡する
ストリーミングを考慮する: ストリーミングレスポンスの場合、メッセージの到着に応じて使用量を蓄積する

使用量フィールドリファレンス

各使用量オブジェクトには以下が含まれます：

input_tokens: 処理されたベース入力トークン
output_tokens: レスポンスで生成されたトークン
cache_creation_input_tokens: キャッシュエントリの作成に使用されたトークン
cache_read_input_tokens: キャッシュから読み取られたトークン
service_tier: 使用されたサービスティア（例：「standard」）
total_cost_usd: USD単位の合計コスト（結果メッセージのみ）

例：課金ダッシュボードの構築

課金ダッシュボード用に使用量データを集計する方法は以下の通りです：

class BillingAggregator {
  private userUsage = new Map<string, {
    totalTokens: number;
    totalCost: number;
    conversations: number;
  }>();
  
  async processUserRequest(userId: string, prompt: string) {
    const tracker = new CostTracker();
    const { result, stepUsages, totalCost } = await tracker.trackConversation(prompt);
    
    // ユーザーの合計を更新
    const current = this.userUsage.get(userId) || {
      totalTokens: 0,
      totalCost: 0,
      conversations: 0
    };
    
    const totalTokens = stepUsages.reduce((sum, step) => 
      sum + step.usage.input_tokens + step.usage.output_tokens, 0
    );
    
    this.userUsage.set(userId, {
      totalTokens: current.totalTokens + totalTokens,
      totalCost: current.totalCost + totalCost,
      conversations: current.conversations + 1
    });
    
    return result;
  }
  
  getUserBilling(userId: string) {
    return this.userUsage.get(userId) || {
      totalTokens: 0,
      totalCost: 0,
      conversations: 0
    };
  }
}

コストと使用量の追跡

SDKコスト追跡

トークン使用量の理解

主要な概念

使用量レポートの構造

単一ツール使用 vs 並列ツール使用

メッセージフローの例

重要な使用量ルール

1. 同じID = 同じ使用量

2. ステップごとに1回だけ課金

3. 結果メッセージには累積使用量が含まれる

4. モデルごとの使用量内訳

実装：コスト追跡システム

エッジケースの処理

出力トークンの不一致

キャッシュトークンの追跡

ベストプラクティス

使用量フィールドリファレンス

例：課金ダッシュボードの構築

関連ドキュメント

コストと使用量の追跡

SDKコスト追跡

トークン使用量の理解

主要な概念

使用量レポートの構造

単一ツール使用 vs 並列ツール使用

メッセージフローの例

重要な使用量ルール

1. 同じID = 同じ使用量

2. ステップごとに1回だけ課金

3. 結果メッセージには累積使用量が含まれる

4. モデルごとの使用量内訳

実装：コスト追跡システム

エッジケースの処理

出力トークンの不一致

キャッシュトークンの追跡

ベストプラクティス

使用量フィールドリファレンス

例：課金ダッシュボードの構築

関連ドキュメント