用 Litefuse 追踪 Hermes Agent

Hermes Agent 是 Nous Research 的终端 AI 助手，采用可插拔的工具调用和网关架构。本集成以 Hermes 插件 形式安装到 ~/.hermes/plugins/litefuse/。插件在 Hermes 的 Python 解释器中以同进程方式运行，订阅十个生命周期 hook 事件，为每个用户回合生成一条 Litefuse trace（与 Pi、Claude Code 集成同一套 trace 形态，一条看板查询横跨你的所有 agent）。

该插件适用于 Hermes 的所有界面 —— CLI（hermes -z、hermes chat -q）、Gateway（飞书、Discord、Slack、Telegram、WhatsApp、IRC）和 TUI。

给 AI —— 自动安装

如果你正在和 Hermes Agent 对话，把下面这段 prompt 粘贴过去，Agent 会端到端完成整个安装：

Read https://litefuse.ai/SKILL.md and follow the instructions to install and configure Litefuse for Hermes Agent.

skill 会向你索取 Litefuse 的 API Key（如果还没有账号，会引导你注册），然后在本地完成全部配置。如果你想手工一步步配置，请继续往下看。

会捕获哪些数据

Trace 结构

一个既调用多个工具又委派子 agent 的回合，产生的 trace 形如：

Hermes Agent — Turn 7                     (AGENT, root, 真实回合时长)
├── plan (2 tools) #1                     (GENERATION, usage + 真实延迟, thinking + toolCalls)
├── tool: terminal (grep) #2              (TOOL, input=参数, output=结果)
├── tool: read_file (index.ts) #3         (TOOL)
├── plan (1 tool) #4                      (GENERATION, usage)
├── tool (1 subagent) #5                  (TOOL —— delegate_task 的批次容器)
│   └── subagent                          (AGENT —— 子容器, input=任务, output=子 agent 回答)
│       ├── plan (1 tool) #1              (每个容器内编号从 #1 重新计数)
│       ├── tool: read_file (README.md) #2
│       └── subagent response             (GENERATION —— 子 agent usage 汇入 trace 成本)
└── response                              (GENERATION —— 最后一次 LLM 调用本身, usage + 延迟)

设计说明：

• 按行为命名 generation。 模型发出工具调用时叫 plan (n tools) #N，最终回答叫 response，只有 thinking 的步骤叫 think #N。模型名只是 generation 的 model 属性 —— 换模型永远不会破坏你按名字建的过滤器和看板。
• 一个共享的步骤计数器。 generation 和 tool 从同一个容器级序列取 #N，名字里的数字就是 metadata 里的 agent_step_index —— 只有一套编号，不是两套。
• tool 与 plan 的关联用 metadata 表达，不靠树深度。 每个 tool 携带 agent_plan_step（发起它的 generation 的步骤序号）和 agent_tool_call_id。树保持扁平，关联可查询。
• 真实 wall-clock 时间戳。 generation span 在 pre_api_request 打开、用 post_api_request 捕获的时刻关闭 —— 时间线展示真实的 LLM 延迟。tool span 走 pre_tool_call → post_tool_call。
• 完整 I/O 靠回合结束时回填。 Hermes 的 hook payload 只给计数不给内容 —— 插件把 generation span 保持打开，在 post_llm_call 时从对话历史回填 input（完整消息数组）和 output（thinking / 正文 / toolCall 块）后再导出。每个 span 仍然只发送一次。
• trace 头随每个 span 携带。 第一个 observation 完成时 trace 就出现在 Litefuse（name / session / input / tags），不需要额外的 bootstrap observation。
• 子 agent 子树。 一次 delegate_task 调用产生一个 tool (n subagents) #N span，每个子 agent 一个 subagent AGENT 容器嵌在其下。tool span 与容器之间的时间差就是真实的委派开销（进程启动、结果解析）。

快速开始

~/.hermes/hermes-agent/venv/bin/pip install 'langfuse>=4,<5'
 
# Verify
~/.hermes/hermes-agent/venv/bin/python3 -c "import langfuse; print(langfuse.__version__)"
# Expect: 4.x.y

mkdir -p ~/.hermes/plugins/litefuse
curl -fsSL https://litefuse.ai/integrations/hermes-agent/plugin.yaml \
  -o ~/.hermes/plugins/litefuse/plugin.yaml
curl -fsSL https://litefuse.ai/integrations/hermes-agent/__init__.py \
  -o ~/.hermes/plugins/litefuse/__init__.py

cat >> ~/.hermes/.env <<'EOF'
 
# Litefuse observability
LITEFUSE_PUBLIC_KEY=pk-lf-xxx
LITEFUSE_SECRET_KEY=sk-lf-xxx
LITEFUSE_BASE_URL=https://litefuse.cloud
EOF

hermes plugins enable litefuse
hermes plugins list   # confirm: status = enabled

hermes gateway restart  # only if you have `hermes gateway` running

hermes -z "用 shell 工具数一下 ~/.hermes/config.yaml 有多少行，然后告诉我行数"
tail -3 ~/.hermes/state/litefuse_plugin.log
# Expected: "litefuse plugin v0.2.0 registered (10 hooks, spec v1.2)"
#         + "turn closed session=YYYYMMDD_HHMMSS_xxxxxx turn=1 steps=3 api=2 tools=1 final=True"

环境变量

凭据查找顺序：进程环境 → ~/.hermes/state/litefuse.env → ~/.hermes/litefuse.env（取第一个存在的文件；环境变量永远优先于文件）。

