前言

这本书的缘起

2025 年到 2026 年，AI Agent 经历了一场从概念到产品的爆发。

这场爆发的前奏来自行业领袖们不约而同的判断。Sam Altman 宣称 Agent 将成为 AI 的杀手级应用；Dario Amodei 在《Machines of Loving Grace》中描绘了 Agent 深度参与软件工程的未来；Andrew Ng 在多次演讲中反复强调 Agentic Workflow 的核心理念——不是让模型一次性给出答案，而是让它像人类一样迭代：思考、行动、观察、调整。到了 2026 年，各种 Agent 产品已经成为开发者的日常工具，Agent 的时代不再是将来时，而是现在进行时。

市面上讲 AI 的书不缺。讲 Prompt Engineering 的、讲 API 调用的、讲 LangChain 等编排框架的，一搜一大把。但当我们真正打开一个大型生产级 Agent 产品的源码时，发现了一个令人意外的事实：LLM 本身只占代码量的极小部分。一个完整 Agent 系统中约 99% 的代码，在做另一件事——构建围绕 LLM 的运行时框架。

Andrej Karpathy 曾将 LLM 类比为「新的操作系统内核」。如果 LLM 是内核，那么工具系统是系统调用，权限模型是访问控制，上下文管理是内存管理，多 Agent 编排是进程调度。这整套包裹在 LLM 外层的基础设施，我们称之为 Harness。

Agent = LLM + Harness

LLM 提供推理能力，Harness 提供工具、权限、记忆、编排。几乎所有人都在谈论等号左边的 Agent 和右边的 LLM，但很少有人系统地讲清楚 Harness 到底怎么造。这本书要填补的，正是这个空白。

我们分析了一个日活数百万开发者、每周产生超过 3400 万次子 Agent 调用的生产级系统。它不是一个框架的 demo，不是一篇论文的 proof-of-concept，而是一个在真实世界中承受了海量用户考验的完整产品。它的代码库覆盖了 Agent Harness 的每一个关键维度——从核心循环到工具系统，从权限模型到多智能体编排，从记忆机制到生态扩展。

打开这个代码库的那一刻，我们意识到：这里藏着的不是某个产品的实现细节，而是一整套构建可信 AI Agent 的工程方法论。踩过的坑、做过的权衡、选择的架构模式，是任何教科书和论文无法替代的实战经验。它值得被系统地梳理、抽象、分享出来。

于是有了这本书。

一本关于「第二个 99%」的书

需要澄清一个可能的误解：这不是一本关于某个特定产品的书。

我们分析的系统是一个案例，但本书的目标是提炼出通用的 Agent Harness 设计模式。就像《设计模式》一书分析了 Smalltalk 和 C++ 的代码，但提炼出的 23 个模式适用于所有面向对象语言一样——权限的四层纵深防御、子 Agent 的 fork 隔离、System Prompt 的静态/动态分区、上下文的多层压缩策略，这些模式不绑定特定语言或框架。

如果你用 Python 写 Agent，书中的伪代码不会妨碍你理解。如果你用 Go 或 Rust 写 Agent，底层的架构原则同样适用。我们关注的不是「这个系统是怎么做的」，而是「构建 Agent Harness 时，有哪些问题必须面对，有哪些久经考验的解法」。

业界常说 AI 应用开发中「最后 1% 的模型能力需要 99% 的工程量来释放」。这本书讲的就是那个 99%。

谁应该读这本书

我们为四类读者写了这本书。每类读者关心的问题不同，能从中获得的收获也不同。

AI 应用开发者。 你正在或即将构建自己的 Agent 产品。你需要回答的问题不是「怎么调 API」，而是「怎么设计一个工具系统让 40 个功能各异的工具统一管理」「怎么在 200K token 的上下文窗口里管理不断膨胀的对话历史」「怎么让多个 Agent 并行工作又互不干扰」。本书从生产级代码中提炼出的设计模式和架构决策，会成为你避开弯路的地图。重点阅读 Part II（Agent Loop）、Part III（工具系统）和 Appendix D（动手构建 Mini Harness）。

