本地优先的 AI Agent 运行观测、用量分析与故障诊断工具。
Agent-Trace 把模型调用、工具执行、Token、成本、耗时、错误和本地会话历史汇总到本机 SQLite,并通过 Web 或 Windows 桌面界面呈现可搜索、可比较、可诊断的运行轨迹。核心采集、存储和展示不依赖托管后端。
- TypeScript SDK:显式记录自定义 Agent 的 Run、LLM 与工具调用。
- Python SDK:嵌套 Step、同步/异步装饰器,以及 OpenAI 和 LangChain 适配。
- Codex/Claude Code Hooks:无需修改 Agent 源码即可采集生命周期与工具元数据。
- Codex OTel:接收 OTLP/HTTP JSON 日志中的模型与官方 Token 用量。
- 本地 Usage Scanner:通过
tokscale汇总多客户端会话、Token 与 API 等价成本,并恢复来源支持的 Command/Tool/MCP/Skill 分类。 - Run 分析:事件筛选、时间线、父子调用树、失败检查,以及重试、慢步骤和 Token 热点诊断。
- Token Trace:按日、周、月查看 Token 活跃度、趋势、模型与客户端分布。
- 质量与成本治理:Run 对比、项目分析、预算告警、评测集和多维评分。
- 安全回放:使用内置 Mock Worker 覆盖输入、模拟输出、错误、延迟与超时,不执行用户代码或真实工具。
- 本地治理:Run 项目与标签、维护中心、保留期清理、墓碑恢复、写入前字段脱敏和命令正文采集策略。
- 本地交付:Hono Collector、双语 Next.js Dashboard 和 Windows Electron 桌面包。
flowchart LR
SDK["TypeScript / Python SDK"] --> Collector["Hono Collector<br/>127.0.0.1:4319"]
Hooks["Codex / Claude Code Hooks<br/>Codex OTel"] --> Collector
Scanner["tokscale<br/>本地会话历史"] --> Collector
Collector --> SQLite[("本机 SQLite")]
SQLite --> Dashboard["Next.js Dashboard<br/>localhost:3000"]
Dashboard --> UI["Web / Windows 桌面界面"]
- Node.js
>=22.12.0;仓库的.nvmrc使用 Node.js 22。 - pnpm
>=11.0.7 <12;packageManager和 CI 固定使用 11.0.7。 - Python
>=3.10,仅使用 Python SDK 时需要。 - Windows 桌面安装包只能在 Windows x64 环境构建。
pnpm install --frozen-lockfile
pnpm build
node packages/cli/dist/index.js dev启动后可直接进入以下页面:
| 入口 | 地址 | 用途 |
|---|---|---|
| Runs | http://localhost:3000/runs | 搜索、筛选、比较和诊断 Agent 运行 |
| Token Trace | http://localhost:3000/token-trace | 查看 Token 趋势、活跃日历与模型分布 |
| 分析 | http://localhost:3000/analytics | 按项目、环境、模型或来源分析质量与成本 |
| 评测 | http://localhost:3000/evaluations | 管理评测集、用例和多维评分 |
| 安全回放 | http://localhost:3000/sandbox | 在固定 Mock Worker 中回放 Run |
| 维护 | http://localhost:3000/maintenance | 清理、恢复、压缩,以及配置字段脱敏与命令正文采集 |
Collector 默认监听 http://127.0.0.1:4319。
另开终端生成一条示例 Run:
pnpm --filter simple-agent devTip
不希望首次启动扫描本地会话时,可运行
node packages/cli/dist/index.js dev --usage-scan=false。
import { startRun } from "@agent-trace/sdk";
const run = startRun({
name: "research-agent",
input: { task: "Research MCP ecosystem" }
});
try {
const result = await run.traceTool(
"web_search",
{ query: "MCP ecosystem" },
() => webSearch("MCP ecosystem")
);
await run.end(result);
} catch (error) {
await run.fail(error);
throw error;
}SDK 默认向 http://localhost:4319 投递,单次投递超时 1000 ms;Tracing 失败不会改变被观测函数的返回值或异常语义。
从源码工作区安装:
pip install -e packages/sdk-pythonfrom agent_trace import AgentTraceClient
from agent_trace.integrations.openai import instrument_openai
client = AgentTraceClient()
with client.start_run("research-agent", metadata={"project": "demo"}) as run:
with run.trace_step("retrieval", "load-documents"):
documents = load_documents()
openai_client = instrument_openai(openai_client, run)Python SDK 支持嵌套 Step、同步/异步装饰器、OpenAI 包装器和 LangChain Callback,同样采用有界超时与 fail-open 投递。
node packages/cli/dist/index.js install codex
node packages/cli/dist/index.js install claude-code安装过程只管理带 Agent-Trace 标记的配置,并在修改前创建时间戳备份。完整参数见用户手册。
node packages/cli/dist/index.js usage --once
node packages/cli/dist/index.js usage clients --home <path>敏感项目建议首次扫描前设置 AGENT_TRACE_HISTORY_CONTENT=metadata,避免保存 Prompt 预览。
| 路径 | 职责 |
|---|---|
apps/server |
Hono Collector、SQLite、集成入口与读模型 |
apps/web |
Next.js Dashboard |
apps/desktop |
Electron 主进程与 Windows 打包 |
packages/schema |
Zod 契约与共享 TypeScript 类型 |
packages/sdk-js |
JavaScript/TypeScript Tracing SDK |
packages/sdk-python |
Python Tracing SDK 与框架适配 |
packages/cli |
开发编排、Hooks 管理和本地用量扫描 |
examples |
SDK 与 Hook 冒烟示例 |
pnpm verify等价于依次运行构建、测试、类型检查和 lint;lint 同时执行文档链接、API 路由、环境变量和 CLI 命令一致性检查。测试范围与已知边界见测试文档。
Warning
Collector 没有认证,只应监听回环地址。不要直接暴露到公网或不可信局域网。
- 数据默认保存在本机 SQLite。
- SDK 会保存调用方传入的 input/output,不会自动脱敏。
- 命令默认只保存分类元数据,不保存正文;显式开启完整命令采集后,命令仍可能包含路径、参数或凭据。
- 本地历史默认可保存清理后的 Prompt 预览;可切换为
metadata。 - 所有成本都是 API 等价估算,不代表订阅产品的实际账单。
处理敏感数据前请阅读隐私与安全。
从文档索引按角色进入,常用入口包括: