前言
过去两年，“Agent” 这个词被用滥了。它有时指一次带工具的 LLM 调用，有时指一个能自己跑一整晚的编码助手，有时又指一套横跨多个服务的企业级编排平台。当概念的边界如此模糊，学习就变得困难：你读到的每篇文章可能都在讲不同的东西。
这本书想做的，是用一个真实、可读源码的系统，把这些概念钉在地上。
这本书讲什么
本书讲述从单个 Agent 的最小闭环，一路走到生产级多智能体系统的设计模式。
它有一个鲜明的选择：以一个你可以直接 clone、直接读、直接改的开源 agent harness——pi——作为贯穿全书的参考实现，让每一个模式都能落到真实、可运行的代码上。
pi 是一个用 TypeScript 编写的 agent harness：它包含 agent runtime、多 provider LLM 层、工具调用、扩展机制、技能系统、会话管理，以及一个实验性的多 agent orchestrator。它和 Claude Code 属于同一类东西——一个“能跑 agent 的宿主”。
选择 pi，是因为它恰好覆盖了本书要讲的大部分模式，而且每一个模式都能落到一段真实的源码上。当我们讲 ReAct 循环，我们会打开 agent-loop.ts；当我们讲 Hooks，我们会看 pi 的扩展如何拦截生命周期事件；当我们讲安全执行，我们会看它的三种容器化方案。
什么是 Harness，为什么它是本书的核心
这本书的书名叫《AI Agent：如何构建企业级 Harness 智能体》。Harness（宿主） 这个词是全书的骨架，值得一开始就讲清楚。
一个 Agent 要真正跑起来、还要能上生产，光有一个聪明的大模型远远不够。它需要一层承载并运行 Agent 的基础设施：把模型调用、工具执行、上下文管理、会话持久化、多模型适配、错误重试、安全隔离这些又难又琐碎的工程一并扛下来。这一层，就是 Harness。
打个比方：如果模型是发动机，那 Harness 就是整台车的底盘和传动系统——离合、变速箱、刹车、方向盘。没有底盘，再强的发动机也只是原地轰鸣，跑不起来、更谈不上安全上路。pi、Claude Code 都属于这一类“底盘”；而本书教你的，正是如何看懂这套底盘、并在它之上装出你自己要的那台车。
为什么“企业级”离不开 Harness？因为企业真正关心的东西——成本可控、行为可审计、执行可隔离、故障可恢复、多用户可隔离——没有一样能只靠模型解决，全都落在 Harness 这一层。所以本书的主线不是“怎么调 prompt”，而是“怎么在一个 Harness 之上，构建出达到企业标准的 Agent”：
- 前半部分（第 1–6 部分）讲清 Harness 提供的核心能力：循环、工具、技能、上下文、记忆、多 Agent 协作——这是“底盘上有哪些部件”。
- 后半部分（第 7–9 部分）讲清怎么把它推上生产：架构分层、远程驱动、可观测、预算、治理、安全、多租户——这是“如何让这台车合规上路”。
- 全书的落点（最后一章）只有一句话：不要从零造 Harness，要在成熟的 Harness 之上构建你独有的价值。
记住这条主线，后面每一章你都会看到它——每个模式，都是在为“构建一个企业级的 Harness 智能体”添砖加瓦。
本书 Harness 维度覆盖图
「Harness 是什么」一章给了你一张判别 Agent 有没有 Harness 的 10 条清单。下面这张图把这 10 项对应到全书的章节——既能当导航，也能看出哪几项有专章、哪几项横切、哪几项落在 Agno 实战里。
| 判别维度 | 正文落点 | Agno 实战（Part 10） |
|---|---|---|
| 1 执行循环 | 第 3 章 ReAct 循环 | 第 36 章 进入 Agno 实战轨 |
| 2 工具执行 | 第 4 章工具调用、第 5 章 MCP、第 6 章结构化输出 | 第 37 章 Tools 与 MCP |
| 3 状态持久化 | 第 10 章记忆、第 12 章多轮对话、第 24 章 RPC、第 29 章多租户 | 第 39 章 Storage/Memory |
| 4 循环控制/停止 | 第 8 章 Hooks（阻断/中止） | 第 42 章 治理与人审 |
| 5 异常兜底 | 横切（散见第 2、7 章；无专章） | 第 42 章 回滚降级 |
| 6 上下文工程 | 第 9 章上下文工程 | 第 39 章 Memory |
| 7 可观察性 | 第 8 章 Hooks、第 25 章可观测性 | 第 41 章 AgentOS 运行时 |
| 8 权限/安全边界 | 第 27 章策略治理、第 28 章安全执行 | 第 42 章 治理安全部署 |
| 9 扩展机制 | 第 7 章 Skills、第 16 章编排基础 | 第 40 章 Team/Workflow |
| 10 动态切换 | 第 34 章分层模型策略 | —（Agno 多 provider，散见各章） |
一句话读法：正文讲清 Harness 的 10 项能力，Part 10 用 Agno 把同样的模式落到第二个 harness 上——这恰好印证“学模式不学 pi”。第 5 项「异常兜底」没有专章，是横切能力，散见循环与 Hooks。
为什么是“模式先于框架”
框架会过时，模式不会。
LangGraph、CrewAI、PydanticAI、Agno、pi——它们都会迭代、改名、甚至消失。但“如何在有限上下文里保留关键信息”“如何让多个 Agent 交接任务”“如何在不信任的代码前设一道门”这些问题，会一直存在。
所以本书每一章都遵循同样的四步结构：
- 先讲问题——这个模式要解决什么，不用它会怎样
- 再讲模式——通用的解法，与具体框架无关
- 用 pi 实现——打开真实源码，看它怎么落地
- 与其他框架对比——同样的模式，LangGraph / Agno / Claude Agent SDK 怎么做
这样即使有一天你不用 pi，学到的东西依然成立。
目标读者
这本书写给两类人，它们往往是同一个人的两个阶段：
- 想快速上手构建 Agent 的开发者——你会从“用 pi 实现”和“框架对比”里，最快地知道该写什么代码。
- 关注 Agent 运行时与生产架构的工程师——你会从 pi 的源码里，看到工具调用、上下文压缩、沙箱隔离这些底层机制到底怎么实现。
不需要你精通 TypeScript——pi 的代码足够直白，我们也会解释关键片段。你只需要理解基本的编程概念，和“LLM 是什么”。
一个贯穿全书的项目
从第 1 章到最后一章，我们会逐步构建同一个东西：一个研究型 Agent（Research Agent）。
它一开始只是一次带工具的调用，然后我们给它加上技能、记忆、上下文压缩，让它学会规划与反思，再把它拆成多个协作的 Agent，最后把它送上生产环境。每一章的新知识，都会落到这个项目上——到全书结束时，你会拥有一个真实可跑、构建在 pi 之上的完整 Agent。
这条主线可以按 Part 这样理解：
| 部分 | Research Agent 长出什么能力 | 对应产物 |
|---|---|---|
| Part 1 · Agent 基础 | 从一次模型调用变成能循环行动的 Agent | 能提出下一步、调用工具、观察结果 |
| Part 2 · 工具与扩展 | 接入外部系统，并把输出变成程序可消费的数据 | 销量查询、MCP 工具、结构化研究结果、技能与确认门 |
| Part 3 · 上下文与记忆 | 管住长任务需要的资料、偏好、状态和知识库 | 上下文压缩、长期偏好、RAG 检索、多轮会话 |
| Part 4 · 单 Agent 模式 | 让单个研究员更会规划、反思和推理 | 研究计划、自我检查、结构化推理 |
| Part 5 · 多 Agent 编排 | 把一个研究员拆成多个角色协作 | 并行研究员、综合 Agent、交接与工作流 |
| Part 6 · 高级推理 | 用搜索、辩论、研究—综合提高质量 | 多方案比较、证据交叉验证、深度报告 |
| Part 7 · 生产架构 | 把它做成可远程驱动、可追踪的服务 | RPC 会话、成本/trace、Web/后台入口 |
| Part 8 · 企业级特性 | 给它加预算、治理、安全和多租户边界 | 预算上限、策略门、沙箱、租户隔离 |
| Part 9 · 前沿实践 | 把它扩展成深度研究、浏览器操作、后台 Agent | Deep Research、Computer Use、Agentic Coding、Background Agent |
| 第 35 章 + 附录 | 把前面能力装配成可上线的产品 | 示例仓库、评测回归、上线运维清单 |
你不必在第一遍就记住所有章节。只要记住这个演进：先让 Agent 会做事，再让它会查资料、会协作、可观察、可治理，最后才谈上线。
怎么读
按顺序读最好。但如果你已经有基础，也可以直接跳到你关心的 Part：
- 只想快速做个能用的 Agent → Part 1、Part 2
- 关心上下文与记忆 → Part 3
- 关心多 Agent 协作 → Part 5
- 关心生产与安全 → Part 7、Part 8
准备好了吗？我们从最基本的问题开始：到底什么是 Agent。