Skip to content

About

Agent-Trace 是 AI Agent 的本地 DevTools,用来追踪、可视化和调试 LLM 调用与工具调用。

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Agent-Trace 图标

Agent-Trace

本地优先的 AI Agent 运行观测、用量分析与故障诊断工具。

English · 完整文档 · 变更记录 · 参与贡献

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 桌面界面"]
Loading

运行要求

  • 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 dev

Tip

不希望首次启动扫描本地会话时,可运行 node packages/cli/dist/index.js dev --usage-scan=false。

四种数据接入方式

TypeScript SDK

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 失败不会改变被观测函数的返回值或异常语义。

Python SDK

从源码工作区安装:

pip install -e packages/sdk-python
from 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 投递。

Codex / Claude Code Hooks

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 等价估算,不代表订阅产品的实际账单。

处理敏感数据前请阅读隐私与安全。

文档

从文档索引按角色进入,常用入口包括:

About

Agent-Trace 是 AI Agent 的本地 DevTools,用来追踪、可视化和调试 LLM 调用与工具调用。

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages