1. 前言：从一个真实的生产级 AI Agent 中学习架构

1.1. 为什么要写这本书？

2024 年至 2025 年，AI Agent 从学术概念迅速走入工程现实。AutoGPT、CrewAI、LangGraph 等一系列框架让"构建 Agent"的门槛大幅降低——你只需要写几行代码，定义几个工具，就能拥有 一个"看起来能自主工作"的 AI 程序。

然而，当你真正尝试构建一个能够在生产环境中可靠运行、处理真实用户请求、 支持多轮对话、优雅应对 API 限流与超时、管理上下文窗口的 Agent 时， 你会发现框架教程里那些优雅的 demo 和真实的生产系统之间存在一道巨大的鸿沟。

这道鸿沟的核心在于：工程复杂性 。

一个生产级 Agent 需要同时处理以下问题：

  • 如何设计主循环，使其既能流式响应又能执行工具调用？

  • 如何在多个 LLM 提供商（OpenAI、Anthropic、Bedrock）之间优雅地切换？

  • 当上下文窗口溢出时，如何在不丢失关键信息的情况下压缩对话历史？

  • 如何在迭代预算耗尽前引导模型完成任务？

  • 如何实现工具的并行执行，同时保证交互式工具的顺序性？

  • 当 API 返回各种类型的错误时，如何智能地分类并选择恢复策略？

这些问题很难在论文中找到答案，也很难在框架文档中找到系统的论述。 它们分散在成千上万行代码的细节中，隐藏在错误处理的分支逻辑里， 嵌套在异步调用的层层回调之间。

这本书的目标就是跨越这道鸿沟。

我们选择了一个真实的生产级 AI Agent 项目——Hermes Agent（又称 hermes-agent） ——作为分析对象。这不是一个教学项目，不是为了"展示架构"而精心构造的示例代码。 它是一个拥有超过 15000 行核心逻辑、支持十余种工具、运行在 CLI 和网关两种模式下的 真实系统。我们通过逐行分析其关键模块，带你理解一个生产级 Agent 的完整生命周期。

1.1.1. 为什么是 Hermes Agent？

选择 Hermes Agent 作为分析对象有三个理由：

第一，规模适中。 Hermes 的核心循环（run_agent.py）约 12000 行， 工具系统约 3000 行。这个规模大到足以覆盖生产系统的所有关键挑战， 又小到可以被一个人完整理解。它不是那种需要六个月才能读完的百万行代码库。

第二，架构完整。 Hermes 涵盖了一个 Agent 系统的几乎所有核心子系统：

  • Agent 主循环（observe-think-act loop）

  • 流式 API 调用与多提供商适配（109+ Provider，5 种适配器）

  • 工具注册、发现、调度与并行执行（50+ 工具，7 种执行环境后端）

  • 上下文压缩与 prompt 缓存

  • 会话持久化与状态管理

  • 错误分类与智能恢复

  • 子代理委派与预算共享

  • 多 Profile 协作 Kanban（SQLite 持久化任务看板，调度器 + Worker 模型）

  • 插件系统与 MCP 工具集成

  • 智能模型路由（cheap-vs-strong 自动选择）

第三，设计有启发性。 Hermes 的许多设计决策并非显而易见。 例如，它使用 SimpleNamespace 对象来统一不同 API 模式的响应格式； 它通过线程局部事件循环来避免 asyncio 的 "Event loop is closed" 错误； 它在预算耗尽时不立即终止，而是给模型一次"宽限调用"的机会来完成总结。 这些设计背后的考量——为什么要这样做、其他方案有什么问题——是本书最核心的内容。

1.2. 为什么通过真实代码学习？

理论学习有其价值，但对于工程性极强的 Agent 开发来说，仅靠理论是不够的。

理论告诉你 Agent 是一个 observe-think-act 循环， 但不会告诉你当 API 调用在第 17 次迭代时因为 429 限流失败，你需要同时考虑凭证轮换、 上下文压缩和提供商回退三种恢复路径。

