# Hermes Agent
本文介绍如何将Hermes Agent接入华为云AgentArts观测服务，实现调用链追踪和业务指标监控。接入后无需修改业务代码，Python探针加载后，采集Agent执行链路、LLM调用、工具调用等数据并上报。
**快速入门：**
前提：本地已安装Hermes Agent（版本\>= 0.21.3）
1. 在AgentArts平台创建Hermes智能体，获取接入参数。
2. 安装Python探针，执行安装脚本传入接入参数，脚本自动完成插件安装、凭证写入和启用。
3. 启动hermes，在AgentArts观测页面查看调用链和指标数据。
详细步骤见下方[接入步骤]。
#### 前提条件
- 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会话开始之前初始化。
![](https://support.huaweicloud.com/ops-agentarts/public_sys-resources/note_3.0-zh-cn.png)
- 在AgentArts观测界面查看数据不收费。
- 但数据上报会产生费用：
  - 调用链上报到APM（应用性能管理服务），费用明细请参考[APM计费说明](https://support.huaweicloud.com/price-apm2/apm_07_0019.html)。
  
  - 指标上报到AOM（应用运维管理服务），费用明细请参考[AOM计费说明](https://support.huaweicloud.com/price-aom2/aom_07_0004.html)。
   

- 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消耗、模型调用次数、模型调用耗时、工具调用耗时等。
 
 #### 接入步骤
 #### 步骤一：获取接入参数
1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。
2. 在左侧导航栏选择"观测与优化 \> 观测"。
3. 在"智能体列表"页面，单击"接入智能体"，按照页面指引填写名称、智能体类型，创建一个"Hermes"智能体，并获取各配置参数。 
   图1获取配置参数   
   ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002776990548.png "点击放大")
   
   
 
#### 步骤二：安装探针
安装过程需要两个文件：插件wheel包和安装脚本。请根据您的操作系统选择对应的安装脚本，将两者下载到**同一目录**后执行。脚本会自动完成：识别当前目录下的插件安装包 → 定位hermes运行环境 → 写入凭证 → 安装依赖 → 安装插件 → 启用插件，并自动适配hermes各版本架构（0.21.4+ store python / 0.21.3- venv）。
1. 下载[Hermes探针包](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.10.30/huaweicloud-instrumentation-hermes-plugin-1.0.1.zip)，解压后包含插件wheel包和安装脚本。
   
   - 插件wheel包（所有平台通用）
   
   - 安装脚本（按操作系统选择其一）
     - Windows：install_otel_probe_plugin.ps1
     
     - Linux / macOS / WSL2：install_otel_probe_plugin.sh
      
   
   
   
   
2. 执行安装脚本。 
   将[步骤一：获取接入参数]章节获取的接入参数作为脚本参数传入。脚本会自动将凭证写入$HERMES_HOME/.env文件，一条命令完成安装 + 凭证写入 + 启用插件。
   **Windows（PowerShell）**
   ```
   .\install_otel_probe_plugin.ps1 `
     -AgentId <智能体ID> -DomainId <租户ID> -ProjectId <项目ID> -ResourceType <agent|multiagents|workflow> `
     -Endpoint <APM上报地址> -Token <APM Token> `
     -AomEndpoint <AOM上报地址> -AomAccessCode <AOM access-code> -AomPrometheusId <Prometheus ID>
   ```
   **Linux / macOS / WSL2（bash）**
   ```
   chmod +x ./install_otel_probe_plugin.sh
   ./install_otel_probe_plugin.sh \
     --agent-id <智能体ID> --domain-id <租户ID> --project-id <项目ID> --resource-type <agent|multiagents|workflow> \
     --endpoint <APM上报地址> --token <APM Token> \
     --aom-endpoint <AOM上报地址> --aom-access-code <AOM access-code> --aom-prometheus-id <Prometheus ID>
   ```
   表1参数说明 
   | 参数                                    | 是否必填             | 说明                                                   |
   |:---|:---|:---|
   | AgentId（--agent-id）                  | 是               | 智能体ID，即步骤一获取的agent_resource_id。                       |
   | DomainId（--domain-id）                | 是                 | 账号Domain ID。                                          |
   | ProjectId（--project-id）              | 是             | 华为云项目ID。                                             |
   | ResourceType（--resource-type）         | 是                | 智能体类型：agent（单智能体，默认）、multiagents（多智能体）、workflow（工作流）。 |
   | Endpoint（--endpoint）               | 条件必填（上报调用链时必填） | APM OTLP数据上报地址。                                       |
   | Token（--token）                     | 条件必填（上报调用链时必填）  | APM接入凭证Token。                                        |
   | AomEndpoint（--aom-endpoint）         | 条件必填（上报指标时必填）    | AOM OTLP数据上报地址。                                      |
   | AomAccessCode（--aom-access-code）     | 条件必填（上报指标时必填）   | AOM接入凭证Access Code。                                  |
   | AomPrometheusId（--aom-prometheus-id） | 条件必填（上报指标时必填）   | AOM Prometheus实例ID。                                   |
      
   ![](https://support.huaweicloud.com/ops-agentarts/public_sys-resources/note_3.0-zh-cn.png)
   - 脚本自动识别同目录下唯一的插件安装包（.whl）；若目录下有多个安装包，需在命令中显式指定。
   
   - hermes升级后重新运行对应平台的脚本即可。
    
   
   
 
#### 步骤三：启动Hermes Agent并验证
1. 启动Hermes Agent，并进行对话问答。 
   ```
   hermes
   ```
   如果Hermes Agent已经在运行，请先停止后重新启动。
   
   
2. 确认插件已正常加载。 
   启动后查看终端输出或日志，确认插件是否已正确加载。启动时应出现以下类似的日志：
   ```
   [hermes-plugin] provider ready
   [hermes-plugin] registered 13 hooks
   ```
   出现以上日志说明插件已成功加载，探针开始工作。
   
   
3. 触发Hermes Agent会话，产生观测数据。
4. 在AgentArts平台查看观测数据。
 
#### 配置参数说明
插件安装后，以下参数可在运行时通过环境变量调整。环境变量统一存放在**$HERMES_HOME/.env**文件（每行键、值），修改后需重启Hermes Agent生效。
表2.env文件路径 
| 平台             | .env路径                                                                            |
|:---|:---|
| Windows      | %LOCALAPPDATA%\\hermes\\.env（例如C:\\Users\\\<用户名\>\\AppData\\Local\\hermes\\.env） |
| Linux / macOS | \~/.hermes/.env                                                                |
   
- 安装脚本已自动写入：安装命令中的凭证参数（-Token/-Endpoint/-AgentId等）由脚本写入该文件。
- 手动新增/修改配置：直接编辑.env追加或修改对应键、值行，保存后重启hermes生效。
- 也可在shell中临时设置环境变量：Windows用$env:KEY=value，Linux用export KEY=value。
表3参数说明 
| 环境变量                                      | 说明                               | 是否必填     | 默认值    |
|:---|:---|:---|:---|
| agentarts_agentops_otel_agent_apm_enable  | 是否启用APM调用链上报                      | 否         | true   |
| agentarts_agentops_otel_agent_aom_enable  | 是否启用AOM指标上报                     | 否        | true |
| agentarts_agentops_apm_token              | APM接入凭证                         | APM启用时必填  | -      |
| agentarts_agentops_apm_exporter_endpoint | APM数据上报地址                         | APM启用时必填   | -     |
| agentarts_agentops_aom_access_code      | AOM接入凭证                          | AOM启用时必填 | -      |
| agentarts_agentops_aom_exporter_endpoint | AOM数据上报地址                        | AOM启用时必填 | -      |
| agentarts_agentops_aom_prometheus_id     | Prometheus实例ID                  | AOM启用时必填  | -     |
| agentarts_project_id                     | 华为云项目ID                         | 是          | -       |
| agent_domain_id                            | 账号Domain ID                       | 是          | -      |
| agent_resource_id                         | 智能体ID                            | 是          | -        |
| resource_type                             | 智能体类型：agent、multiagents、workflow | 是         | agent  |
   
表4可选环境变量 
| 环境变量                                                | 说明                | 默认值   |
|:---|:---|:---|
| OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT | 是否采集 LLM 输入/输出内容 | true |
| OTEL_METRIC_EXPORT_INTERVAL                        | Metrics 上报间隔（毫秒）   | 60000 |
   
#### 查看监控数据
数据上报成功后，可在AgentArts智能体平台的观测功能中查看监控数据。
1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/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数。