Rastreamento de Custos do SDK

O Claude Agent SDK fornece informações detalhadas de uso de tokens para cada interação com Claude. Este guia explica como rastrear adequadamente os custos e entender o relatório de uso, especialmente ao lidar com usos de ferramentas paralelas e conversas em várias etapas.

Para documentação completa da API, consulte a referência do SDK TypeScript.

Entendendo o Uso de Tokens

Quando Claude processa solicitações, ele relata o uso de tokens no nível da mensagem. Esses dados de uso são essenciais para rastrear custos e faturar usuários apropriadamente.

Conceitos-Chave

1. Etapas: Uma etapa é um único par de solicitação/resposta entre sua aplicação e Claude
2. Mensagens: Mensagens individuais dentro de uma etapa (texto, usos de ferramentas, resultados de ferramentas)
3. Uso: Dados de consumo de tokens anexados a mensagens do assistente

Estrutura de Relatório de Uso

Uso de Ferramentas Único vs Paralelo

Quando Claude executa ferramentas, o relatório de uso difere dependendo se as ferramentas são executadas sequencialmente ou em paralelo:

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

// Exemplo: Rastreamento de uso em uma conversa
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);
      }
    }
  }
});

Exemplo de Fluxo de Mensagens

Aqui está como as mensagens e o uso são relatados em uma conversa típica com várias etapas:

<!-- Etapa 1: Solicitação inicial com usos de ferramentas paralelas -->
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)

<!-- Etapa 2: Resposta de acompanhamento -->
assistant (text)      { id: "msg_2", usage: { output_tokens: 98, ... } }

Regras Importantes de Uso

1. Mesmo ID = Mesmo Uso

Todas as mensagens com o mesmo campo id relatam uso idêntico. Quando Claude envia várias mensagens na mesma rodada (por exemplo, texto + usos de ferramentas), elas compartilham o mesmo ID de mensagem e dados de uso.

// Todas essas mensagens têm o mesmo ID e uso
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 } }
];

// Cobrar apenas uma vez por ID de mensagem único
const uniqueUsage = messages[0].usage; // Mesmo para todas as mensagens com este ID

2. Cobrar Uma Vez Por Etapa

Você deve cobrar dos usuários apenas uma vez por etapa, não para cada mensagem individual. Quando você vê várias mensagens do assistente com o mesmo ID, use o uso de qualquer uma delas.

3. Mensagem de Resultado Contém Uso Cumulativo

A mensagem final result contém o uso cumulativo total de todas as etapas na conversa:

// Resultado final inclui uso total
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. Detalhamento de Uso Por Modelo

A mensagem de resultado também inclui modelUsage, que fornece dados de uso por modelo autoritativos. Como total_cost_usd, este campo é preciso e adequado para fins de faturamento. Isso é especialmente útil ao usar vários modelos (por exemplo, Haiku para subagentos, Opus para o agente principal).

// modelUsage fornece detalhamento por modelo
type ModelUsage = {
  inputTokens: number
  outputTokens: number
  cacheReadInputTokens: number
  cacheCreationInputTokens: number
  webSearchRequests: number
  costUSD: number
  contextWindow: number
}

// Acessar da mensagem de resultado
const result = await query({ prompt: "..." });

// result.modelUsage é um mapa de nome de modelo para 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}`);
}

Para as definições de tipo completas, consulte a referência do SDK TypeScript.

Implementação: Sistema de Rastreamento de Custos

Aqui está um exemplo completo de implementação de um sistema de rastreamento de custos:

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) {
    // Processar apenas mensagens do assistente com uso
    if (message.type !== 'assistant' || !message.usage) {
      return;
    }
    
    // Pular se já processamos este ID de mensagem
    if (this.processedMessageIds.has(message.id)) {
      return;
    }
    
    // Marcar como processado e registrar uso
    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 {
    // Implementar seu cálculo de preço aqui
    // Este é um exemplo simplificado
    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;
  }
}

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

Tratamento de Casos Extremos

Discrepâncias de Tokens de Saída

Em casos raros, você pode observar valores diferentes de output_tokens para mensagens com o mesmo ID. Quando isso ocorre:

1. Use o valor mais alto - A mensagem final em um grupo normalmente contém o total preciso
2. Verifique contra o custo total - O total_cost_usd na mensagem de resultado é autoritativo
3. Relate inconsistências - Abra problemas no repositório Claude Code GitHub

Rastreamento de Tokens de Cache

Ao usar cache de prompt, rastreie esses tipos de token separadamente:

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

Melhores Práticas

1. Use IDs de Mensagem para Deduplicação: Sempre rastreie IDs de mensagem processados para evitar cobrança dupla
2. Monitore a Mensagem de Resultado: O resultado final contém uso cumulativo autoritativo
3. Implemente Logging: Registre todos os dados de uso para auditoria e depuração
4. Trate Falhas Graciosamente: Rastreie uso parcial mesmo se uma conversa falhar
5. Considere Streaming: Para respostas de streaming, acumule uso conforme as mensagens chegam

Referência de Campos de Uso

Cada objeto de uso contém:

• input_tokens: Tokens de entrada base processados
• output_tokens: Tokens gerados na resposta
• cache_creation_input_tokens: Tokens usados para criar entradas de cache
• cache_read_input_tokens: Tokens lidos do cache
• service_tier: O nível de serviço usado (por exemplo, "standard")
• total_cost_usd: Custo total em USD (apenas na mensagem de resultado)

Exemplo: Construindo um Painel de Faturamento

Aqui está como agregar dados de uso para um painel de faturamento:

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);
    
    // Atualizar totais do usuário
    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
    };
  }
}

Documentação Relacionada

• Referência do SDK TypeScript - Documentação completa da API
• Visão Geral do SDK - Começando com o SDK
• Permissões do SDK - Gerenciando permissões de ferramentas