企业官网建设流程全解析

NOAA追踪可视化教程：一键打开浏览器，看清Agent每次LLM调用的完整调用树

【免费下载链接】labs-OO-AgentsNVIDIA Object Oriented Agents: the Pythonic way to build AI Agents.项目地址: https://gitcode.com/gh_mirrors/la/labs-OO-Agents

NOAA（NVIDIA Object Oriented Agents，开源项目 labs-OO-Agents）是一个用 Python 面向对象方式构建 AI Agent 的框架。它的追踪可视化（tracing）能力是新手最容易上手的亮点：一条命令启动 Trace Viewer，再运行任意 Agent，浏览器里就会实时出现每一层方法调用、每一次 LLM 对话、每一个工具执行的完整调用树。本文将手把手教你在 10 分钟内掌握 NOAA 追踪可视化，让 Agent 内部过程从“黑盒”变成透明的调用图。

为什么 Agent 需要追踪可视化？

新手常遇到的困惑：Agent 为什么答错了？哪一次 LLM 调用超时了？生成的代码到底跑了什么？

传统做法是把 prompt 打印出来反复试错。NOOA 的答案是OpenTelemetry 风格的调用树追踪：它记录的不仅是发给 LLM 的消息，而是整个程序调用结构——Python 编排方法、嵌套的 Agent 方法、模型调用、生成的代码单元格、工具调用，全部按父子层级嵌套呈现。

核心收益：

• 🔍定位延迟：每个 span 自带耗时，一眼看出慢在哪一步
• 💬回放对话：每次 LLM 调用的完整输入/输出消息都可以展开查看
• 🧩追踪控制流：方法 A 调用了哪些子方法、哪些工具，层级关系一目了然

提示：NOAA 中的Events（事件）与Traces（追踪）是两个不同视图。Events 是 Agent 自己的工作历史（会进入后续模型上下文），Traces 则是程序执行的运维记录，专用于调试延迟、重试、工具调用与控制流。详细说明见 docs/concepts/tracing.md。

一键启动：三步打开浏览器里的调用树

好消息是：NOOA 的追踪对新手几乎零配置。

第 1 步：启动 Trace Viewer

uv run nooa start-dev

Viewer 默认监听http://localhost:5001，它既是接收 Agent 上报 span 的 OTLP 接收端，也是浏览追踪的 Web UI。源码位于 src/nooa/viewer/，追踪数据持久化在 SQLite 中，重启后不会丢失。

第 2 步：运行你的 Agent

在另一个终端运行任意 Agent 脚本：

uv run python examples/quickstart/06_tracing.py

Agent 启动时会自动探测 5001 端口的 Viewer，只要 Viewer 可达，追踪自动开启——不需要导入任何模块，不需要写一行追踪代码。

第 3 步：打开浏览器

访问http://localhost:5001/traces，即可看到会话列表；点进某个会话，展开/折叠 span 层级，就能看到完整调用树。

Viewer 的完整用法（导入/导出/删除、REST API、快捷键）在官方技能文档中有详细清单：skills/nooa-trace-viewer/SKILL.md。

调用树里到底有什么？

以官方示例 examples/quickstart/06_tracing.py 为例：一个MathAgent依次调用calculate()（LLM 方法）、_format()（私有辅助方法）、explain()（LLM 方法）。运行后，Viewer 中会呈现如下嵌套结构：

method.run ← 编排入口（普通 Python 方法） ├── method.calculate ← LLM 方法（...） │ └── generation ← 一次策略执行 │ └── litellm.acompletion ← 真正打到模型提供商的那一次调用 ├── method._format ← 私有方法同样被追踪 └── method.explain └── generation └── litellm.acompletion

常见 span 类型速查表：

父子嵌套严格遵循 Python 调用层级——编排工作流和 LLM 步骤在树上同等重要，这正是 NOAA 调用树区别于单纯“LLM 日志”的地方。

在 Viewer 详情页还藏了几个高价值功能：

