第一篇：认识 Hermes Agent

Agent与聊天机器人差异、5分钟快速体验

1. Hermes Agent 是什么

1.1 定义与定位

Hermes Agent 是一个AI 驱动的自主 Agent 框架（AI-powered Autonomous Agent）。与传统的 ChatGPT 或 Claude 等对话助手不同，Hermes Agent 不仅能够理解自然语言指令，还能自主规划、调用工具、迭代执行，直到任务完成。

传统 AI 对话系统的核心是"单轮问答"：用户提问，模型回答，结束。而 Hermes Agent 的核心是工具调用循环（Tool Calling Loop）：

理解意图 → 拆解任务 → 调用工具 → 观察结果 → 判断是否完成 → 继续或交付

这个循环在 run_agent.py 的 run_conversation() 方法（第 7506 行）中实现，是整个系统的引擎。Agent 会反复调用 LLM，执行工具，将结果反馈给模型，直到模型判断任务已完成或达到迭代上限。

1.2 与 ChatGPT / Claude / Copilot 的本质区别

特性	ChatGPT / Claude	GitHub Copilot	Hermes Agent
交互模式	单轮问答	代码补全建议	自主工具调用循环
工具调用	需要用户确认执行	无工具调用	自动调用 30+ 内置工具
执行环境	沙箱 / 无	编辑器内	本地 / Docker / Modal 云沙箱
任务拆解	用户手动引导	无	Agent 自主拆解、子 Agent 委派
记忆能力	会话内	项目上下文	持久记忆、跨会话 MEMORY.md
多平台接入	Web/App	IDE 插件	19+ 即时通讯平台

关键差异在于：Hermes Agent 是一个执行者，而不是单纯的建议者。当你说"帮我部署这个项目"，它不会给你部署步骤，而是直接执行部署命令，观察输出，处理错误，最终告诉你结果。

从源码层面看，这种差异体现在 run_agent.py 的 run_conversation() 方法（第 7506 行）中。该方法不是一次性的 "发送请求-获取响应"，而是一个 while 循环：每次 LLM 返回 tool_calls 时，Agent 执行工具、将结果追加到消息历史、再次调用 LLM，直到 LLM 不再请求工具调用（即返回纯文本响应）为止。这个循环的迭代次数由 IterationBudget（第 170 行）控制，默认上限为 90 次。

1.3 核心能力链

Hermes Agent 的核心能力可以用以下链条描述：

理解意图（Intent Understanding）：通过 LLM 解析用户的自然语言指令，识别任务目标
拆解任务（Task Decomposition）：将复杂任务拆分为可执行的子步骤
调用工具（Tool Invocation）：通过 model_tools.py 中的 handle_function_call() 调度到具体的工具处理器
迭代执行（Iterative Execution）：在 IterationBudget（第 170 行）控制的预算内反复执行，直到任务完成
交付结果（Result Delivery）：将最终结果返回给用户，支持多平台交付

这个能力链并非单向线性流程。在实际执行中，Agent 可能会回溯（发现某条路径不通，尝试其他方案）、委派（将子任务交给子 Agent 并行处理）、提问澄清（通过 clarify 工具向用户确认模糊的意图）。这种灵活性使得 Hermes Agent 能够处理开放的、复杂度未知的真实世界任务。

1.4 技术栈概览

从技术实现角度看，Hermes Agent 基于以下核心技术栈：

语言：Python 3.10+
LLM 接口：OpenAI Python SDK（兼容 chat_completions / codex_responses / anthropic_messages 三种 API 模式）
异步框架：asyncio + threading 混合模型（Gateway 层异步、Agent 层同步+线程池）
包管理：pyproject.toml + pip/uv
数据存储：SQLite（会话历史）、JSONL（轨迹日志）、YAML（配置文件）
部署：Docker / systemd / Nix / Modal

核心依赖项定义在 pyproject.toml 和 requirements.txt 中，主要包含 openai（LLM SDK）、httpx（HTTP 客户端）、playwright（浏览器自动化）、yaml（配置解析）等。

2. 核心特性一览

2.1 多平台接入（19+）

Hermes Agent 通过 Gateway 层支持丰富的即时通讯平台。每个平台由独立的 adapter 实现，位于 gateway/platforms/ 目录下：

平台	适配器文件	说明
Telegram	`telegram.py`	最早支持的平台之一
Discord	`discord.py`	支持频道和私信
WhatsApp	`whatsapp.py`	通过 WhatsApp Web 桥接
Slack	`slack.py`	支持 Socket Mode
Signal	`signal.py`	端到端加密消息
WeChat (企业微信)	`wecom.py`	企业微信应用消息
Feishu (飞书)	`feishu.py`	飞书机器人
DingTalk (钉钉)	`dingtalk.py`	钉钉机器人
Matrix	`matrix.py`	去中心化通讯协议
Mattermost	`mattermost.py`	开源团队协作
Email	`email.py`	邮件收发
SMS	`sms.py`	短信网关
Weixin (微信)	`weixin.py`	微信公众号
API Server	`api_server.py`	HTTP REST API
Webhook	`webhook.py`	通用 Webhook 接入

