Tracciare costi e utilizzo

​

Comprendere l’utilizzo dei token

• TypeScript fornisce suddivisioni dei token per fase su ogni messaggio dell’assistente (message.message.id, message.message.usage), costo per modello tramite modelUsage sul messaggio risultato, e un totale cumulativo sul messaggio risultato.
• Python fornisce suddivisioni dei token per fase su ogni messaggio dell’assistente come message.usage e message.message_id, costo per modello tramite model_usage sul messaggio risultato, e il totale cumulativo sul messaggio risultato come total_cost_usd.

• Chiamata query(): una singola invocazione della funzione query() dell’SDK. Una singola chiamata può coinvolgere più fasi: Claude risponde, utilizza strumenti, ottiene risultati e risponde di nuovo. Ogni chiamata produce un messaggio result alla fine, tranne in modalità input streaming, dove una chiamata query() comporta più turni dell’utente e ogni turno emette il proprio messaggio result.
• Fase: un singolo ciclo richiesta/risposta all’interno di una chiamata query(). Ogni fase produce messaggi dell’assistente con utilizzo dei token.
• Sessione: una serie di chiamate query() collegate da un ID di sessione tramite l’opzione resume. I risultati di una chiamata ripresa segnalano la spesa totale della sessione, non solo quella della chiamata stessa. Vedere Accumulare i costi su più chiamate per come i totali si trasferiscono.

​

Tracciare i costi in modalità di input in streaming

• usage: copre solo quel turno, e all’interno di esso solo il ciclo principale dell’agente, non eventuali subagenti che ha eseguito.
• total_cost_usd e modelUsage, o model_usage in Python: portano il totale cumulativo per l’intera chiamata fino a quel momento, più qualsiasi spesa ripristinata quando la chiamata ha ripreso una sessione.

• Il risultato del turno /clear: copre solo ciò che è stato eseguito dal ripristino, e porta un nuovo session_id.
• Ogni risultato successivo: continua a contare da quel ripristino.
• L’ultimo risultato prima di ogni /clear: contiene il totale per i turni dal ripristino precedente.

​

Ottenere il costo totale di una query