• 时间线：可缩放的双画布时间轴，展示所有事件的时间分布
• LLM 调用视图：按调用重建完整对话（/api/traces/{session_id}/calls接口驱动）
• 过滤侧栏：按事件类型、span、Agent、LLM 执行 ID 过滤
• Playground：换个模型/温度重放某一轮 LLM 调用并对比输出
• 快捷键：j/k上下导航，/全文搜索，?查看全部快捷键

排查问题的五步调试循环

有了调用树，调试 Agent 就有了确定性的路径。NOAA 官方推荐的调试循环（见 docs/concepts/tracing.md）：

1. 检查渲染后的 prompt：看信息是否缺失或重复
2. 检查方法 span 及其子 generation：确认执行结构是否符合预期
3. 查看校验错误与模型重试：很多“答错”其实是格式校验失败后的重试
4. 打开生成的代码单元格：查看其 stdout / stderr
5. 沿嵌套方法 span 走到第一个错误边界：错误通常出现在嵌套的最浅层

这条路径通常比“扩大 prompt 再试一次”高效得多。

进阶：把追踪存成文件，离线导入

Viewer 模式适合开发调试；测试、基准评测等无人值守场景，建议显式配置文件导出器，把追踪写成可归档的 JSONL 文件：

from nooa.tracing import enable_tracing, exporters, flush_traces enable_tracing(exporters=[exporters.jsonl("traces")]) # ... 运行 Agent ... flush_traces()

之后一条命令即可导入 Viewer 查看：

uv run nooa import-traces traces/quickstart-06-journal

各导出器（jsonl / journal / otlp / langfuse / console）的完整对照表和环境变量说明，见 skills/nooa-capturing-traces/SKILL.md；追踪导出器的实现位于 src/nooa/tracing/。

命令行深挖：trace-explorer 根因分析

如果追踪文件很大、或想自动化分析，可以用官方 CLI 工具trace-explorer，它专为“渐进式下钻”设计：

uv run trace-explorer trace.jsonl # 总览：调用图、会话、通过/失败 uv run trace-explorer trace.jsonl --errors # 列出所有错误 uv run trace-explorer trace.jsonl -s 278a10 -t 0 # 查看某会话第 0 轮的完整上下文 uv run trace-explorer trace.jsonl --search "Timeout" # 全文搜索

典型工作流：总览 → 找错误 → 定位会话 → 读那一轮的上下文窗口与 LLM 输出 → 找到“模型实际看到的内容”中的问题。完整文档：skills/nooa-trace-explorer/SKILL.md。

新手常见坑位清单 ⚠️

• Viewer 没开就构造了 Agent：自动追踪每个进程只探测一次，之后不会重试。请确保先nooa start-dev再跑 Agent，或显式调用enable_tracing(...)
• Viewer 不可达时没有文件兜底：自动追踪静默关闭，不会自动落盘。需要离线追踪时请显式配置exporters.jsonl()
• 短脚本记得flush_traces()：批量导出器约 1 秒一刷，进程快速退出可能丢尾巴
• 模块级main()里的逻辑不可见：追踪边界是 Agent 方法。把关键工作流步骤放进 Agent 方法，失败才会在树上留痕
• 排除噪音方法：高频辅助方法可加@no_trace装饰器，行为不变但不再产生 span

总结

NOAA 追踪可视化的核心体验只有三句话：一条命令启动 Viewer、Agent 自动上报、浏览器里展开调用树。它把 Agent 的每一次 LLM 调用、每一段生成代码、每一次工具执行都映射成带耗时的父子 span，让你从“猜 prompt”升级为“看证据”。

建议按此顺序动手：

1. 跑通 examples/quickstart/06_tracing.py 示例
2. 对照 docs/concepts/tracing.md 认识 Events 与 Traces 的区别
3. 用trace-explorer对你的第一个真实 Agent 做一次根因分析

更多学习路径：notebook_tutorials/ 中的交互式教程、docs/tour.md 的 10 分钟框架概览。

【免费下载链接】labs-OO-AgentsNVIDIA Object Oriented Agents: the Pythonic way to build AI Agents.项目地址: https://gitcode.com/gh_mirrors/la/labs-OO-Agents