Hermes Agent

前提条件

• Python环境版本 >= 3.9
• Hermes Agent版本 >= 0.21.3
  如果未安装Hermes Agent，请先使用Hermes Agent官方安装脚本完成安装。

  curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

• 独立探针仅支持本地凭证模式（环境变量配置APM/AOM凭证），不支持通过云上元数据服务自动获取凭证。

探针初始化需要在应用启动时完成，建议在Hermes会话开始之前初始化。

• 在AgentArts观测界面查看数据不收费。
• 但数据上报会产生费用：
  • 调用链上报到APM（应用性能管理服务），费用明细请参考APM计费说明。
  • 指标上报到AOM（应用运维管理服务），费用明细请参考AOM计费说明。

• AOM和APM都是按需计费，并有一定量的免费额度，超出后按实际使用量收费。

工作原理

Hermes Agent是智能体框架，提供多工具调用、技能（Skill）、会话搜索、记忆、子智能体委派（delegate_task）等能力，支持在终端中直接运行。

Hermes探针是华为云AgentArts基于OpenTelemetry标准为Hermes Agent自研的可观测采集探针。探针以Hermes官方插件形式安装，通过Hermes的生命周期hooks机制在会话启动时自动加载，无需修改业务代码。

数据流转过程：

Hermes Agent运行时
  ├── Hermes会话启动
  │     └── 加载已启用插件
  │           └── 生命周期hooks注册观测埋点
  │                 ├── Agent回合（invoke_agent）
  │                 ├── 推理步骤（react step）
  │                 ├── 模型调用（chat）
  │                 ├── 工具调用（execute_tool）
  │                 └── 子智能体委派（delegate_task）
  │
  ├── Trace数据 ──OTLP gRPC──→ APM（调用链）
  └── Metrics数据 ──OTLP gRPC──→ AOM（指标）
                                          │
                                          ▼
                                AgentArts观测平台展示

接入后，以下能力将被自动监控：

• Agent执行链路（invoke_agent）：Agent回合的完整生命周期。主agent固定命名hermes，子agent按派发任务命名。
• 推理步骤（react step）：每轮"模型推理 + 工具调用"的详细过程。
• LLM调用（chat）：模型名称、Token用量（全量）、缓存Token、输入/输出内容、上下文窗口、首Token时延（TTFT）。
• 工具调用（execute_tool）：工具名称、输入参数、返回结果、执行耗时。
• 子智能体委派（delegate_task）：子Agent的完整链路嵌套在父链路之下。
• 业务指标：Token消耗、模型调用次数、模型调用耗时、工具调用耗时等。

接入步骤

查看监控数据

数据上报成功后，可在AgentArts智能体平台的观测功能中查看监控数据。

1. 登录AgentArts 智能体平台。
2. 在左侧导航栏选择“观测与优化 > 观测”。
3. 在“智能体列表”页面，找到已接入的智能体，单击智能体名称进入详情页面。

查看业务指标

在“指标分析”页签中，可以查看关键业务指标：

• Tokens消耗：Input Tokens和Output Tokens的消耗总量
• 模型调用次数：应用调用大模型的累计次数
• 模型调用平均耗时：模型调用的平均响应时间
• 模型调用成功率：大模型调用成功的比例
• 会话数：应用产生的会话总数
• 工具调用次数与耗时：工具调用总量、平均耗时（含 Skill 调用的独立指标）
• 响应成功率：服务响应的成功率

查看调用链信息

在“调用链分析”页签中，可以查看完整的Trace调用链路：

• 查看各Span类型的层级关系及各节点耗时
• 单击具体Span查看详细信息：
  • Agent节点（invoke_agent）：可查看Agent名称、输入/输出消息
  • LLM节点（chat）：可查看模型名称、输入/输出消息（Input/Output Messages）、Token消耗（Total tokens）
  • Tool节点：可查看工具名称、输入参数、返回结果
  • 中间件节点：可查看中间件执行耗时

查看会话分析

在“会话分析”页签中，可以查看智能体与用户对话的历史数据：

• 追踪对话上下文
• 分析模型响应耗时
• 统计Token消耗
• 快速定位对话异常问题

更多参考

会话与用户维度

插件自动为span关联会话；子agent回合沿用父会话ID，保证一次问答的调用链会话一致。如需按用户维度统计，可在$HERMES_HOME/.env中添加AGENTARTS_AGENTOPS_USER_ID环境变量（默认兜底主机名）。

AGENTARTS_AGENTOPS_USER_ID=<user-id> 

修改后需重启Hermes Agent生效。如果不设置，默认取当前主机名作为user.id。多用户共享主机时，需要显式设置环境变量以区分不同用户。

子智能体（delegate_task）

Hermes的delegate_task会在父链路下嵌套一个完整的子Agent回合：

execute_tool delegate_task     PLUGIN — 父回合中的委派调用   └── invoke_agent {child}     AGENT — 子 Agent 独立回合        └── react step ... 

后台委派（background）场景下，子Agent可能成为独立Trace。

控制内容采集

默认情况下，探针会采集LLM输入/输出内容，包括根节点（Agent回合）、LLM节点与工具节点的对话/调用内容。如需关闭（隐私/合规场景），在$HERMES_HOME/.env中添加：

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false

修改后需重启Hermes Agent生效。

关闭后：

• LLM 节点：gen_ai.input.messages、gen_ai.output.messages、input.value、output.value 不采集。
• 根节点（Agent 回合）：input.value、output.value 不采集。
• 工具节点：gen_ai.tool.call.arguments、gen_ai.tool.call.result、input.value、output.value 不采集。
• 模型名、Token 用量、耗时、调用链结构、工具名称等非内容属性不受影响。

常见问题

无数据上报

1. 检查环境变量是否正确配置，特别是Token和Endpoint。
2. 确认启动日志出现[hermes-plugin] provider ready / registered 13 hooks。如果未出现，说明插件未正确加载。
3. 检查网络连接，确保能访问APM/AOM端点。
4. 检查凭证是否有效。
5. 确认hermes-agent版本 >= 0.21.3（hermes --version）。

hermes升级后插件失效

1. hermes升级可能更换运行环境，重新运行安装脚本即可。
2. 若升级过程清理了依赖，脚本会自动补装。

指标无数据

1. 确认AOM凭证（Access Code / Prometheus ID）与端点正确。
2. 确认$HERMES_HOME/.env中agentarts_agentops_otel_agent_aom_enable未设为false。
3. AOM平台侧异常时（如服务端报错），联系AOM侧确认。

部分Span缺失

1. 确认Hermes Agent版本兼容性（>= 0.21.3）。
2. 确认工具确实被调用（终端有preparing xxx输出）。
3. 确认未使用-z oneshot模式启动（该模式不加载插件，hooks不触发）。

Token统计不准确

1. 确保使用最新版本的探针。
2. 某些模型可能不返回准确的Token数。