架构师。 你的职责是评估和选择 Agent 框架，或者为团队设计 Agent 基础设施。你需要的不是框架的 API 文档，而是框架背后的设计原理——为什么权限要分四层？为什么子 Agent 要用 fork 而不是从零创建？为什么 System Prompt 要拆成静态和动态两半？理解了这些「为什么」，你才能在 LangChain、CrewAI、AutoGen 等框架之间做出知情决策，或者自信地决定自己造轮子。重点阅读 Part I（心智模型）、Part IV（安全与权限）和 Chapter 22（设计哲学）。

LLM 研究者。 你关注的是模型能力如何通过工程手段被放大或约束。一个纯推理引擎如何通过 Harness 获得行动能力？提示词工程的边界在哪里，什么时候必须靠代码而非 prompt 来约束行为？协调者模式为什么要剥夺 Coordinator 的工具使用权，用架构约束替代提示词劝说？这些问题的答案分布在 Part V（多智能体）、Part VI（Prompt 与记忆）和 Part VIII（前沿与哲学）中。

对 AI Agent 好奇的技术人员。 你用过各种 Agent 产品，惊叹于它们的能力，但好奇「这到底是怎么做到的」。你想超越 Demo 和 Prompt Engineering，看看一个真正的 Agent 在引擎盖下是什么样子。本书不预设你读过任何源码，每章都从一个直觉性的问题出发，用类比和叙事引导理解。从 Chapter 1 开始顺序阅读即可。

你不需要是 TypeScript 专家。书中所有代码示例都是伪代码，重在传达思路而非编译通过。但如果你有 Web 开发或系统编程的背景，对异步编程、事件驱动和进程模型有基本了解，阅读体验会更流畅。

如何阅读本书

全书 8 个 Part，22 章加 4 个附录。每章围绕一个核心问题展开，具有一定的独立性。但章节之间存在依赖关系——后面的章节建立在前面章节引入的概念之上。

我们提供三条推荐阅读路径，适合不同的时间预算和目标。

路径一：快速了解（4 章，约 3 小时）

如果你只想在一个下午建立对 Agent Harness 的整体认知：

Chapter 1 --> Chapter 3 --> Chapter 6 --> Chapter 22

Chapter 1 建立「Agent = LLM + Harness」的心智模型。Chapter 3 带你走完一轮完整的 Agent 循环。Chapter 6 解剖工具系统的接口设计。Chapter 22 提炼七条设计原则。四章读完，你对 Agent Harness 的核心架构和设计哲学已有清晰的图景。

路径二：深入 Agent 核心（Part I --> Part II --> Part III，顺序阅读）

如果你准备构建自己的 Agent，需要深入理解核心机制：

从 Part I 开始建立全局认知，然后进入 Part II 理解 Agent Loop 的完整生命周期（API 调用、流式响应、上下文管理），再到 Part III 掌握工具系统的设计、注册、调度和编排。这三个 Part 共 8 章，构成了 Agent Harness 的骨架。

读完后根据需要选读：对安全感兴趣继续 Part IV，对多 Agent 编排感兴趣跳到 Part V。

路径三：实战优先

如果你是「先动手再看书」的类型：

Appendix D --> Chapter 3 --> Chapter 6 --> Chapter 9 --> 其余章节

先跟着 Appendix D 从零构建一个 Mini Agent Harness——10 行代码的最简循环，逐步加入工具、权限、多轮对话。动手的过程中你会产生很多「为什么要这样设计」的疑问，然后带着这些疑问回到对应章节，理解会深刻得多。

关于每章的结构

每一章遵循「问题 --> 思路 --> 实现」的三段式结构（少数章节根据内容略有变化）：

• 问题：一个具体的工程困境，读者可以先想想自己会怎么做
• 思路：设计者的思考路径，为什么选这个方案而不是其他方案
• 实现：用伪代码展示关键逻辑，源码只是验证思路的证据

每章末尾附有思考题，将该章的设计决策推广到你自己的场景。这些思考题不是考试题——没有标准答案，但认真想一想，你会发现很多设计取舍在不同场景下有完全不同的最优解。