工作原理

插件通过 ctx.register_hook(...) 订阅十个 Hermes 插件 hook 事件：

子 agent 子树。 Hermes 的 delegate_task 子 agent 在同进程的工作线程里运行，hook 不携带父会话关联 —— 所以插件用启发式：在某个 delegate_task tool span 打开期间启动首个回合的会话，被视为该委派的子会话。子容器（subagent，AGENT 类型）通过 trace context 挂在委派 tool span 下；子步骤从 #1 重新编号；子 agent 的 generation 携带各自的 usage，Litefuse 自动汇入父 trace 总成本。容器 metadata 中以 agent_subagent_link: "heuristic" 记录这种关联方式。

该插件是 fail-open 的：任何意外错误都会写入 ~/.hermes/state/litefuse_plugin.log，回调静默返回，所以永远不会阻塞 Hermes 的主循环。一个 Langfuse 客户端在模块级状态中跨 Hermes 进程整个生命周期保留，并由线程锁保护，多个并发的 gateway 会话可以安全共享。

Trace metadata 参考

所有 metadata 都是打平的、带 agent_ 前缀的标量 —— 与其他 Litefuse agent 集成完全同一套 key，所以 metadata.agent_duration_ms > 60000 这样的过滤器在 Hermes、Pi、Claude Code 的 trace 上通用。源数据中不存在的字段完全不出现（没有 null 占位）。

Trace root（AGENT observation）：

• agent_turn_number、agent_session_id、agent_cwd、agent_model、agent_platform、agent_history_messages
• 关闭时补充：agent_api_calls、agent_tool_calls、agent_steps、agent_message_count、agent_duration_ms

Generation（plan / response / think）：

• agent_turn_number、agent_step_index、agent_provider、agent_api（api_mode）、agent_stop_reason、agent_api_duration_ms、agent_tool_call_count、agent_message_count
• 消息带 reasoning 时有 agent_thinking_chars

Tool（tool: ...）：

• agent_tool_name、agent_step_index、agent_plan_step（join 键：等于发起它的 generation 的 agent_step_index）、agent_tool_call_id、agent_duration_ms、agent_is_error
• 触发截断时有 agent_output_truncated / agent_output_orig_len

子 agent 容器（subagent）：

• agent_subagent: true、agent_subagent_link: "heuristic"、agent_model、agent_platform、agent_session_id（子会话的）

故障排查

Litefuse 中没有出现 trace。 用 tail 查看 ~/.hermes/state/litefuse_plugin.log：

tail -20 ~/.hermes/state/litefuse_plugin.log

期望：启动时出现 "litefuse plugin v0.2.0 registered (10 hooks, spec v1.2)"，然后是 "Litefuse client ready" 和每回合的 "turn closed session=... turn=N steps=N api=N tools=N final=True"。如果文件是空的，说明插件没加载：

hermes plugins list           # confirm: litefuse → enabled
hermes plugins enable litefuse  # if not enabled
hermes gateway restart        # if gateway is running

插件日志显示 Litefuse credentials not set。 插件在环境变量和回退 env 文件中都没找到 key。把它们加到 ~/.hermes/.env：

cat >> ~/.hermes/.env <<'EOF'
LITEFUSE_PUBLIC_KEY=pk-lf-...
LITEFUSE_SECRET_KEY=sk-lf-...
LITEFUSE_BASE_URL=https://litefuse.cloud
EOF

然后重新执行任何 hermes -z "..." 或重启 gateway。（LANGFUSE_* 命名作为回退同样有效。）

插件日志显示 langfuse SDK not importable。 Langfuse SDK 没装在 Hermes 的 venv 中：

~/.hermes/hermes-agent/venv/bin/pip install --upgrade 'langfuse>=4,<5'

generation 要等回合结束才出现。 这是设计使然：generation 的内容（完整 messages、thinking）只有在回合结束时才拿得到，所以 generation span 在那时才导出 —— 但带着真实记录的时间戳。tool span 在每个工具完成时实时导出，trace 头随第一个完成的 observation 出现。

看到旧的 trace 形态（api: <model> #N、user message event、metadata.hermes_agent.*）。 你在运行插件 v0.1.0。从 https://litefuse.ai/integrations/hermes-agent/ 重新拉取两个文件并重启 gateway。

TUI 或 hermes -z oneshot 不产生 trace。 只影响 v0.12 之前的旧版 Hermes —— 升级 Hermes，或改用一直会加载插件的 hermes chat -q "..."。

局限

• 执行中的步骤在结束前不可见。 每个 span 恰好发送一次、在它结束时 —— 长时间运行的工具或流式 LLM 调用在完成前不会出现在 live 视图里。委派进行中，子步骤可能先于其父容器出现（列表尾部的”孤儿”行）；回合结束后树视图完整且正确。
• 子 agent 关联是启发式的。 在繁忙的多用户 gateway 上，与委派同一瞬间启动的无关会话可能被误挂（会带 agent_subagent_link: "heuristic" 标记）。单用户场景不受影响。
• 没有 TTFT / 采样参数。 Hermes hook 不暴露首 token 时刻和 temperature/top_p，所以 completion_start_time 与完整的 model_parameters（max_tokens 之外）缺失。

资源

• Hermes Agent hooks 用户指南
• Hermes Agent 插件参考
• Langfuse Python SDK v4
• Litefuse Cloud
• 插件源码：plugin.yaml · __init__.py