README

traceroot：持续改进你的 AI Agent 的开源平台。

  [![Y Combinator][y-combinator-image]][y-combinator-url]
  [![License][license-image]][license-url]
  [![X (Twitter)][twitter-image]][twitter-url]
  [![Discord][discord-image]][discord-url]
  [![Documentation][docs-image]][docs-url]
  [![PyPI SDK Downloads][pypi-sdk-downloads-image]][pypi-sdk-downloads-url]
  

  
    Website ·
    Cloud ·
    Documentation ·
    Community
  



  
  
  


⭐ 为本仓库点亮 Star，让更多开发者了解 traceroot，一起壮大社区！

 traceroot

找出你的 Agent 在生产环境中各类问题的规律，再与你的编程 Agent 一起交付经过验证的修复。

https://github.com/user-attachments/assets/2ecf21ce-93b3-41cb-8749-e02b77467357

 核心功能

 将生产故障转化为经过验证的改进

追踪生产运行，使用检测器评估行为，并将反复出现的模式提炼为改进信号。你的编程 Agent 通过 traceroot CLI 分析这些信号、在本地修改代码，再通过离线评测验证改动。发布后，新的生产追踪进入下一轮检测、信号分析与验证，形成持续改进的闭环。

| 步骤 | 描述 |
| ---- | ----------- |
| 追踪 | 查看每次模型调用、工具调用和响应，以及输入、输出、延迟和成本。 |
| 检测 | 定义符合预期的行为，自动标记未达标准的生产运行。 |
| 信号 | 将评审输出聚类为信号。后台编程 Agent 在沙箱中结合追踪与已连接的 GitHub 代码，调查问题并提出修复建议。 |
| 验证 | 基于数据集运行评测并比较版本，衡量改进效果并发现回归问题。 |

 ⭐ 为仓库点亮 Star

如果你喜欢我们正在构建的产品，请为 traceroot 点亮 Star ⭐，帮助更多开发者发现它。


  
    
  


 配置 traceroot

准备好 traceroot 实例（云端或自托管）后，在仪表盘中创建项目，并选择发送第一条追踪的方式：让编程 Agent 通过 CLI 配置埋点，或手动配置 SDK。

 使用编程 Agent



安装 traceroot CLI 并登录：

bash
npm install -g traceroot-cli
traceroot login


然后向你的编程 Agent 提出请求：

text
使用 traceroot CLI 为此应用配置追踪。


 手动配置 SDK

想自己配置埋点？使用 Python SDK 或 TypeScript SDK。以下示例从 TypeScript 应用发送一次带追踪的模型调用。


运行最小 TypeScript 示例

你需要 Node.js、npm、traceroot 项目 API 密钥和 OpenAI API 密钥。自托管时，请将下方的云服务地址替换为你的实例地址。

1. 安装 SDK，在 TypeScript 项目中运行：

sh
npm install @traceroot-ai/traceroot openai


2. 设置 API 密钥：

bash
export TRACEROOT_API_KEY="your-project-api-key"
export TRACEROOT_HOST_URL="https://app.traceroot.ai"
export OPENAI_API_KEY="your-openai-api-key"


3. 追踪一次 Agent 调用。 将以下代码保存为 example.ts：

typescript
import OpenAI from 'openai';
import { TraceRoot, observe } from '@traceroot-ai/traceroot';

TraceRoot.initialize({ instrumentModules: { openAI: OpenAI } });
const openai = new OpenAI();

const myAgent = observe({ name: 'my_agent', type: 'agent' }, async (query: string) = {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: query }],
  });
  return response.choices[0].message.content;
});

async function main() {
  try {
    await myAgent("What's the weather in SF?");
  } finally {
    await TraceRoot.shutdown();
  }
}

main().catch(console.error);


4. 运行 npx tsx example.ts，然后打开项目的 Traces 页面查看 Agent 运行记录。此示例会发起一次 OpenAI API 调用。



 开始使用 traceroot

 traceroot Cloud

创建账号，无需自行部署即可开始使用。

 自托管

安装 Git、Docker Compose 和 Make 后，在本地运行：

bash
git clone https://github.com/traceroot-ai/traceroot.git
cd traceroot
cp .env.example .env
make prod-lite


打开 localhost:3000。配置与部署详情请参阅自托管指南。

 集成

 原生 SDK

| 语言 | 仓库 |
| -------- | ---------- |
| Python | traceroot-py |
| TypeScript | traceroot-ts |


支持的框架与模型厂商

 Agent 框架

| 集成 | 支持语言 | 描述 |
| ----------- | -------- | ----------- |
| Agno | Python | 自动埋点 Agent 运行、工具调用以及多步推理。 |
| AutoGen | Pytho