TraceRoot
让 AI Agent 从线上故障定位到验证修复的可观测性平台。
这个 Agent 能做什么，适合哪些场景？
TraceRoot 是面向 AI Agent 的开源可观测性与持续改进平台，覆盖追踪、线上检测、根因分析和离线评测。它通过兼容 OpenTelemetry 的 SDK 捕获 LLM 调用、Agent 动作与工具使用，并用 Detectors 筛选需要关注的线上 trace。被确认的问题可转成 golden dataset，再通过 TraceRoot CLI 或 SDK 运行离线 eval 验证修复。其 Agentic Debugging 层连接含生产源码的 sandbox，并关联 GitHub 的提交、PR 和 issue，以定位失败代码行并可创建修复 PR。团队可使用 TraceRoot Cloud，也可通过 Docker 本地运行；AWS 的 Kubernetes、Helm 与 Terraform 部署仍标为实验性。
应用侧可调用 Python 的 traceroot.initialize(integrations=[Integration.OPENAI])，以 @observe(name="my_agent", type="agent") 包装函数；或在 TypeScript 中调用 TraceRoot.initialize({ instrumentModules: { openAI: OpenAI } })，以 observe({ name: "my_agent", type: "agent" }, ...) 包装异步 Agent，并在结束时执行 TraceRoot.shutdown()。SDK 记录 LLM 调用、Agent 动作和工具使用的 trace。Detectors 使用 LLM-as-judge 评估进入的 trace，检查幻觉、工具或逻辑失败、安全违规和意图漂移，并可发出邮件和 Slack 告警、触发根因分析。调试层在包含生产源码的 sandbox 中分析问题，关联 GitHub 提交、PR 与未关闭 issue，定位失败行，并按项目说明创建已验证的修复 PR。确认的线上发现可一键成为 golden dataset；离线 eval 可从 TraceRoot CLI 或 SDK 在 Claude Code、Codex、Cursor 等编码 Agent 内运行，用于检验修复。
- 维护线上客服 Agent 的工程团队，可用 Detectors 监测生产 trace 中的幻觉或意图漂移，再将确认案例沉淀为回归评测集。
- 使用 OpenAI Chat Completions 或 Responses API 的 Python 或 TypeScript 团队，可通过对应 SDK 初始化和 observe 包装采集调用与 Agent 运行。
- 需要排查工具调用不稳定或逻辑错误的团队，可让 Agentic Debugging 在生产源码 sandbox 中关联 GitHub 历史来定位失败代码行。
- 使用 LangChain、LangGraph、CrewAI、AutoGen 或 OpenAI Agents SDK 的开发者，可接入项目列出的框架追踪集成。
- 准备在每次代码改动后验证 Agent 修复的团队，可将线上发现转为 golden dataset，并在 Codex、Claude Code 或 Cursor 中运行离线 eval。
这个 Agent 有哪些优点和局限？
- 把线上 LLM-as-judge 检测、根因分析、golden dataset 和离线 eval 串成同一改进闭环，而不止提供 trace 浏览。
- 调试流程明确利用生产源码 sandbox 和 GitHub 的提交、PR、issue 来定位失败行，并说明可创建修复 PR。
- 同时提供 Python 与 TypeScript SDK，并列出 OpenAI、Anthropic、Gemini、Mistral、OpenRouter 等提供商及多种 Agent 框架的追踪路径。
- 可选择 TraceRoot Cloud、Docker 本地运行或 AWS 的 Kubernetes/Helm/Terraform 部署，且说明支持自带模型提供商密钥。
- README 没有提供 Cloud、SDK 上报或 GitHub 访问所需令牌、环境变量、权限范围与认证配置的具体步骤。
- 根因分析需要连接包含生产源码的 sandbox，并读取 GitHub 历史；这会带来源码访问、隔离和权限审查成本。
- AWS 的 Kubernetes、Helm 与 Terraform 生产部署被明确标为实验性，生产采用前需要额外验证。
- Detector 依赖 LLM-as-judge；README 未说明评审模型、阈值、误报控制、数据保留或告警配置细节。
如何安装或部署这个 Agent？
Python：执行 pip install traceroot openai。TypeScript：执行 npm install @traceroot-ai/traceroot openai。本地开发可执行 git clone https://github.com/traceroot-ai/traceroot.git、cd traceroot、make dev；完整本地 Docker 运行可执行 make prod。README 未给出 TraceRoot Cloud 的认证变量、SDK 上报端点或模型提供商密钥的具体配置方式；示例会创建 OpenAI 客户端，因此实际模型调用需要该客户端可用的认证配置。
如何使用这个 Agent？
Python 的最小调用是导入 traceroot、Integration、observe 和 OpenAI，执行 traceroot.initialize(integrations=[Integration.OPENAI])，再用 @observe(name="my_agent", type="agent") 标注调用 client.chat.completions.create(...) 的函数。TypeScript 中先执行 TraceRoot.initialize({ instrumentModules: { openAI: OpenAI } })，用 observe({ name: "my_agent", type: "agent" }, async (...) => ...) 包装函数，并在 finally 中执行 await TraceRoot.shutdown()。若自行部署平台，可在仓库根目录使用 make dev 或 make prod；生产 AWS 路径位于 deploy/，项目说明其 Kubernetes、Helm、Terraform 方案仍属实验性。