Отслеживание затрат и использования

​

Понимание использования токенов

• TypeScript предоставляет разбивку токенов по шагам для каждого сообщения ассистента (message.message.id, message.message.usage), стоимость для каждой модели через modelUsage в результирующем сообщении и совокупный итог в результирующем сообщении.
• Python предоставляет разбивку токенов по шагам для каждого сообщения ассистента как message.usage и message.message_id, стоимость для каждой модели через model_usage в результирующем сообщении и совокупный итог в результирующем сообщении как total_cost_usd.

• Вызов query(): одно вызывание функции query() SDK. Один вызов может включать несколько шагов: Claude отвечает, использует инструменты, получает результаты и отвечает снова. Каждый вызов создает одно сообщение result в конце, за исключением режима потоковой передачи входных данных, где один вызов query() содержит несколько ходов пользователя и каждый ход выдает свое собственное сообщение result.
• Шаг: один цикл запроса/ответа в рамках вызова query(). Каждый шаг создает сообщения ассистента с использованием токенов.
• Сеанс: серия вызовов query(), связанных идентификатором сеанса через опцию resume. Результаты возобновленного вызова сообщают об общих расходах сеанса, а не только о расходах этого вызова. См. Накопление стоимости при нескольких вызовах для получения информации о том, как переносятся итоги.

​

Отслеживание затрат в режиме потоковой передачи входных данных

• usage: охватывает только этот ход и в его пределах только основной цикл агента, а не какие-либо подагенты, которые он запустил.
• total_cost_usd и modelUsage, или model_usage в Python: содержат текущий итог для всего вызова на данный момент, плюс любые расходы, восстановленные при возобновлении вызовом сеанса.

• Собственный результат хода /clear: охватывает только то, что было запущено с момента сброса, и содержит новый session_id.
• Каждый последующий результат: продолжает отсчет с этого сброса.
• Последний результат перед каждым /clear: содержит итог для ходов с момента предыдущего сброса.

​

Получить общую стоимость запроса

• В Python это поле типизировано как опциональное, поэтому проверьте, что оно не равно None перед его чтением.
• Результаты успеха и ошибки оба содержат его, хотя финальный результат сбоя сеанса может содержать его обнуленным.

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

​

Отслеживание использования на каждом шаге и для каждой модели

​

Отслеживание использования на каждом шаге

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

​

Разбивка использования по моделям

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

​

Накопление затрат при нескольких вызовах

• Независимые вызовы без опции resume или continue: каждый результат охватывает только свой собственный вызов, поэтому складывайте итоги самостоятельно, как это делается в примерах ниже.
• Вызовы, которые возобновляют один и тот же сеанс: Claude Code сохраняет итоги сеанса в его транскрипт при нормальном завершении процесса и восстанавливает их, когда последующий вызов возобновляет или разветвляет сеанс. Каждый результат уже включает более ранние расходы сеанса. Прочитайте последний результат для получения общей суммы сеанса; суммирование результатов приводит к двойному подсчёту восстановленных расходов. До версии 2.1.277 сеанс, который вы возобновили через SDK или claude -p, начинал свои итоги с нуля, поэтому результаты каждого вызова охватывали только этот вызов.

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

​

Обработка ошибок, кеширование и подсчет выходных токенов

​

Чтение выходных токенов из результирующего сообщения

​

Отслеживание затрат при неудачных разговорах

• error_during_execution после сбоя сеанса: каждое поле затрат может быть обнулено.
• error_max_budget_usd: usage исключает ответ, который превысил бюджет, в то время как total_cost_usd и modelUsage включают его.

​

Восстановление итогов после сбоя сеанса

1. Используйте результат хода перед сбоем. В режиме потокового ввода он содержит текущий итог, описанный в Track costs in streaming input mode. Перейдите к шагу 2, если этот результат не может вам помочь:
   • Вызов был одноразовым, поэтому более ранний результат не существует.
   • Сбой произошел на первом ходу.
   • Ход перед сбоем был самим /clear, поэтому его результат охватывает только сброс.
2. Вместо этого суммируйте usage в сообщениях ассистента, считая каждый ответ API один раз, как это делает пример Track per-step usage. В режиме одноразового ввода суммируйте все из них; в режиме потокового ввода суммируйте те, которые пришли после последнего результата. Это дает вам входные токены и токены кеша основного цикла. Использование подагента не восстанавливается таким образом, и выходные токены или стоимость в USD тоже, потому что выходные токены на шаг — это заполнитель.

​

Отслеживание токенов кеша

• cache_creation_input_tokens: токены, используемые для создания новых записей кеша (взимаются по более высокой ставке, чем стандартные входные токены).
• cache_read_input_tokens: токены, прочитанные из существующих записей кеша (взимаются по сниженной ставке).

​

Расширение TTL кеша подсказок до одного часа

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

• Основной разговор: переменная окружения CLAUDE_CODE_PROMPT_CACHE_TTL или параметр promptCacheTtl
• Все остальное: переменная окружения CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL или параметр subagentPromptCacheTtl

​

Связанная документация

• Справочник TypeScript SDK - Полная документация API
• Обзор SDK - Начало работы с SDK
• Разрешения SDK - Управление разрешениями инструментов