• In Python il campo è tipizzato come opzionale, quindi verificate che non sia None prima di leggerlo.
• I risultati di successo e di errore lo portano entrambi, anche se il risultato finale di un crash della sessione potrebbe portarlo azzerato.

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

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "result") {
      console.log(`Total cost: $${message.total_cost_usd}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, it still carried total_cost_usd and the
  // branch above has already run; connection or process failures yield
  // no result message.
  console.error(`Session ended with an error: ${error}`);
}

from claude_agent_sdk import query, ResultMessage
import asyncio


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, ResultMessage):
                print(f"Total cost: ${message.total_cost_usd or 0}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the branch above has already run;
        # connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

​

Tracciare l’utilizzo per step e per modello

​

Tracciare l’utilizzo per step

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

const seenIds = new Set<string>();
let totalInputTokens = 0;
let resultOutputTokens = 0;

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant" && !message.parent_tool_use_id) {
      const msgId = message.message.id;

      // Parallel tool calls share the same ID, only count once
      if (!seenIds.has(msgId)) {
        seenIds.add(msgId);
        totalInputTokens += message.message.usage.input_tokens;
      }
    }
    if (message.type === "result") {
      // Per-step output_tokens is a placeholder; the result message
      // carries the accumulated output total.
      resultOutputTokens = message.usage.output_tokens;
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result, so the
  // input total below still reflects the steps that ran before the failure.
  console.error(`Session ended with an error: ${error}`);
}

console.log(`Steps: ${seenIds.size}`);
console.log(`Input tokens: ${totalInputTokens}`);
console.log(`Output tokens: ${resultOutputTokens}`);

​

Dettagliare l’utilizzo per modello

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

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type !== "result") continue;

    for (const [modelName, usage] of Object.entries(message.modelUsage)) {
      console.log(`${modelName}: $${usage.costUSD.toFixed(4)}`);
      console.log(`  Input tokens: ${usage.inputTokens}`);
      console.log(`  Output tokens: ${usage.outputTokens}`);
      console.log(`  Cache read: ${usage.cacheReadInputTokens}`);
      console.log(`  Cache creation: ${usage.cacheCreationInputTokens}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the per-model breakdown above has already
  // printed; connection or process failures yield no result message.
  console.error(`Session ended with an error: ${error}`);
}

​

Accumulare i costi su più chiamate

• Chiamate indipendenti, senza opzione resume o continue: ogni risultato copre solo la propria chiamata, quindi aggiungete i totali voi stessi, come fanno gli esempi seguenti.
• Chiamate che riprendono la stessa sessione: Claude Code salva i totali della sessione nel suo transcript quando il processo esce normalmente e li ripristina quando una chiamata successiva riprende o effettua il fork della sessione. Ogni risultato include già la spesa precedente della sessione. Leggete l’ultimo risultato per il totale della sessione; sommare i risultati conta due volte la spesa ripristinata. Prima della v2.1.277, una sessione che avevate ripreso tramite l’SDK o claude -p iniziava i suoi totali a zero, quindi i risultati di ogni chiamata coprivano solo quella chiamata.

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

// Track cumulative cost across multiple query() calls
let totalSpend = 0;

const prompts = [
  "Read the files in src/ and summarize the architecture",
  "List all exported functions in src/auth.ts"
];

for (const prompt of prompts) {
  try {
    for await (const message of query({ prompt })) {
      if (message.type === "result") {
        totalSpend += message.total_cost_usd;
        console.log(`This call: $${message.total_cost_usd}`);
      }
    }
  } catch (error) {
    // A single-shot query() throws after yielding an error result. If the
    // failure was an error result, this call's cost was already counted;
    // connection or process failures yield no result message. Continue
    // with the next prompt.
    console.error(`Call failed: ${error}`);
  }
}

console.log(`Total spend: $${totalSpend.toFixed(4)}`);

from claude_agent_sdk import query, ResultMessage
import asyncio


async def main():
    # Track cumulative cost across multiple query() calls
    total_spend = 0.0

    prompts = [
        "Read the files in src/ and summarize the architecture",
        "List all exported functions in src/auth.ts",
    ]

    for prompt in prompts:
        try:
            async for message in query(prompt=prompt):
                if isinstance(message, ResultMessage):
                    cost = message.total_cost_usd or 0
                    total_spend += cost
                    print(f"This call: ${cost}")
        except Exception as error:
            # A single-shot query() raises after yielding an error result. If
            # the failure was an error result, this call's cost was already
            # counted; connection or process failures yield no result message.
            # Continue with the next prompt.
            print(f"Call failed: {error}")

    print(f"Total spend: ${total_spend:.4f}")


asyncio.run(main())

​

Gestire errori, caching e conteggi dei token di output

​

Leggere i token di output dal messaggio di risultato

​

Tracciare i costi su conversazioni non riuscite

• error_during_execution dopo un arresto anomalo della sessione: ogni campo di costo può essere azzerato.
• error_max_budget_usd: usage omette la risposta che ha superato il budget, mentre total_cost_usd e modelUsage la includono.

​

Recuperare i totali dopo un arresto anomalo della sessione

1. Utilizzare il risultato del turno prima dell’arresto anomalo. In modalità input streaming, contiene il totale in esecuzione descritto in Track costs in streaming input mode. Passare al passaggio 2 invece quando quel risultato non può aiutarti:
   • La chiamata era single-shot, quindi non esiste alcun risultato precedente.
   • L’arresto anomalo è avvenuto al primo turno.
   • Il turno prima dell’arresto anomalo era il /clear stesso, quindi il suo risultato copre solo il ripristino.
2. Sommare invece il usage sui messaggi dell’assistente, contando ogni risposta API una volta, come fa l’esempio Track per-step usage. In modalità single-shot, sommare tutti; in modalità input streaming, sommare quelli arrivati dopo l’ultimo risultato. Questo ti dà i token di input e cache del ciclo principale. L’utilizzo dei subagent non è recuperabile in questo modo, e nemmeno i token di output o il costo in USD, perché il output_tokens per passaggio è un segnaposto.

​

Tracciare i token della cache

• cache_creation_input_tokens: token utilizzati per creare nuove voci della cache (addebitati a una tariffa più alta rispetto ai token di input standard).
• cache_read_input_tokens: token letti da voci della cache esistenti (addebitati a una tariffa ridotta).

​

Estendere il TTL della cache del prompt a un’ora

from claude_agent_sdk import ClaudeAgentOptions, query
import asyncio


async def main():
    options = ClaudeAgentOptions(
        env={
            "CLAUDE_CODE_USE_BEDROCK": "1",
            "ENABLE_PROMPT_CACHING_1H": "1",
        },
    )

    async for message in query(prompt="Summarize this project", options=options):
        print(message)


asyncio.run(main())

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

const options = {
  env: {
    ...process.env,
    CLAUDE_CODE_USE_BEDROCK: "1",
    ENABLE_PROMPT_CACHING_1H: "1",
  },
};

for await (const message of query({ prompt: "Summarize this project", options })) {
  console.log(message);
}

• Conversazione principale: la variabile di ambiente CLAUDE_CODE_PROMPT_CACHE_TTL, o l’impostazione promptCacheTtl
• Tutto il resto: la variabile di ambiente CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, o l’impostazione subagentPromptCacheTtl

​

Documentazione correlata

• Riferimento TypeScript SDK - Documentazione API completa
• Panoramica SDK - Introduzione all’SDK
• Autorizzazioni SDK - Gestione delle autorizzazioni degli strumenti