理论告诉你 Agent 需要使用工具， 但不会告诉你当模型幻觉出不存在的工具名时， 你需要一个"自动修复"机制来处理拼写错误，同时限制重试次数以防止无限循环。

理论告诉你需要管理上下文窗口， 但不会告诉你当提供商返回的错误信息被 OpenRouter 包装在 metadata.raw JSON 嵌套中时，你需要三层解包才能 识别出真正的上下文溢出错误。

通过分析真实代码，我们能够理解这些"理论不会告诉你"的工程决策。

另一个同样重要的理由是：阅读代码是软件工程师最被低估的核心能力。 在一个 AI 辅助编程日益普及的时代，能够阅读、理解和评估复杂系统的能力 变得越来越关键。本书通过分析一个真实的生产代码库来锻炼这种能力。

1.3. 如何阅读这本书

1.3.1. 推荐阅读路径

本书的组织遵循从整体到局部、从概念到实现的原则。

        flowchart LR
    classDef start fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
    classDef success fill:#dcfce7,stroke:#16a34a,color:#166534
    classDef warn fill:#fef9c3,stroke:#ca8a04,color:#854d0e
    classDef info fill:#f1f5f9,stroke:#64748b,color:#334155

    A["前言<br/>(你在这里)"] --> B["第一部分：基础概念"]
    B --> C["Agent Loop<br/>核心循环"]
    C --> D["工具系统"]
    C --> E["Prompt 管线"]
    C --> F["上下文压缩"]
    D --> G["会话与状态"]
    E --> G
    F --> G
    G --> H["CLI 与网关"]
    H --> I["插件与扩展"]
    I --> J["安全与配置"]
    J --> K["第二部分：经验与实战"]

    class A start
    class C success
    class D,E,F warn
    class G,H,I,J info
    class K success

推荐阅读路径

如果你是完全的新手： 从第一部分的基础概念开始，按顺序阅读到 Agent Loop 章节。 这是本书最重要的章节，涵盖了 Agent 主循环的完整生命周期。之后可以根据兴趣选择其他章节。

如果你有 Agent 开发经验： 直接跳到 Agent Loop 章节。然后阅读工具系统、 上下文压缩和错误恢复等章节，这些是 Hermes 最有设计亮点的部分。

如果你在做代码审查或架构评审： 重点阅读 Agent Loop、错误分类与恢复、 以及会话持久化章节。这些章节深入讨论了设计权衡和替代方案。

1.3.2. 代码引用约定

本书中所有代码引用都指向 Hermes Agent 仓库中的实际文件。 引用格式为 文件名:行号 ，例如 run_agent.py:8668 表示 run_agent.py 文件的第 8668 行。代码片段经过适当精简以突出重点，省略了不相关的分支逻辑。

代码中使用了以下关键文件：

文件

职责

run_agent.py

AIAgent 类、run_conversation 主循环、流式调用、工具调度

model_tools.py

工具发现、注册、调度、参数类型强制转换

agent/error_classifier.py

API 错误分类管道、FailoverReason 枚举

agent/retry_utils.py

抖动指数退避算法

agent/context_compressor.py

上下文窗口压缩、摘要生成

agent/prompt_builder.py

系统提示词构建、身份注入

tools/registry.py

工具注册中心、自发现机制

1.4. 前置知识

阅读本书需要以下基础：

1.4.1. Python 编程

你需要熟悉 Python 3.10+ 的语法，特别是：

  • 类型注解（Optional[str] 、Dict[str, Any]）

  • 上下文管理器（with 语句）

  • 装饰器和属性（@property）

  • threading 模块的基本用法（threading.Lock 、threading.Thread）

  • dataclass 和 enum

你不需要是 asyncio 专家——事实上，Hermes 的一个有趣设计决策就是 刻意避免在主循环中使用 async/await 。本书会在相关章节解释这一决策的原因。

1.4.2. LLM API 基础

你需要了解以下概念：

  • Chat Completions API 的消息格式（system/user/assistant/tool 角色）

  • 工具调用（function calling）的工作方式

  • 流式响应（SSE streaming）的基本原理

  • Token 计费模型的基本概念

