Skip to main content
控制与可观测性

成本和用量

Qoder Agent SDK 会同时透出 Credits 和 Token 用量数据。它们的用途和计量方式不同：
  • Credits 是 Qoder 的资源用量单位。本文重点介绍如何查询 Credits。
  • Token 反映模型输入、输出和缓存的文本量，不能直接换算成 Credits。
有关 Credits 的产品规则、额度类型和扣减顺序，见 Credits。

查看 Credits 用量

根据需要统计的范围，SDK 提供账号额度、单次模型请求和当前会话累计三种 Credits 用量数据：
你要查看的内容TypeScriptPython数据范围
账号额度和当前会话用量q.getUsageInfo()client.get_usage_info()账号与当前 CLI 会话的实时快照
单次模型请求用量message.message.usagemessage.usage单个已完成的模型请求
当前会话累计用量result.total_credits、result.modelUsageresult.total_credits、result.model_usage当前 CLI 会话从开始到 Result 消息的累计值
如果只想在业务代码中查询当前额度，不需要等待一次 Agent 任务结束，使用 getUsageInfo() / get_usage_info()。如果需要记录每次模型请求或在会话结束时结算，则从消息流读取。 TypeScript 中两处会话统计的命名不同：getUsageInfo().session 使用 total_credits 和 model_usage，Result 消息使用 total_credits 和 modelUsage。Python 在两处均使用 snake_case。

单独查询 Credits 用量

getUsageInfo() / get_usage_info() 返回账号额度信息，并在可用时通过 session 返回当前 CLI 会话累计的 Credits。 
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

let releaseInput: (() => void) | undefined;

// Keep the CLI session alive without starting an Agent turn.
async function* noPrompt() {
  await new Promise<void>((resolve) => {
    releaseInput = resolve;
  });
}

const q = query({
  prompt: noPrompt(),
  options: {
    auth: accessTokenFromEnv(),
  },
});

try {
  await q.initializationResult();

  const usage = await q.getUsageInfo();
  if (usage === null) {
    console.log('Usage is unavailable.');
  } else {
    console.log('Plan:', usage.userType);
    console.log('Overall usage:', usage.totalUsagePercentage);
    console.log('Plan Credits remaining:', usage.userQuota?.remaining);

    if (usage.session) {
      console.log('Session Credits:', usage.session.total_credits);
      for (const [model, modelUsage] of Object.entries(
        usage.session.model_usage,
      )) {
        console.log(model, modelUsage.credits);
      }
    }
  }
} finally {
  releaseInput?.();
  await q.close();
}
常用返回字段：
字段说明
userQuota当前套餐包含的额度，包含 total、used、remaining、percentage 和 unit
addOnQuota加购额度；账号没有加购额度时可能不存在，detailUrl 存在时指向用量明细页
orgResourcePackage组织共享资源包，使用 cap 表示总额度，并提供 used、remaining、percentage、available 和 unit
totalUsagePercentage账号所有可用额度的整体用量百分比
isQuotaExceeded当前账号的可用额度是否已耗尽
session.total_credits当前 CLI 会话累计 Credits
session.model_usage当前会话按模型累计的 Credits
账号额度与 session 是相互独立的数据。账号额度接口暂时不可用时，SDK 仍可能返回只有 session 的对象，因此不要通过 userId 或 userQuota 是否存在来判断会话用量是否可用。 返回 null / None 表示本次未获取到可用的账号额度或会话 Credits。除未登录、旧版 CLI 不支持外，控制请求失败或服务暂时不可用也可能导致该结果。 完整 API 定义见 SDK References。

从会话消息读取 Credits

消息流可以同时提供单次请求和会话累计两个统计范围。下面的示例会打印：
  • Assistant 消息中的单次模型请求 Credits；
  • Result 消息中的当前会话累计 Credits；
  • Result 消息中按模型累计的 Credits。
一次 Agent 任务可能触发多次模型请求，因此消息流中可能出现多条带有请求级 Credits 的 Assistant 消息。如果只需要当前会话总量，以 Result 消息的 total_credits 为准，不要再与请求级 credits 相加。 
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

for await (const message of query({
  prompt: 'Summarize this repository.',
  options: {
    auth: accessTokenFromEnv(),
  },
})) {
  if (message.type === 'assistant') {
    const usage = message.message.usage;

    if (typeof usage?.credits === 'number') {
      console.log('Request Credits:', usage.credits);
      console.log('Original Credits:', usage.original_credits);
      console.log('Billable:', usage.billable);
    }
  }

  if (message.type === 'result') {
    if (typeof message.total_credits === 'number') {
      console.log('Session Credits:', message.total_credits);
    }

    for (const [model, modelUsage] of Object.entries(message.modelUsage)) {
      if (typeof modelUsage.credits === 'number') {
        console.log(model, modelUsage.credits);
      }
    }
  }
}

字段含义

字段统计范围说明
credits单次模型请求优惠或折扣生效后的 Credits
original_credits单次模型请求优惠或折扣生效前的 Credits；没有该数据时省略
billable单次模型请求该请求是否计入用户的 Credits 用量
total_credits当前会话累计从当前 CLI 会话开始累计的 Credits
TypeScript modelUsage[model].credits当前会话累计指定模型在当前会话累计的 Credits
Python model_usage[model]["credits"]当前会话累计指定模型在当前会话累计的 Credits
注意：不要从 Result 消息的 usage 字段读取 Credits。result.usage 用于 Token 等用量数据，不包含请求级的 credits、original_credits 或 billable。请求级 Credits 应从 Assistant 消息读取，会话累计 Credits 应从 total_credits 或按模型统计字段读取。

兼容性说明

  • Credits 相关字段为可选字段，以兼容旧版 CLI。读取前应判断字段是否存在，不要把缺失值当作 0。
  • total_credits 是会话累计值。不要把多条 Result 消息中的该字段再次相加，否则可能重复计算。
  • 请求级 credits 与 Result 中的会话累计 Credits 是同一批消耗的不同统计范围，不要把二者相加。
  • Token 字段（例如 input_tokens、output_tokens）与 Credits 没有固定换算关系。
  • 如果需要展示账号剩余额度，以 getUsageInfo() / get_usage_info() 返回的额度桶为准，不要通过累加会话消息自行推算。

下一步

  • Credits — Credits 类型、扣减顺序和用量查看方式
  • SDK References — 完整消息与控制 API
快速开始
核心概念
对话与会话
扩展能力
控制与可观测性
参考