Agent Usage Tracker 是一个专为 AI 代理设计的本地监控工具，采用 TypeScript 与 SQLite 技术栈，旨在帮助开发者在代理运行时实时追踪 token 消耗、计算模型费用并管理预算阈值。该工具通过轻量级的本地数据库持久化使用数据，确保即使在长时间运行或复杂交互场景中也能保持数据的准确性与可追溯性。其核心设计围绕三个关键模块展开：UsageTracker 负责记录和存储每次交互的 token 数量及元数据；CostCalculator 提供灵活的定价目录，支持按不同模型动态计算成本；BudgetManager 则实现预算策略评估，可在超出预设阈值时发出警告或主动阻止进一步操作。整个系统无需依赖外部服务，完全在本地运行，非常适合对隐私和稳定性有高要求的开发环境。 该工具特别适用于需要精细化控制 AI 服务开销的项目场景。无论是构建多智能体协作系统、自动化内容生成流水线，还是企业级对话应用，都能通过 Agent Usage Tracker 实现对资源使用的透明化管理。它不仅能帮助开发者避免因突发高负载导致的意外费用激增，还能为产品运营提供详实的使用分析报告。此外，由于所有数据均存储于本地 SQLite 数据库，因此具备良好的可移植性和调试便利性，便于集成到现有 Node.js 工作流中。整体架构简洁高效，测试用例完备，方便二次开发与定制扩展。
核心功能特点
- 实时追踪 AI 代理的 prompt 与 completion tokens 使用量，并持久化存储至 SQLite 数据库
- 基于模型 ID 动态调用定价表，自动计算每笔交互产生的实际费用
- 支持设置滑动窗口或固定周期的预算策略，自动触发警告或阻断超额请求
- 提供按时间窗口、会话 ID 或模型分类的聚合统计报告功能
- 内置示例代码与完整测试套件，便于快速集成与行为验证
适用场景
Agent Usage Tracker 最典型的应用场景是那些需要严格控制 AI 服务成本的自动化系统。例如，在一个持续运行的客服机器人集群中，每个实例都会频繁调用大语言模型处理用户请求。若缺乏用量监控，很容易因某个时段流量突增而导致月度账单失控。此时，开发者可通过 BudgetManager 设定每日最大支出限额，并在每次发起新请求前调用 evaluateBudget 方法进行预检，一旦接近阈值即暂停服务或降级响应质量，从而有效防止预算超支。另一个常见用例是内容创作平台，该平台同时接入多个第三方 API（如 GPT-4、Claude 等），各模型单价差异显著。借助 CostCalculator 维护一份统一的定价映射表，系统可在后台自动换算出每条生成内容的真实成本，辅助运营团队优化资源配置。 对于研发阶段的应用而言，Agent Usage Tracker 同样极具价值。当工程师正在调试一个多步骤推理代理时，他们往往希望了解每一步骤消耗了多少 token，以及总耗时与成本之间的关系。通过调用 getTimeSeries 或 getUsageSummary 接口，可以生成可视化的趋势图表，直观展示性能瓶颈所在。此外，在 A/B 测试不同提示词模板的效果时，对比各版本对应的 token 使用效率也变得异常简单。由于所有数据都保留在本地，这些数据不会泄露给任何外部服务器，保障了敏感业务逻辑的安全性。最后值得一提的是，即便是在单元测试环境中，也可以将 SQLite 路径设为 :memory: 模式，实现零磁盘占用的快速验证流程，极大提升了 CI/CD 管道的执行速度。