如果你不熟悉这些概念，第一部分的基础章节会提供简要介绍。

1.4.3. 异步编程概念

Hermes 使用了同步事件循环（asyncio.new_event_loop()）而非原生 async/await 来处理异步操作。理解为什么这样做需要一些 asyncio 的基础概念：

  • 事件循环（event loop）是什么

  • run_until_complete() 与 asyncio.run() 的区别

  • 为什么 asyncio.run() 会关闭事件循环

本书会在 Agent Loop 章节的流式架构部分详细解释这些概念。

1.5. 章节概览

1.5.1. 第一部分：基础（Part 1）

基础概念（Part 1 Index） 定义什么是 AI Agent，梳理 Agent 架构的演进历史， 建立本书的分析框架。如果你已经熟悉 ReAct、Reflexion 等架构，可以快速浏览。

1.5.2. 核心架构

Agent Loop（核心循环） —— 本书最重要的章节。逐行分析 run_conversation() 方法，覆盖 AIAgent 类的架构设计、主循环流程、流式调用、错误分类与恢复、 工具执行引擎、预算控制、会话持久化等七个主题。包含 5 个以上的 Mermaid 图表。

工具系统（Tool System） 分析 Hermes 的工具注册、发现、调度架构。 理解工具如何通过自注册模式加入系统，参数如何被强制转换，工具集如何被过滤。

Prompt 管线（Prompt Pipeline） 解析系统提示词的构建过程。 理解身份注入、平台适配、上下文文件加载、技能提示等如何组合成最终的 prompt。

上下文压缩（Context Compression） 深入分析当对话超过上下文窗口时的 自动压缩机制。理解摘要生成策略、头尾保护、工具输出裁剪等关键技术。

会话与状态（Session & State） 分析会话持久化的完整路径。 理解 SQLite 存储、消息冲刷、跨轮次状态恢复的实现。

1.5.3. 平台层

CLI 与 TUI 分析命令行界面的实现，理解用户交互如何与 Agent 核心对接。

网关 RPC 分析网关模式的实现，理解 Hermes 如何通过 RPC 服务多平台用户。

MCP 集成 分析 Model Context Protocol 工具的集成方式。

插件系统 分析 Hermes 的插件架构，理解钩子（hook）机制和工具扩展点。

技能系统 分析可复用技能的存储、发现和自动注入机制。

模型路由 分析多提供商的模型选择与凭证管理。

配置管理 分析 YAML 配置系统与运行时配置合并。

安全 分析沙箱执行、破坏性命令检测等安全机制。

1.5.4. 第二部分：经验与实战（Part 2）

经验总结 从 Hermes 的设计中提炼通用的 Agent 工程原则和反模式。

构建你自己的 Agent 基于从 Hermes 学到的架构模式，提供一个从零构建 生产级 Agent 的实践指南。

1.5.5. 附录

术语表 中英文术语对照与定义。

文件索引 仓库中关键文件的快速参考。

1.6. 本书的边界

本书 不是 一份 Hermes Agent 的使用手册。我们不会告诉你如何安装和运行 Hermes。 如果你想使用 Hermes，请参考其项目文档。

本书 不是 一本 LLM 应用开发入门书。我们假设你已经知道如何调用 OpenAI API， 知道什么是 token，知道什么是 system prompt。

本书 是 一份通过深度分析真实生产代码来学习 Agent 架构设计的工程指南。 它会告诉你那些教程不会教你的东西：如何处理边界情况，如何做设计权衡， 如何让一个系统在真实世界的混乱中保持可靠。

1.7. 致谢

感谢 Hermes Agent 的所有贡献者。正是他们的工程实践为我们提供了 这个丰富的学习素材。感谢 Nous Research 团队将这个项目以开源形式发布， 让整个社区都能从中受益。

开始之前，请确保你已经克隆了 Hermes Agent 仓库， 并能在编辑器中打开 run_agent.py —— 我们即将开始一段深入的代码旅程。