了解如何使用执行轨迹来理解智能体行为，并判断测试框架的变更是否改善了任务结果。

智能体可以完成任务，但仍可能走低效路径。一次失败的搜索可能触发另一次搜索。一次被截断的文件读取可能导致命令再次获取相同内容。正确的最终答案会掩盖这些额外步骤，尽管它们会增加延迟并消耗 token。低效会带来更多失败的机会。

要改善智能体的行为，开发者必须了解任务是否成功以及智能体是如何完成任务的。仅靠成功检查无法解释智能体为何从工具错误中恢复、为何提前停止，或为何需要额外的模型调用。

在本教程中，你将使用 NVIDIA NeMo Relay 运行两个 Hermes Agent（智能体） 示例。你将使用生成的轨迹来检查模型和工具调用、错误、重试、持续时间以及 token 使用情况，然后将这些证据与每个任务的验证结果进行比较。一个 Hermes ToolPerf 案例研究展示了如何使用相同的方法在重复运行中评估测试框架的变更。

本教程和视频将解释如何：

• 使用其原生 NeMo Relay 集成设置隔离的 Hermes Agent 运行时。
• 运行一个简单的终端工具任务，并检查其事件流和轨迹。
• 运行一个文件和网络研究任务，并在 Arize Phoenix 中探索其 OpenTelemetry 轨迹。
• 将任务验证与轨迹证据相结合，以评估对智能体测试框架的变更。

先决条件

在开始之前，请确保你具备：

• macOS 或 Linux
• Git 和 curl
• 已安装并运行 Docker（容器化平台） Desktop 或 Docker Engine
• 用于 NVIDIA Nemotron 3.5 Lightning 的 NVIDIA Build API（应用程序编程接口） 密钥。打开模型页面并选择 Generate API Key。

接下来概述本教程所使用的技术以及它们如何协同工作。

NeMo Relay 如何与 Hermes Agent 测试框架协同工作

NeMo Relay 为智能体开发者提供了一种通用方式来观察和控制模型与工具的执行。流行的智能体测试框架 Hermes Agent 原生包含 NeMo Relay，并在 NeMo Relay 的作用域层级中表示其会话、轮次、模型调用和工具调用。NeMo Relay 在工作开始和结束时记录生命周期事件，保留其时序和父子关系。

理解 trace 输出

NeMo Relay 用于智能体可观测性。你将使用智能体执行的三种表示形式：

| 格式 | 包含内容 | 使用场景 |
| --- | --- | --- |
| Agent Trajectory Observability Format ( ATOF ) | 一个 JSONL 日志，记录 scope 开始、scope 结束和时间点标记，包含 ID 和时间戳，用于重建智能体运行过程。 | 使用 ATOF 调试或审计单个事件、时序和父子关系。 |
| Agent Trajectory Interchange Format ( ATIF ) | 一个逐步的 JSON 记录，包含智能体交互、工具调用和观察结果，由生命周期事件组装而成。 | 使用 ATIF 逐步审查、分析或评估智能体的执行路径。 |
| OpenTelemetry with OpenInference | OpenTelemetry 将运行过程记录为父子 span。OpenInference 标记智能体、LLM（大语言模型） 和工具 span 并定义其属性。 | 在符合 OTEL 的工具（如 Phoenix）中使用，以检查模型和工具调用、持续时间、token 使用情况和错误。 |

ATIF 工具请求显示模型要求运行的内容，但不确认结果。要验证实际发生的情况，请检查 ATOF 中匹配的工具开始和结束事件以及任何记录的错误。它们共享的 uuid 将事件配对，而 parent_uuid 将工具调用连接到其父级。

在分享 trace 之前请先审查。根据你的配置，它们可能包含提示词、模型响应、工具参数和结果、文件路径以及其他应用程序数据。

对于智能体安全与安保治理，NeMo Relay 有助于提供证据层：结构化的 trace 和轨迹，企业、评估者和安全系统可以使用它们来调查智能体行为、评估策略、改进控制措施，或创建扩展 Relay 的专用安全插件。

让我们从第一个智能体任务运行开始。

实验 #1：使用 Hermes Agent 运行一个简单的工具使用任务

第一个示例有意设计得很小，以便你在添加网络搜索和 Phoenix 之前验证完整设置。Hermes 使用其终端工具在隔离的 Docker 容器中运行包含的 Python 脚本。该脚本打印：VALUE=42。

这个固定输出为运行器提供了精确的成功检查。通过的运行还确认 Hermes 已连接到模型、在沙箱中调用了终端工具，并生成了两个 Relay trace 文件。

该容器无法访问网络、仓库检出或 NVIDIA API 密钥。Hermes 也无法回退到在主机上运行终端命令。

按顺序运行以下命令。复制 keys.env 后，在继续之前将你的 NVIDIA API 密钥添加到该文件中。

# Clone the tutorial repository.
git clone https://github.com/NVIDIA/nemoclaw-community

# Enter the cloned repository.
cd nemoclaw-community/examples/tools/hermes-relay-tracing

# Create the isolated Hermes Agent and NeMo Relay runtime.
./scripts/setup_tutorial_runtime.sh

