如何用 TraceRoot 快速上手:10 分钟为 AI Agent 接入第一条 Trace 并跑通第一个 Detector

原创2026-10-24 22:57:212,332 阅读

如何用 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 创建项目 API Key 的快速入门页面

二、一键安装 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 用量与成本一目了然。

TraceRoot 第一条 Trace 追踪查看器:Span 树、Token 用量与成本明细

四、创建第一个 Detector:自动捕获 Agent 的故障

有了 Trace,下一步是让 TraceRoot 替你"读"这些 Trace。

Detector 的工作原理:每条 Trace 到达约一分钟后,由一个评审模型(judge)判断该 Trace 是否存在你指定的问题。判定为"是"就是一条 finding(发现),同类发现会被聚合成 Signal,TraceRoot Agent 还可以进一步做根因分析。

手动创建只需 6 步(详见 docs/detectors/introduction.mdx):

  1. 左侧导航进入 Detectors,点击 New Detector
  2. Template:选择 Failure、Hallucination、Logic Error、Task Completion、Safety 或 Blank,模板会自动填好名称和 Prompt
  3. Model:选择评审每条 Trace 的模型
  4. Prompt:用自然语言描述要找的问题
  5. Filter / Sampling:过滤要检查的 Trace,设置采样比例(100% 全检,0% 暂停)
  6. 点击 Create Detector,此后到达的 Trace 即开始被检测

TraceRoot Detector 列表:模板、评审模型、采样率与 Signal 统计

不会写 Prompt?让 AI 帮你建。进入左侧导航的 Home(TraceRoot Agent),直接说"创建一个标记工具调用失败的 Detector",Agent 会基于你的项目草拟检测器,确认后再点击 Create detector 保存:

TraceRoot Agent 辅助创建 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 不参与检测,避免污染线上统计

接下来推荐按此路线深入:

  1. docs/signals/introduction.mdx — 理解 Signal 的分组、审核与解决
  2. docs/ai-agent/overview.mdx — 用 TraceRoot Agent 做根因分析与自动修复
  3. docs/evals/get-started.mdx — 用数据集验证改动效果
  4. docs/cli/get-started.mdx — 在终端中列出、检查与导出 Trace

恭喜!你已经跑通了 Trace → Detect → Signal 的核心闭环,剩下的就是把这套流程应用到你的真实 Agent 中,持续发现并修复问题 🚀

登录后查看全文
traceroot