平台定义在 gateway/config.py（第 48 行）的 Platform 枚举中，每个平台有独立的配置数据类 PlatformConfig。

2.2 工具调用（30+）

Hermes Agent 内置了丰富的工具集，通过 tools/registry.py 中的 ToolRegistry 单例统一管理。主要工具包括：

终端工具（terminal_tool.py）：在本地/Docker/Modal/SSH/Singularity/Daytona 6 种后端执行命令
文件工具（file_tools.py）：读写文件、搜索内容、补丁修改
Web 工具（web_tools.py）：搜索和提取网页内容
浏览器工具（browser_tool.py）：无头浏览器自动化
视觉工具（vision_tools.py）：图像分析和理解
子 Agent 委派（delegate_tool.py）：生成子 Agent 并行处理子任务
技能系统（skills_tool.py）：可扩展的技能框架
记忆工具（memory_tool.py）：持久化对话记忆
代码执行（code_execution_tool.py）：沙箱内的程序化工具调用
TTS 语音（tts_tool.py）：文本转语音输出
定时任务（cronjob_tools.py）：计划任务管理

所有工具在模块导入时通过 registry.register() 自动注册，无需手动维护注册表。

2.3 子 Agent 委派

Hermes Agent 支持层级化的任务委派。父 Agent 可以通过 delegate_task 工具生成子 Agent，每个子 Agent 拥有独立的上下文、终端会话和受限的工具集。这在 tools/delegate_tool.py 中实现：

子 Agent 不能递归委派（DELEGATE_BLOCKED_TOOLS，第 30 行）
支持并行执行多个子任务（_DEFAULT_MAX_CONCURRENT_CHILDREN = 3）
最大委派深度为 2 层（MAX_DEPTH = 2）
每个子 Agent 有独立的 IterationBudget（默认 50 次迭代）

2.4 技能系统

技能（Skills）是可扩展的任务模板，存放在 skills/ 目录下。用户可以通过 skills_tool.py 和 skill_manager_tool.py 管理、浏览和执行技能。技能系统支持：

内置技能和用户自定义技能
技能市场（Skills Hub）浏览和安装
技能模板变量和上下文注入

2.5 上下文压缩

长对话会消耗大量 token。Hermes Agent 通过 agent/context_compressor.py 实现智能上下文压缩：

当对话接近模型的 context window 上限时自动触发
保留关键信息的同时压缩历史消息
配置在 config.yaml 的 compression 节

2.6 记忆系统

Hermes Agent 的记忆系统支持两个维度：

MEMORY.md：Agent 自主维护的长期记忆，存储重要上下文和用户偏好
USER.md：用户画像信息，帮助 Agent 了解用户背景
外部记忆提供者：支持 Honcho 等第三方记忆服务（通过 plugins/memory/ 插件）

记忆系统在 AIAgent.__init__ 中初始化（第 1089-1112 行），配置在 config.yaml 的 memory 节。

2.7 安全审批

对于潜在危险的操作，Hermes Agent 实现了多层安全机制：

破坏性命令检测（_is_destructive_command，run_agent.py 第 256 行）：正则匹配 rm、mv、sed -i、git reset 等命令
Tirith 安全扫描（tools/tirith_security.py）：命令注入和路径遍历检测
审批回调（tools/approval.py）：通过 CLI 或 Gateway 交互式确认
环境隔离：支持 Docker/Modal 沙箱隔离执行

安全机制的设计遵循**纵深防御（Defense in Depth）**原则：第一层是 Agent 层的启发式检测（正则匹配），第二层是工具层的 Tirith 安全扫描（AST 级别分析），第三层是用户交互式确认（CLI 或 Gateway 弹出审批提示）。即使其中一层被绕过，其他层仍然提供保护。

2.8 Provider 灵活路由

Hermes Agent 的 Provider 路由机制在 AIAgent.__init__ 中实现（第 645-682 行），支持：

OpenAI 兼容端点：任何实现了 /v1/chat/completions 的 API（包括 vLLM、Ollama、LM Studio 等本地模型）
Anthropic 原生 API：直接使用 Messages API，获得更好的 Prompt Caching 支持
Codex Responses API：OpenAI 的新一代 API，适用于 GPT-5.x 等模型
OpenRouter 聚合：一个 API Key 访问 200+ 模型，支持 provider 过滤和排序
Fallback 链：当主 Provider 不可用时自动切换到备用 Provider

2.9 会话持久化

Hermes Agent 通过 SessionStore（gateway/session.py 第 495 行）实现会话持久化：

SQLite 数据库：存储会话元数据和消息历史，支持 session_search 工具检索
JSONL 文件：降级方案，当 SQLite 不可用时使用
会话重置策略：支持按消息、按对话、永不重置三种模式
跨平台会话：每个平台/用户组合有独立的会话上下文

3. 5 分钟快速体验

3.1 安装