# Copy the API key template.
cp keys.env.example keys.env

# Add NVIDIA_API_KEY to keys.env before continuing.

# Verify that Docker is running.
docker version

# Build the Docker image for the terminal-tool task.
./scripts/build_tutorial_image.sh

# Run the task and generate the ATOF and ATIF traces.
./scripts/run_tutorial.sh

Hermes Agent 和 NeMo Relay 进程从该仓库的本地环境运行。Docker 单独用于终端工具沙箱和本地 Phoenix 服务。

仓库中的安装脚本会在 .tutorial-runtime/ 下创建一个自包含环境，包含所有适当的依赖项，如 Python 3.11 和 Hermes 0.21.1 以及 NeMo Relay 0.8.3。它不会修改你现有的 Python 或 Hermes 安装。

当任务完成后，运行器会检查响应和两个 trace 文件。通过的运行会打印验证结果，随后是 ATOF 和 ATIF 摘要。

查看 trace 摘要

在 Hermes 完成任务后，运行器会验证预期结果和生成的 trace。它会检查终端命令是否成功、ATOF trace 是否包含已完成的 LLM 活动（含 token 使用量且无工具错误），以及是否创建了非空的 ATIF 轨迹。以下输出来自一次已验证的运行。Token 计数、标识符和文件路径可能因运行而异。

events: 74
completed llm scopes: 2
llm scopes with usage: 2
prompt tokens: 7239
completion tokens: 96
total tokens: 7335
tool calls: 1
tool errors: 0
correlated events: 74

agent: Hermes Agent
model: nvidia/nemotron-3.5-lightning-30b-a3b
steps: 3
llm calls: 2
requested tool calls: 1

Task verified: VALUE=42
Artifacts: .../artifacts/runs/<run-id>

查找包含 Task verified: VALUE=42 的行，它确认了预期结果。ATOF 摘要报告已完成的模型作用域、token 使用量、工具调用和工具错误。ATIF 摘要将同一执行过程呈现为三步轨迹。

Artifacts: 后面的路径标识了包含完整 ATOF 事件流和 ATIF 轨迹的运行目录。配套仓库说明了如何再次检查或汇总任一文件。

实验 #2：运行多工具研究任务并探索其 trace

在验证基本设置后，第二个示例使用相同的 Hermes 和 NeMo Relay 环境来执行一个需要多个工具的任务。Hermes 收到一条旅行记录，其中包含关于一个未命名机器学习会议的线索。它必须读取该记录，找到与主题、日期和地点匹配的会议，在官方网站上确认答案，将验证后的信息保存到报告中，并返回会议名称。

使用 NeMo Relay 的 OpenInference 导出器通过 OTLP（OpenTelemetry Protocol）将 OpenTelemetry span 发送到 Arize Phoenix。Phoenix 将该运行显示为交互式 trace，你可以在其中检查模型和工具调用、时序、token 使用量、错误以及可用的输入和输出。

你可以通过更改端点和身份验证设置，将相同的 OpenTelemetry trace 发送到其他兼容 OTLP 的后端，例如 LangSmith。NeMo Relay 可观测性指南描述了其他可用的导出器和配置选项。

该示例复用第一个示例中的 NVIDIA Nemotron 模型和 NVIDIA API 密钥。Hermes 使用其内置的无密钥网页搜索，运行器在固定版本的本地容器中启动 Phoenix。运行会议搜索示例：

./scripts/run_conference_research_with_phoenix.sh

在运行过程中，NeMo Relay 会在本地保存 ATOF 事件流和 ATIF 轨迹。

在报告成功之前，运行器会检查 Hermes 是否：

• 将 COLT 2026 识别为会议名称
• 保存了包含预期会议详情和官方来源的报告
• 成功完成了 read_file、web_search、web_extract 和 write_file 调用
• 生成了非空的 ATIF 轨迹
• 向 Phoenix 发送了带有正 token 使用量的模型和工具 span

检查通过后，终端输出会包含 Phoenix 项目链接和本地运行目录。在 Phoenix 中打开该项目，即可跟踪智能体从初始文件读取到网络搜索、来源验证、报告撰写和最终响应的整个运行过程。

使用另一个模型尝试该任务

要查看另一个模型如何处理相同的会议查询，请按照配套仓库中的模型配置说明操作。保持查询、可用工具、执行限制和验证器不变，以便检查执行路径的差异。

由于该任务使用实时网络搜索，请将这些运行用于探索行为，而非对模型进行排名。受控比较需要固定的搜索响应和重复运行。

使用轨迹评估智能体框架变更

这两个示例展示了如何验证结果和检查单次运行。评估框架变更需要在受控的、重复的条件下进行相同的检查。

智能体框架评估步骤

• 选择一个固定的任务，并配有精确的自动化成功检查。
• 定义一个基线和一个针对提示词、工具、配置或框架的聚焦变更。
• 除该变更外，保持其他一切不变，包括模型快照、提供商、任务输入、执行预算和超时。
• 在启用 NeMo Relay 的情况下，对基线和候选方案运行相同次数的重复。
• 首先比较经过验证的任务结果。然后使用轨迹检查模型调用、工具调用、重试、错误、耗时、token 使用量和成本。
• 在推广结果之前，在预期该变更支持的模型或工作负载上重复评估。