一些阅读建议

无论你选择哪条路径，以下建议可能有帮助：

• 带着问题读。 每章开头的核心问题不是修辞——在看答案之前先想想自己会怎么设计。你的直觉方案和系统实际方案的差异，往往是最有教学价值的部分。
• 不要跳过类比。 书中大量使用了日常类比（机场安检、餐厅分工、员工手册）来解释技术概念。这些类比不是文学装饰，而是帮助你建立直觉模型的脚手架。
• 关注「违反会怎样」。 很多章节不只讲「应该怎么做」，还讲「如果不这样做会出什么问题」。理解反面案例往往比理解正面方案更能加深认知。
• 动手验证。 如果某个设计模式让你觉得「这样做真的有必要吗」，试试用 Appendix D 的 Mini Harness 改改看。实验出真知。

本书的方法论

Anthropic 的 "Building Effective Agents" 指南开篇说过："The most successful implementations we've seen aren't using complex frameworks -- they're using simple, composable patterns." 本书遵循同样的理念。

我们不是在罗列代码。 这不是一本源码注释集。源码是证据，不是阅读的主体。我们的任务是从数万行 TypeScript 中提炼出可迁移的设计模式和工程决策。

我们用伪代码而非真实代码。 真实代码绑定语言特性、框架版本和工程细节，它们对理解设计思想是噪音。伪代码保留核心逻辑，去掉不相关的实现细节，让 Python 开发者、Go 开发者、Rust 开发者都能读懂。

我们讲「为什么」而不只是「是什么」。 技术书籍最常见的缺陷是描述了系统做了什么，却不解释为什么做了这些选择。每一个架构决策都有它的上下文：什么约束迫使了这个选择？考虑过哪些替代方案？选择的代价是什么？「违反会怎样」往往比「应该怎样」更有教学价值。

我们追求可迁移性。 本书分析的是一个特定系统，但目标是让读者能将其中的模式应用到自己的场景中。权限的四层防线、子 Agent 的 fork 隔离、System Prompt 的静态/动态分区、上下文的多层压缩策略——这些模式不依赖于特定的语言或框架。你用 Python 写 Agent，用 Go 写 Agent，甚至用 Rust 写 Agent，这些模式同样适用。

我们承认局限。 本书基于对一个特定时间点的代码库的分析。软件在持续演进，某些实现细节在你阅读时可能已经改变。但我们刻意将关注点放在设计原则和架构模式上，而非实现细节上——原则的半衰期远长于代码。

我们重视叙事。 技术写作不等于枯燥。每一章都从一个具体的、读者能感同身受的困境出发——「你让 Agent 整理项目结构，它执行了 rm -rf /」「你的上下文窗口在 30 轮对话后爆了」「三个子 Agent 同时写同一个文件」。我们相信好的技术叙事能让复杂概念变得直觉化，而直觉化的理解比死记硬背更持久。

全书结构一览

Part I    什么是 Harness           2 章    建立心智模型
Part II   Agent Loop              3 章    核心循环的生命周期
Part III  工具系统                 3 章    Agent 的手和脚
Part IV   安全与权限               3 章    Agent 的缰绳
Part V    多智能体                 4 章    从个体到团队
Part VI   Prompt 与记忆            2 章    灵魂和笔记本
Part VII  扩展机制                 3 章    开放的 Agent
Part VIII 前沿与哲学               2 章    设计原则的提炼
附录 A-D                          4 篇    架构图、类型速查、Feature Flag、实战教程

八个 Part 的组织逻辑是从内到外：先理解 Agent 的心跳（循环），再看它怎么和外部世界交互（工具），然后是约束（权限）、协作（多 Agent）、记忆（Prompt 与状态）、扩展（生态），最后上升到设计哲学。

