用 NVIDIA NeMo Relay 追踪 Hermes Agent 行为：从任务验证到 harness 变更评估

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

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

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

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

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

视频 1. 使用 NeMo Relay 评估 Hermes Agent 追踪记录的分步代码演示

先决条件

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

• macOS 或 Linux Git和curlDocker Desktop 或 Docker Engine已安装并正在运行- 一个用于

NVIDIA Nemotron 3.5 Lightning 的 NVIDIA Build API 密钥。打开模型页面并选择Generate API Key。

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

NeMo Relay 如何与 Hermes Agent harness 协同工作

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

理解追踪输出

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

Agent Trajectory Observability Format（

ATIF）OpenTelemetry与OpenInferenceLLM，以及工具 span，并定义它们的属性。表 1. 追踪输出以三种不同格式表示，以适应各种智能体工作流

ATIF 工具请求显示模型要求运行什么，但并不确认结果。要验证实际发生了什么，请检查 ATOF 中匹配的工具启动和结束事件以及任何记录的错误。它们共享的 uuid

将事件配对，而 parent_uuid

将工具调用连接到其父级。

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

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

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

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

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

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

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

按顺序运行以下命令。复制 keys.env

后，在继续之前将你的 NVIDIA API 密钥添加到该文件中。

# 克隆教程仓库。
git clone https://github.com/NVIDIA/nemoclaw-community
# 进入克隆的仓库。
cd nemoclaw-community/examples/tools/hermes-relay-tracing
# 创建隔离的 Hermes Agent 和 NeMo Relay 运行时。
./scripts/setup_tutorial_runtime.sh
# 复制 API 密钥模板。
cp keys.env.example keys.env
# 在继续之前，将 NVIDIA_API_KEY 添加到 keys.env 中。
# 验证 Docker 正在运行。
docker version
# 为终端工具任务构建 Docker 镜像。
./scripts/build_tutorial_image.sh
# 运行任务并生成 ATOF 和 ATIF 追踪。
./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 安装。

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

查看跟踪摘要

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

ATOF 摘要

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

ATIF 摘要

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：运行多工具研究任务并探索其轨迹

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

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

你可以通过更改端点和身份验证设置，将相同的 OpenTelemetry 轨迹发送到其他兼容 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 中打开该项目，即可跟踪 agent 从初始文件读取到网络搜索、来源验证、报告撰写和最终响应的整个运行过程。

图 1。Phoenix 左侧显示完整的 Hermes Agent 运行过程，右侧显示所选的模型调用，包括会议查询、请求的 read_file 调用、耗时和 token 使用量

用另一个模型尝试该任务

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

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

使用轨迹评估 agent harness 变更

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

agent harness 评估步骤

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

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

结果没有变化也很有用。它可以表明表面上的改进依赖于特定的模型、环境或样本。

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

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

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

表 2. 2026年8月6日 A/B 运行的结果，比较了两个模型上的固定基线和修复版本

在这次运行中，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 秒增加到 42 秒。修复为基线放弃的任务带来了成功，代价是一个更慢、更啰嗦的智能体。

任务级别的审计显示了这些权衡的来源。

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

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

开始评估智能体追踪

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

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

了解更多：

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