只有当候选方案能够可重复地提高任务完成率，或在保持完成率的同时改善你打算变更的可靠性、延迟或成本指标时，才能称其为改进。一次更快的运行或更少的调用可以帮助解释结果，但两者本身都不能确立优化。

结果不变同样有价值。它可以表明，表面上的改进依赖于特定的模型、环境或样本。

评估 Hermes 工具层变更的基准案例研究

Hermes ToolPerf 基准由 Nous Research 开发，其过程包括分析生产会话、审计工具 schema，以及从生产会话日志中挖掘失败类别。随后，使用 NeMo Relay ATOF traces 进行真实轮次核算。通过检查九种失败模式，结果被转化为确定性基准案例，然后用于评估一批 Hermes 工具层修复。

8 月 6 日的重跑比较了 Hermes 的固定基线和修复修订版在九个任务上的表现。每个任务在每个模型每个分支上运行三次，总计 108 次运行，全程使用相同的提示、工具、执行限制和成功检查。任务验证器测量完成情况，NeMo Relay ATOF traces 捕获模型调用、工具调用、错误、重试、工具结果数据和时序。

| 模型 | 分支 | 任务成功 | 平均 LLM 调用次数 | 平均工具调用次数 | 平均工具结果数据 | 平均时长 |
| --- | --- | --- | --- | --- | --- | --- |
| Claude Sonnet 4.5 | 基线 | 24/27 (89%) | 2.9 | 2.2 | 17 KB | 16 s |
| Claude Sonnet 4.5 | 修复 | 23/27 (85%) | 2.8 | 2.1 | 17 KB | 22 s |
| Qwen3 Coder 30B | 基线 | 19/27 (70%) | 3.8 | 2.8 | 16 KB | 27 s |
| Qwen3 Coder 30B | 修复 | 22/27 (81%) | 4.9 | 3.9 | 33 KB | 42 s |

在这次运行中，Sonnet 没有表现出实际变化。它在基线上完成了 27 次运行中的 24 次，在修复上完成了 27 次中的 23 次，相差一次运行。其轮次、工具调用和结果数据在两个分支上相同。

Qwen Coder 是修复产生效果的地方，而且这种影响是双向的。它成功完成了多三个任务，从 27 次中的 19 次增加到 27 次中的 22 次。它也为这些任务付出了更多努力：平均 LLM 调用次数从 3.8 上升到 4.9，工具调用从 2.8 上升到 3.9，工具结果数据从 16 KB 增加到 33 KB，时长从 27 s 增加到 42 s。修复为基线放弃的任务带来了成功，代价是智能体变得更慢、更啰嗦。

任务级审计显示了这些权衡来自哪里。

• 在 blocked-command 任务上，基线 Qwen 在解析器阻塞处失败，得分为 33%，而恢复配方将修复分支提升到 100%。这种完成正是轮次计数上升的原因：恢复会消耗轮次，而放弃从不消耗。
• 大小写不敏感搜索任务则相反。零匹配探测输出在三次重复中的两次将 Qwen 推入额外的探索性搜索，使其从 3.3 轮增加到 9.3 轮，这是一个值得单独研究的回归。
• 隐藏文件搜索在两个分支和两个模型上都保持在 0 到 33%，与原始运行发现的差距相同，并且在这些 SHA 上仍然存在。

仅凭任务的成功或失败无法得出这一结论。NeMo Relay traces 记录了所有 108 次运行的每次模型调用、工具调用、错误、重试、结果负载和时序。Qwen 的额外轮次是恢复而非胡乱尝试，而那个任务的回归可追溯到特定的探测输出。这些 traces 已检入结果目录，因此任何人都可以解包它们，并从原始记录重新生成这些表格。

开始评估智能体 traces

NeMo Relay 为你提供了一种一致的方式来捕获证据，以评估优化智能体 harness 的变更。ATOF 保留有序的生命周期事件，而 ATIF 将相同的工作呈现为可读的轨迹。将这些 traces 与确定性验证器配对，使你能够比较 harness 变更，而不会将更少的调用误认为更好的结果。

配套仓库提供了示例工件，包括本文中使用的可运行任务、验证器、NeMo Relay 配置和 Phoenix 设置。

• NeMo Relay 文档，用于安装、概念和配置。
• Hermes Agent 文档，用于安装和使用 Hermes。
• 配套教程仓库，包含本文中的可运行示例。
• ATOF 和 ATIF 文档，用于事件和轨迹格式。
• NeMo Relay 可观测性配置，用于配置导出器和遥测目标。
• 支持的集成，用于将 NeMo Relay 与其他智能体框架和应用程序配合使用。

转载声明：本文为转载整理，原文版权归原作者及原站点所有。

原文来源：NVIDIA Technical Blog

原创地址：https://developer.nvidia.com/blog/tracing-agent-harness-behavior-with-nvidia-nemo-relay/