如何用 TraceRoot 快速上手:10 分钟为 AI Agent 接入第一条 Trace 并跑通第一个 Detector
如何用 TraceRoot 快速上手:10 分钟为 AI Agent 接入第一条 Trace 并跑通第一个 Detector
TraceRoot 是一款开源的 AI Agent 改进平台,帮助你追踪(Tracing)每一次模型调用与工具执行,并用 Detector(检测器)自动发现 Agent 的故障、幻觉等问题。这篇入门教程带你在 10 分钟内为 AI Agent 接入第一条 Trace,并跑通第一个 Detector,全程只需几行代码。
一、准备工作:快速上手的 3 个前置条件
在开始之前,确认以下三样东西就绪:
| 条件 | 说明 |
|---|---|
| 运行环境 | Python 3 或 Node.js(任选其一,本教程以 Python 为例) |
| API Key | 一个 TraceRoot 项目 API Key |
| 模型 Key | 一个 OpenAI API Key(用于示例中调用模型,可选) |
如何获得 API Key:注册 TraceRoot Cloud 后,在项目设置中即可创建项目级 API Key;API Key 按项目隔离,只授权访问对应项目的数据(详见 docs/getting-started/concepts.mdx)。
💡 更偏好完全掌控数据?TraceRoot 也支持自托管。安装 Git、Docker Compose 和 Make 后执行:
git clone https://gitcode.com/gh_mirrors/tr/traceroot cd traceroot make prod-lite随后打开
localhost:3000即可,详细配置见 docs/developer/self-hosting.mdx。
二、一键安装 TraceRoot SDK 并配置 API Key
安装 SDK(按语言二选一):
pip install traceroot # Python
npm install @traceroot-ai/traceroot # TypeScript
配置环境变量。两个 SDK 都只读取进程环境变量、不会自动加载 .env 文件,建议在 shell 中直接导出:
export TRACEROOT_API_KEY="your-api-key"
export TRACEROOT_HOST_URL="https://app.traceroot.ai" # 自托管则改为自己的实例地址
开启追踪:在应用入口加一行 initialize,即可自动捕获所有 OpenAI API 调用:
import traceroot
from traceroot import Integration
traceroot.initialize(integrations=[Integration.OPENAI])
更完整的接入细节见官方文档 docs/tracing/get-started.mdx。
三、两步代码,接入第一条 Trace
仅靠 initialize 就能记录模型调用;若想记录 Agent 会话和工具调用,再用 @observe 装饰器包一层即可。仓库里的 examples/python/openai-tool-agent/main.py 是一个完整的 ReAct Agent 示例:
from traceroot import Integration, observe
traceroot.initialize(integrations=[Integration.OPENAI])
@observe(name="demo_session", type="agent")
def run_demo():
...
运行 python main.py 后,打开项目的 Traces 页面,就能看到完整的 Span 树:每个模型调用、工具调用、输入输出、延迟、Token 用量与成本一目了然。
四、创建第一个 Detector:自动捕获 Agent 的故障
有了 Trace,下一步是让 TraceRoot 替你"读"这些 Trace。
Detector 的工作原理:每条 Trace 到达约一分钟后,由一个评审模型(judge)判断该 Trace 是否存在你指定的问题。判定为"是"就是一条 finding(发现),同类发现会被聚合成 Signal,TraceRoot Agent 还可以进一步做根因分析。
手动创建只需 6 步(详见 docs/detectors/introduction.mdx):
- 左侧导航进入 Detectors,点击 New Detector
- Template:选择 Failure、Hallucination、Logic Error、Task Completion、Safety 或 Blank,模板会自动填好名称和 Prompt
- Model:选择评审每条 Trace 的模型
- Prompt:用自然语言描述要找的问题
- Filter / Sampling:过滤要检查的 Trace,设置采样比例(100% 全检,0% 暂停)
- 点击 Create Detector,此后到达的 Trace 即开始被检测
不会写 Prompt?让 AI 帮你建。进入左侧导航的 Home(TraceRoot Agent),直接说"创建一个标记工具调用失败的 Detector",Agent 会基于你的项目草拟检测器,确认后再点击 Create detector 保存:
五、查看检测结果:Finding、Signal 与通知
- 打开某个 Detector 可以看到每次运行(run),Identified 为 Yes 的即是发现
- 每条运行都链接到对应 Trace,点击 Signal ID 可查看聚合后的问题与根因分析
- 在 Settings → Detectors → Notifications 中配置邮件或 Slack,Signal 会按告警窗口(默认 10 分钟)打包成摘要(digest)推送给你
⚠️ 小提示:没有配置邮件收件人也没有 Slack 频道时不会发送任何通知;自托管部署若需要根因分析与通知,服务端需配置
OPENAI_API_KEY。
六、常见坑与进阶路线
.env不会自动加载:SDK 只读进程环境变量,如需.env请在代码中显式加载(如dotenv)- 采样是确定性的:同一 Trace 重复上报不会改变"是否被检测"的结果
- 评估(Evals)会跳过 Detector:来自离线评估的 Trace 不参与检测,避免污染线上统计
接下来推荐按此路线深入:
- docs/signals/introduction.mdx — 理解 Signal 的分组、审核与解决
- docs/ai-agent/overview.mdx — 用 TraceRoot Agent 做根因分析与自动修复
- docs/evals/get-started.mdx — 用数据集验证改动效果
- docs/cli/get-started.mdx — 在终端中列出、检查与导出 Trace
恭喜!你已经跑通了 Trace → Detect → Signal 的核心闭环,剩下的就是把这套流程应用到你的真实 Agent 中,持续发现并修复问题 🚀