Hermes Agent 使用 Python 包管理，支持 pip 和 uv 两种方式：

# 克隆仓库
git clone https://github.com/nousresearch/hermes-agent.git
cd hermes-agent

# 方式一：pip 安装（含所有可选依赖）
pip install -e ".[all]"

# 方式二：uv 安装（更快）
uv pip install -e ".[all]"

安装完成后，hermes 命令即可用。入口点定义在 hermes_cli/main.py 中。

3.2 配置

Hermes Agent 提供两种配置方式：

方式一：交互式配置向导

hermes setup

这将引导你完成：

选择 LLM 提供者（OpenRouter / Anthropic / OpenAI / 本地模型等）
输入 API Key
选择默认模型
配置工具集

方式二：手动编辑配置文件

配置文件位于 ~/.hermes/ 目录下：

config.yaml：主配置文件（模型、工具集、终端、记忆等）
.env：敏感信息（API Key、密码等）

一个最小化的 config.yaml 示例：

model:
  provider: openrouter
  default: anthropic/claude-sonnet-4-20250514

terminal:
  backend: local
  timeout: 120

对应的 .env 文件：

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxx

3.3 运行

Hermes Agent 支持两种运行模式：

CLI 交互模式

# 直接启动交互式对话
hermes

# 指定模型运行
hermes --model anthropic/claude-opus-4-20250514

# 使用指定 Profile
hermes -p work

CLI 入口在 hermes_cli/main.py 中处理，支持 chat、gateway、setup、doctor 等子命令。

Gateway 服务模式

# 前台运行
hermes gateway

# 作为系统服务运行
hermes gateway install   # 安装服务
hermes gateway start     # 启动服务
hermes gateway status    # 查看状态
hermes gateway stop      # 停止服务

Gateway 的核心类是 GatewayRunner（gateway/run.py 第 510 行），它管理所有平台 adapter 的生命周期，将消息路由到 AIAgent。

3.4 Profile 系统

Hermes Agent 支持 Profile（配置隔离），每个 Profile 有独立的配置和会话：

# 创建并切换到工作 Profile
hermes -p work

# 使用个人 Profile
hermes -p personal

Profile 的实现在 hermes_cli/main.py 的 _apply_profile_override() 函数（第 83 行）中，它在所有模块导入之前解析 --profile 参数，设置 HERMES_HOME 环境变量。

4. 适用场景

4.1 软件开发

Hermes Agent 天然适合软件开发场景：

代码编写：通过终端工具和文件工具直接编辑代码
调试排错：执行测试、查看日志、分析堆栈
代码审查：读取代码、搜索模式、提供改进建议
Git 操作：提交、分支、合并、解决冲突
重构：跨文件搜索替换、函数提取、依赖更新

示例对话：

用户：帮我重构 utils.py，把所有日期处理函数提取到 date_utils.py
Agent：我来执行这个重构任务...
  1. 读取 utils.py，识别日期相关函数
  2. 创建 date_utils.py，迁移函数定义
  3. 更新 utils.py 中的 import
  4. 搜索所有引用点并更新导入路径
  5. 运行测试确认无回归

4.2 DevOps

服务部署：Docker 构建、容器管理、CI/CD 配置
监控告警：日志分析、指标查询、异常排查
基础设施管理：服务器配置、网络诊断、权限管理
定时任务：通过 cronjob_tools.py 设置计划任务

4.3 数据分析

数据清洗：读取 CSV/JSON、格式转换、异常值处理
统计分析：使用 Python 执行统计计算
可视化：生成图表（matplotlib/plotly）
报告生成：将分析结果整理为文档

4.4 内容创作

文档编写：Markdown 文件创建和编辑
翻译：多语言内容翻译
内容审核：检查格式、语法、逻辑
SEO 优化：关键词分析、元数据生成

4.5 团队协作

通过 19+ 平台的 Gateway 接入，团队成员可以在各自习惯的即时通讯工具中与 Agent 交互：

Slack/Discord 频道集成：团队共享 Agent 实例
飞书/钉钉企业集成：企业内部工作流自动化
Telegram/WhatsApp 个人助手：个人效率工具
邮件集成：自动化邮件处理和回复

思考题

Hermes Agent 的工具调用循环与普通的 LLM API 调用有什么本质区别？为什么说这是一个从"建议者"到"执行者"的范式转变？
如果你要用 Hermes Agent 搭建一个团队的 Slack 机器人，需要配置哪些文件？Gateway 层如何保证消息不会丢失？
IterationBudget（run_agent.py 第 170 行）为什么需要线程安全设计？在什么场景下多个线程会同时访问同一个 budget 实例？提示：考虑 delegate_task 的并行执行机制。
Profile 系统（_apply_profile_override）为什么必须在所有模块导入之前执行？如果延迟到模块导入之后会发生什么问题？
对比 Hermes Agent 的 6 种终端后端（local/Docker/Modal/SSH/Singularity/Daytona），在什么场景下你会选择哪种后端？安全性和性能如何权衡？