四个附录各有分工：Appendix A 提供六张 ASCII 架构图供随时查阅；Appendix B 汇总了十个核心 TypeScript 类型定义，是阅读伪代码时的速查手册；Appendix C 完整列出了系统的 Feature Flag 清单（89 个编译时 + 18 个运行时 + 41 个环境变量），展示了大型 Agent 系统的可配置性；Appendix D 是从零构建 Mini Agent Harness 的实战教程——从 10 行代码的最简循环，逐步加入工具注册、权限检查、多轮对话和上下文管理，最终得到一个可运行的 Mini Harness。

这本书不是什么

为了避免期望错位，有必要说明本书不是什么：

• 不是 API 使用教程。 不会教你怎么调用某个 LLM 的 API。市面上有大量这类教程，本书假设你已经知道如何发起一次 API 调用。
• 不是框架使用指南。 不会教你怎么用 LangChain 或 CrewAI 搭建工作流。本书讲的是框架本身是怎么造的，而不是怎么用框架。
• 不是学术论文。 不追求严格的形式化证明或数学推导。本书是工程实践的提炼，追求的是实用性和可操作性。
• 不是特定产品的使用手册。 虽然分析了一个具体的系统，但目标是提炼通用模式，不是教你使用那个产品。

如果用一句话概括本书的定位：这是一本关于如何为 LLM 构建生产级运行时框架的工程方法论著作。

排版约定

本书使用以下排版约定：

• 等宽字体 用于代码、命令、文件名和技术术语（如 AsyncGenerator、tool_use）
• 粗体 用于首次出现的关键概念
• 引用块用于重要论断或来自业界的引述
• 伪代码块标注「概念示意」，表明这不是可编译的代码，而是传达设计意图
• 每章末尾的思考题以灰色框呈现

致谢

这本书的诞生，依赖于整个 AI 研究和开源社区的集体贡献。

感谢 Transformer 架构的发明者们，让大语言模型成为可能。感谢 OpenAI、Anthropic、Google DeepMind 等机构的研究者们，持续推动模型能力的边界。感谢 Andrew Ng、Andrej Karpathy、Harrison Chase 等研究者和实践者，他们的公开演讲和技术文章为 Agent 工程奠定了概念基础。

感谢 MCP（Model Context Protocol）的设计者，定义了 Agent 连接外部世界的开放标准。感谢 LangChain、CrewAI、AutoGen、OpenAI Agents SDK 等框架的开发者，他们的工作让整个社区受益，也为本书的分析提供了丰富的对比视角。

感谢开源精神。本书分析的核心对象是一个生产级系统的架构模式。我们无意复制或泄露任何私有实现，所有代码示例都是为教学目的创作的伪代码。我们的目标是让这些来之不易的工程经验成为公共知识的一部分，帮助更多人构建更好的 Agent 产品。

感谢每一位早期读者和审校者。你们尖锐而中肯的反馈让每一章都变得更清晰、更准确、更有用。正是这些反馈让我们意识到，哪些地方的类比选得不够贴切，哪些地方的伪代码省略了关键步骤，哪些地方的论证跳跃了逻辑环节。

感谢我们的家人和朋友，在无数个深夜和周末给予的理解与支持。写一本技术书籍的时间成本远超预期——但每当收到读者的正面反馈，就觉得一切值得。

最后，感谢你——读者。你愿意花时间深入 Agent 的引擎盖下面，而不是停留在表面的 API 调用，这本身就是对工程卓越的追求。AI Agent 的时代才刚刚开始，最好的 Agent 产品还没有被写出来。也许它就在你读完这本书之后诞生。

希望这本书能成为你构建 AI Agent 之路上的有用参考。

「理解了 Harness 怎么造，你才真正理解了 Agent 是什么。」

如果你在阅读过程中发现错误、有改进建议，或者想分享你基于本书模式构建的 Agent 项目，欢迎通过本书的开源仓库提交反馈。好的技术书籍不是写出来的，是迭代出来的——就像好的 Agent 一样。

让我们开始吧。

翻到 Chapter 1，看看一个只能思考的大脑，是如何长出双手、长出眼睛、戴上缰绳，变成一个能行动的 Agent 的。

二零二六年春 于无数个与 AI Agent 对话的深夜之后