**开篇先说结论：**很多人理解 AI Agent，容易只盯着大模型本身：GPT、Claude、Gemini、开源模型谁更强？但看 Hermes Agent 的官方文档和 GitHub 会发现，真正让 Agent 能长期工作的，不只是模型，而是模型外面那套工程系统：上下文、工具、记忆、技能、会话、自动化、安全和部署。
Hermes Agent 更像一个"长期在线的 AI 工作系统"，而不是一个只会聊天的网页机器人。它可以运行在本地、服务器、云沙箱，也可以通过 CLI、Telegram、Discord、Slack、API、Cron 等入口接收任务；同时，它还会把经验沉淀为 Memory 和 Skills，让后续任务越来越顺手。
一、先用一句话说清楚：Hermes Agent 到底是什么
Hermes Agent 官方介绍把它称为一个 self-improving AI agent，也就是"会随着使用持续改进的智能体"。它的关键点不是单次对话有多聪明，而是长期运行以后，能够沉淀用户偏好、项目经验、可复用技能，并把这些东西带入后续任务。
按照官方文档和 GitHub README 的描述，Hermes Agent 的能力关键词主要有：内置学习闭环、跨会话记忆、技能创建与改进、多平台消息入口、定时自动化、子 Agent 并行、工具调用、终端后端、轨迹导出和训练数据生成。
所以更准确地说，Hermes Agent 不是"一个模型"，而是"一个围绕模型构建的 Agent 运行系统"。模型负责理解与决策，Hermes 负责把任务变成可执行流程：读上下文、选模型、调用工具、保存结果、压缩会话、管理技能、控制风险。
|---------|-----------------|-------------------------------------------------|
| 对比项 | 普通聊天机器人 | Hermes Agent |
| 运行方式 | 一次性问答，主要依赖当前上下文 | 可长期运行，支持 CLI、消息平台、API、Cron 等入口 |
| 执行能力 | 通常只生成文本建议 | 可以调用终端、文件、浏览器、MCP、子 Agent 等工具 |
| 记忆方式 | 多数依赖当前会话或简单偏好 | Memory、Session Search、Skills、Context Files 分层沉淀 |
| 项目理解 | 需要用户反复解释背景 | 可读取 AGENTS.md、.hermes.md、SOUL.md 等上下文文件 |
| 生产化能力 | 通常缺少安全边界和运行控制 | 有审批、沙箱、凭证过滤、压缩、fallback、会话持久化等机制 |
二、整体架构：从入口层到长期沉淀层
如果把 Hermes Agent 拆开看，可以分成五层：入口层、核心循环层、能力扩展层、长期沉淀层、安全运行层。这个分层很适合用来理解所有现代 Agent 系统。
|--------|----------------------------------------------|---------------------------------|-------------------------------|
| 层级 | 代表模块 | 核心职责 | 你可以怎么理解 |
| 入口层 | CLI、Gateway、API Server、ACP、Batch Runner、Cron | 接收不同来源的任务，把消息路由到同一个 Agent 运行时 | 像前台窗口：你可以从命令行、聊天软件、编辑器、定时任务进入 |
| 核心循环层 | AIAgent / run_agent.py | 负责模型调用、工具调用、重试、fallback、压缩、持久化 | 像大脑和调度中心：决定下一步做什么 |
| 能力扩展层 | Tools、MCP、Plugins、Subagents | 把"想法"变成真实动作：读写文件、跑命令、搜网页、调用外部系统 | 像手脚和外接设备 |
| 长期沉淀层 | Memory、Sessions、Skills、Context Files | 保存事实、历史和可复用流程，让 Agent 越用越顺 | 像笔记本、档案馆和操作手册 |
| 安全运行层 | 授权、审批、沙箱、扫描、回滚、隔离 | 降低 Agent 执行真实动作时的风险 | 像刹车、护栏和审计系统 |
从官方 Architecture 页面看，AIAgent 是同步编排引擎，负责 provider selection、prompt construction、tool execution、retries、fallback、callbacks、compression 和 persistence。也就是说，Hermes 的核心不是"发一次请求给模型"，而是把一次任务组织成可观察、可恢复、可限制的执行过程。
三、入口层：为什么 Hermes 不只是本地命令行工具
很多 Agent 工具都绑定在本地 IDE 或网页聊天窗口里，但 Hermes 的定位更偏"长期在线的工作伙伴"。官方文档列出它支持 CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、DingTalk、Feishu、WeCom、Home Assistant、Microsoft Teams、Google Chat 等入口。
这种设计有一个很大的架构意义：入口不再决定 Agent 的能力。你在 Telegram 上发一句"帮我检查昨晚的定时任务是否失败"，背后仍然可以走同一套 AIAgent、工具系统、Session、Memory 和 Cron。
对企业项目来说，这种架构很重要。因为真实业务不会只有一个入口：研发可能从 IDE 发起，运营可能从 Slack 发起，老板可能从手机聊天软件发起，定时巡检可能由 Cron 发起。如果每个入口都各写一套 Agent 逻辑，系统很快会失控。Hermes 的 Gateway 思路，是把入口统一到一个长期运行的 Agent 进程。
四、核心层：Agent Loop 如何驱动一次任务
理解 Hermes Agent，最关键的是理解 Agent Loop。所谓 Agent Loop，不是神秘概念，就是一个循环：模型先判断下一步，系统再执行工具，把结果交还给模型，模型再继续判断，直到任务完成或预算耗尽。
一次请求流转图：Agent Loop 负责把自然语言任务拆成可执行动作
官方 Agent Loop 文档把 AIAgent 的职责列得很清楚：组装系统提示词和工具 schema，选择 provider/API mode，执行可中断模型调用，执行工具调用，维护对话历史，处理压缩、重试和 fallback，并跟踪父子 Agent 的迭代预算。
用更通俗的话说，Hermes Agent 每一轮都在做 6 件事：
第一，读入用户任务和当前会话历史；
第二，加载 Memory、Skills、Context Files、工具说明等上下文；
第三，选择合适的模型供应商和 API 模式；
第四，让模型决定是直接回答，还是调用工具；
第五，执行工具，并把结果放回上下文；
第六，如果任务还没结束，就继续循环；如果结束，就保存会话和必要记忆。
|---------------------|------------------------|--------------------------|
| 机制 | 作用 | 为什么重要 |
| Iteration Budget | 限制任务最大循环次数 | 防止 Agent 无限执行、无限花费 token |
| Fallback Model | 主模型失败后切换备用 provider | 提升稳定性，避免因为限流或服务异常中断任务 |
| Context Compression | 上下文过长时压缩中间过程 | 让长任务持续推进，同时控制上下文窗口 |
| Callbacks | 工具执行、推理状态、流式输出可被观察 | 让用户知道 Agent 正在干什么，不是黑盒 |
| Session Persistence | 每轮后保存消息、工具调用、token 统计等 | 方便恢复、审计、分析和跨会话检索 |
五、Prompt 与上下文：Agent 如何理解项目和用户
普通用户觉得 Prompt 就是一句话，但在 Agent 架构里，Prompt 更像"执行任务前的作战手册"。Hermes 的 Prompt Builder 会把多个来源的信息组装进系统提示词，例如 SOUL.md、MEMORY.md、USER.md、Skills、AGENTS.md、.hermes.md、工具使用指导、模型特定指令等。
这里最值得学习的是"分层上下文"的思想。不同信息不应该都塞进一个超长 Prompt，而应该按用途拆开：
|------------------------|---------------------|----------------------------|
| 上下文来源 | 保存什么 | 适合场景 |
| SOUL.md | Agent 的人格、语气、默认工作风格 | 希望 Agent 长期保持固定表达和工作方式 |
| AGENTS.md | 项目结构、代码规范、测试方式、团队约定 | 让 Agent 进入项目后知道怎么写代码、怎么跑测试 |
| .hermes.md / HERMES.md | 项目专属高优先级指令 | 对当前项目有更强约束时使用 |
| MEMORY.md | 环境事实、项目经验、工具坑点 | 长期有用，不需要每次重新解释的信息 |
| USER.md | 用户偏好、沟通风格、期望 | 让 Agent 更懂用户的默认需求 |
| Skills | 可复用流程、操作步骤、验证方法 | 复杂任务完成后沉淀为"下次照着做"的手册 |
官方 Context Files 文档还有一个很实用的设计：子目录 AGENTS.md 不是一开始全加载，而是当 Agent 读到对应目录内容时再渐进发现。这样既能减少系统提示词膨胀，又能保持 Prompt Cache 稳定。这个思路非常适合大型代码仓库。
六、Tools Runtime：从"想做"到"真执行"
Agent 最大的变化，是从"回答问题"变成"执行动作"。但执行动作必须有统一的工具运行时，否则每个工具都变成临时代码，难以维护、难以审计、难以扩展。
Tools Runtime 与 MCP 扩展架构：工具通过注册表统一暴露和派发
官方 Tools Runtime 文档说明，Hermes 工具是自注册函数，按 toolsets 分组，通过中央 registry/dispatch 系统执行。也就是说，每个工具模块在导入时调用 registry.register，把工具名称、所属 toolset、schema、handler、可用性检查等信息登记进去。
这套机制带来的好处是：模型看到的是规范化 tool schema；运行时执行的是受控 handler；用户看到的是可观察工具进度；开发者扩展工具时，不必改一堆手动列表。
|------------------------|--------------------------------------------------|--------------------------|
| 工具类别 | 代表能力 | 典型用途 |
| Web | web_search、web_extract | 联网查资料、抓页面内容 |
| Terminal & Files | terminal、process、read_file、patch | 跑测试、改文件、启动进程、读取日志 |
| Browser | browser_navigate、browser_snapshot、browser_vision | 网页自动化、浏览器操作、视觉理解 |
| Memory & Recall | memory、session_search | 写入长期记忆、检索历史会话 |
| Agent Orchestration | todo、clarify、execute_code、delegate_task | 规划任务、澄清需求、执行代码、委派子 Agent |
| Automation & Delivery | cronjob、send_message | 定时任务、消息推送 |
| Integrations | MCP tools、Home Assistant、RL tools | 连接外部系统和高级集成 |
终端后端也是 Hermes 的亮点之一。它支持 local、Docker、SSH、Singularity、Modal、Daytona、Vercel Sandbox 等后端。这意味着 Agent 可以在本机跑，也可以在隔离容器、远程服务器、云沙箱中跑。对于能改代码、能执行命令的 Agent 来说，后端隔离不是可选项，而是基础设施。
七、MCP：把外部系统接成 Agent 工具
MCP 可以理解成 Agent 的"外部工具插座"。如果你想让 Hermes 使用 GitHub、数据库、文件系统、浏览器栈、内部 API，不一定要把这些能力写成 Hermes 原生工具，而是可以通过 MCP Server 暴露出来。
官方 MCP 文档说明，Hermes 支持本地 stdio server，也支持远程 HTTP MCP server；启动时可以自动发现并注册 MCP 工具，还能按 server 过滤，只暴露希望 Agent 使用的能力。
|----------------------|-------------------------|---------------------------------|
| 接入方式 | 适合场景 | 架构意义 |
| stdio MCP Server | 本地工具、文件系统、开发机能力、低延迟调用 | Hermes 启动子进程，通过 stdin/stdout 交互 |
| HTTP MCP Server | 企业内部 API、远程工具服务、集中式能力平台 | Hermes 通过 HTTP 连接外部服务，不需要本地启动工具 |
| Per-server Filtering | 只开放部分工具给 Agent | 控制权限边界，避免 Agent 拿到过大的工具面 |
对企业来说，MCP 的价值很大。你不需要把"查订单、查工单、查客户、查知识库、发审批、查库存"全部硬编码进 Agent 主工程，而是把它们包装成 MCP Server。Hermes 只负责发现工具、展示 schema、派发调用和接收结果。
八、Memory、Session、Skills：长期智能体的三套记忆系统
Hermes Agent 的"自我改进"不应该被误解成每次都重新训练模型。更实际的理解是：它通过 Memory、Session Search、Skills 和外部 memory providers，在运行时持续积累可复用信息。
Memory 适合保存长期事实，例如用户偏好、机器环境、项目约定、工具坑点。官方文档显示，Hermes 有 MEMORY.md 和 USER.md 两类文件，存放在 ~/.hermes/memories/，并在 session 启动时注入系统提示词。Memory 有字符限制，目的就是防止无节制膨胀。
Session 适合保存完整过程。每次对话无论来自 CLI 还是消息平台，都会保存为 session。官方 Sessions 文档说明，Hermes 使用 SQLite state.db 保存结构化元数据和 FTS5 搜索，同时用 JSONL transcripts 保存原始会话记录和工具调用。
Skills 适合保存可复用流程。官方 Skills 文档说，Skills 是按需加载的知识文档，遵循 progressive disclosure 模式。它不是每次都把完整内容塞进 Prompt，而是先列出技能，再在需要时加载具体技能，必要时再加载引用文件。
|---------|-----------------------|--------------------|----------------|
| 模块 | 主要保存 | 是否每次进入 Prompt | 最佳用途 |
| Memory | 事实、偏好、环境、约定 | Session 启动时进入系统提示词 | 长期稳定、经常用到的信息 |
| Session | 历史消息、工具调用、结果、token 统计 | 不是全部重复发送；按需恢复或检索 | 复盘、恢复、跨会话回忆 |
| Skills | 流程、步骤、坑点、验证方法 | 按需加载 | 把复杂任务沉淀成可复用方法论 |
这三者的边界非常重要：Memory 不是垃圾桶，不要把所有日志都塞进去；Session 不是 Prompt，不应该无限重发；Skills 也不是知识库全文，而是"做某类任务的操作说明书"。
九、安全架构：能执行动作的 Agent 必须有边界
如果一个 Agent 只能聊天，风险相对可控；但如果它能跑命令、改文件、调用数据库、访问企业系统，就必须先建立安全边界。Hermes 官方 Security 文档把安全模型拆成多层：用户授权、危险命令审批、容器隔离、MCP 凭证过滤、Context 文件扫描、跨 Session 隔离和输入净化。
危险命令审批是最直观的一层。Hermes 在执行命令前，会检查是否命中危险模式；如果命中，默认需要用户手动确认。它也提供 smart 模式，让辅助模型判断风险，但真正危险或不确定的情况仍会升级。
容器隔离则是工程上更重要的一层。终端后端可以用 Docker、Singularity、Modal、Daytona、Vercel Sandbox 等方式把执行环境隔开。这样即使 Agent 需要运行测试、安装依赖、写临时文件，也不会轻易污染宿主环境。
MCP 凭证过滤也很关键。Agent 连接外部工具时，最容易出问题的是凭证范围过大。Hermes 通过环境变量过滤、server 级工具过滤等方式，让外部工具只暴露必要能力。
十、源码阅读路线：从哪些文件入手最清晰
如果你想真正掌握 Hermes Agent，不建议一上来全仓库乱翻。最好的路线是先看主循环，再看 Prompt，再看 Provider，再看 Tools，最后看 Session、Compression、Gateway、Cron 和 ACP。
|----------|-----------------------------|-------------------------------------|
| 阅读顺序 | 文件或模块 | 你要看懂的问题 |
| 1 | run_agent.py | AIAgent 如何完成一次完整任务循环？ |
| 2 | agent/prompt_builder.py | 系统 Prompt 由哪些上下文拼出来？ |
| 3 | runtime_provider.py | 模型供应商、API 模式和凭证如何解析？ |
| 4 | model_tools.py | 工具 schema 如何收集，tool call 如何派发？ |
| 5 | tools/registry.py | 工具如何自注册、发现、过滤和执行？ |
| 6 | hermes_state.py | Session、消息、token、FTS5 搜索如何保存？ |
| 7 | agent/context_compressor.py | 长会话如何压缩，哪些消息必须保留？ |
| 8 | gateway / cron / acp | 多平台入口、定时任务、编辑器集成如何进入同一套 Agent Loop？ |
看源码时可以带着一个核心问题：每个模块到底是在解决 Agent 工程里的哪类问题？例如，run_agent.py 解决"任务如何循环推进"；prompt_builder.py 解决"模型看到什么上下文"；model_tools.py 解决"模型如何调用工具"；hermes_state.py 解决"执行过程如何保存和恢复"。
十一、总结：Hermes Agent 架构给 AI 应用工程的启发
Hermes Agent 最值得学习的地方，不是某个炫酷命令，而是它把 AI Agent 做成了一个完整工程系统。这个系统有入口、有上下文、有模型路由、有工具、有记忆、有技能、有会话、有自动化、有安全、有部署后端。
如果把它抽象成一句话，就是：
AI Agent = 模型能力 + Harness 工程能力
模型决定"能不能理解任务"，Harness 决定"能不能可靠执行任务"。Hermes Agent 的整体架构，正好展示了一个长期运行 Agent 需要具备哪些工程能力：
要有统一入口，让不同平台的任务进入同一个运行时；
要有 Agent Loop，把模型推理、工具执行、结果回填组织起来；
要有 Prompt Builder，把项目规则、用户偏好、记忆、技能合理装配；
要有 Tools Runtime 和 MCP，让 Agent 真正连接外部世界；
要有 Memory、Sessions、Skills，让经验沉淀下来；
要有安全边界，防止能执行命令的 Agent 失控；
要有压缩、fallback、预算控制、持久化，让长任务可持续、可恢复、可观察。
所以，学习 Hermes Agent 的正确姿势，不是只问"怎么安装"，而是问：它如何把模型变成一个长期运行、可扩展、可沉淀、可控制的智能体系统？只要抓住这条主线，再看官方文档和 GitHub 源码，就不会迷路。