ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

2026-08-20 13:12:50 +00:00
commit b119135836
10275 changed files with 3284984 additions and 0 deletions
@@ -0,0 +1,112 @@
+# 人工智能代理入门 [第1部分/共5部分]
+## 人工智能代理入门
+
+如果你使用过Cursor编写代码，并且看到它搜索你的代码库、编辑多个文件并重新运行测试直到通过，那么你已经使用过人工智能代理了。如果你使用过Deep Research通过反复搜索和阅读来研究某个主题、让Manus控制浏览器完成在线任务、让豆包手机助手订票或发送消息，或者让Pine AI协商更低的电信账单，情况也是如此。
+
+这些产品有多种形式，但它们有一个共同特征：它们不再是被动的“你问，它回答”的对话。它们会规划自己的执行步骤，调用每个任务所需的工具，并根据结果调整策略。人工智能代理正在成为与计算机交互的一种新方式。
+
+本章从实际示例开始，逐步回溯到人工智能代理的核心组件：读者将亲身体验现代代理能做什么，了解其背后的架构，并学习构建代理系统的设计模式和最佳实践。
+
+> **阅读提示**：本章是整本书的概念图：对核心公式、操作循环、工程框架和代理设计模式进行简洁概述。它建立了后续章节中使用的共享词汇和参考点。第一次阅读时不要试图记住每个概念；着眼于大局。后面的每一章都会扩展这里介绍的一个方面，你可以在需要重新定位时返回本章。
+
+## 现代代理=大语言模型+上下文+工具
+
+现代代理系统的本质可以用一个简洁的公式概括：**代理=大语言模型（LLM）+上下文+工具**。这个公式简单实用——前提是每个术语都要广义理解：
+
+- **大语言模型是代理的推理引擎**：它不仅仅是一组模型参数；它是代理的决策核心，负责理解意图、推理、规划和判断。大语言模型的能力来自预训练期间获取的世界知识和语言能力，以及通过微调（第7章介绍了监督微调、强化学习等技术）编码的决策策略。
+- **上下文是代理的工作信息集**：不仅仅是输入模型的文本，而是代理在每个决策点可用的工作信息集——环境、用户记忆、领域知识、自身状态和任务进度。就像一个人做决策时需要评估情况、回忆相关经验并参考资料一样，代理的上下文窗口包含了它当时可以使用的信息。
+- **工具是代理的行动接口**：不仅仅是少数可调用的API函数，而是代理可以采取行动的全套方式——从预定义的工具调用到按需加载的技能，从生成代码即时创建新能力到将工作委托给子代理，从与用户互动到响应外部事件。
+
+更直观地说：**代理=推理引擎+工作上下文+行动接口**。模型进行推理和决策，上下文提供这些决策所依赖的工作信息集，工具提供决策影响外部世界的接口。
+
+这三个组件正好对应强化学习（RL）中的三个核心概念（第7章）。以下表格是**可选阅读**——如果你没有强化学习背景，可以随意跳过；后面的内容不依赖它。它仅用于帮助了解强化学习的读者将相关知识映射到本书的术语中：
+
+| 直觉          | 代理组件 | RL概念（可选） | 角色                                                         |
+|---------------|----------|----------------|--------------------------------------------------------------|
+| **推理引擎**  | LLM      | **策略**       | 决定“下一步做什么”的决策逻辑——根据当前信息，从所有可用选项中选择最合适的行动 |
+| **工作上下文**| 上下文   | **观测空间**   | 代理可用的所有信息——它可以观察、读取、记住的内容以及可以访问的系统 |
+| **行动接口**  | 工具     | **行动空间**   | 代理可以做的所有事情——可用的“手段”，从发送消息到执行代码再到控制接口 |
+
+### 观测空间和行动空间：模型与世界的接口
+
+在他们的经典教科书《计算机体系结构：量化研究方法》中，亨尼西和帕特森在第1章开篇提出“什么是计算机体系结构？”，并将**指令集架构**（ISA）确定为软件和硬件之间的接口[^ch1-agent-interface]。这种视角为我们理解代理提供了有用的方式：**观测空间和行动空间共同构成大语言模型与其外部环境之间的接口**。观测空间将环境中的信息转化为模型可以处理的上下文；行动空间将模型决策转化为对外部世界的操作。观测空间之外的信息对模型实际上不存在。行动空间之外的操作仍然是模型只能用语言推荐的事情，即使它完全知道应该做什么。
+
+因此，**一旦底层模型保持不变，提高代理性能的主要系统工程杠杆往往是重新定义或扩展其观测空间和行动空间**。用本书的术语来说，这意味着扩展上下文和工具。许多看似需要“更智能模型”的问题实际上是接口问题：将与任务相关的数据带入上下文，或将所需操作暴露为工具，之前无法解决的任务可能无需重新训练模型就能解决。
+
+**Manus：合并原本独立的空间**。在Manus出现之前，生产型代理主要遵循三条不同的路径：Deep Research、编码和计算机使用。Manus是第一个在一个系统中广泛有影响力地将这三者整合在一起的生产型代理。网络扩大了它的观测空间；文件系统和代码执行扩大了它的行动空间；屏幕感知以及点击和打字将图形界面带入了两者。Manus不仅仅通过替换更强的模型成为通用代理。它整合了三种代理的观测空间和行动空间，使一个代理能够跨越之前的产品边界。
+
+**OpenClaw：将接口扩展到用户的数字生活**。OpenClaw再次将两个空间向外扩展。它通过用户已经使用的消息通道（WhatsApp、Telegram、Slack、Discord、iMessage等）接收任务并返回结果，因此几乎可以从任何地方接触到代理。它的本地优先网关，加上授权的工具、插件和技能，可以连接谷歌驱动器和Notion等云应用以及本地文件系统。因此，在用户明确授权的情况下，分散在账户和设备上的文件可以进入一个代理的观测空间，并由其工具进行操作。与最初以云沙盒为中心的Manus形式相比，Manus中的文件通常必须上传或单独配置连接器，本地优先的OpenClaw跨越了更广泛的数据边界。Manus后来添加了自己的谷歌驱动器连接器和对本地文件的桌面访问——这进一步强化了这一点：产品演进通常恰好包括扩展观测空间和行动空间[^ch1-agent-products]。
+
+扩展并不意味着立即将每个可用的标记和工具倾倒到模型中。不相关的上下文会增加噪声，而太多工具会增加选择成本和安全风险。有用的扩展必须是**按需、相关且受控制的**：检索应将正确的信息放入上下文，工具发现应仅暴露当前需要的行动，权限和结果验证应限制这些行动。后面的章节将开发这些技术中的每一种。
+
+[^ch1-agent-interface]: 约翰·L·亨尼西和大卫·A·帕特森，《计算机体系结构：量化研究方法》，第6版，摩根·考夫曼出版社，2019年，第1章“什么是计算机体系结构？”。该书区分了指令集架构、计算机组织和硬件；指令集架构专门是软件和硬件之间的接口。见https://shop.elsevier.com/books/computer-architecture/hennessy/978-0-12-811905-1
+
+[^ch1-agent-products]: Manus的官方材料描述其原始沙盒是一个孤立的云虚拟机。在介绍其谷歌驱动器连接器时，Manus明确回忆了早期在驱动器、桌面和Manus之间手动下载和上传文件的分散工作流程。当它在2026年3月推出“My Computer”时，它称重要工作本地存在而非在云中是云沙盒的基本限制。OpenClaw的官方README描述了一个在用户自己设备上运行的本地优先、始终在线的个人助理，并列出了二十多个消息通道；其工具和插件系统可以添加云集成和本地功能。见https://manus.im/blog/manus-sandbox，https://manus.im/blog/manus-google-drive-connector，https://manus.im/blog/manus-my-computer-desktop，https://github.com/openclaw/openclaw，以及https://docs.openclaw.ai/tools
+
+理解每个组件的作用以及它们如何组合在一起，是构建有效代理系统的基础。我们将从三个组件中最具体的一个——工具，即行动接口开始，向内深入到LLM和上下文。首先，以下是不同类型的代理在这三个维度上的比较：
+
+| 代理产品       | 工作上下文               | 行动接口                     | 策略                                                         |
+|----------------|--------------------------|------------------------------|--------------------------------------------------------------|
+| **编码代理（例如Cursor）** | 需求文档、代码库、终端环境 | 开放式（内部推理、代码搜索、文件读写、命令执行等） | 增量开发：理解需求→搜索相关代码→编辑代码→测试验证→调试修复 |
+| **搜索代理（例如Deep Research）** | 网络资源、学术数据库、本地文件 | 开放式（内部推理、搜索查询、网络阅读、摘要生成） | 迭代深化：根据现有信息调整搜索方向，逐步合成完整报告       |
+| **计算机控制代理（例如浏览器使用）** | 计算机屏幕、浏览器页面、文件系统 | 开放式（内部推理、点击、打字、滚动、截图、代码执行等） | 视觉感知+操作：观察屏幕→识别目标元素→执行操作→验证结果   |
+| **手机助手代理（例如豆包）** | 手机屏幕、已安装应用       | 开放式（内部推理、点击、滑动、打字、打开应用等） | 意图理解+应用控制：理解用户需求→定位目标应用→执行操作→确认完成 |
+| **个人任务代理（例如Pine AI）** | 用户账户信息、历史账单、服务提供商知识库 | 开放式（内部推理、打电话、发送电子邮件、填写表格、与用户确认） | 多步骤任务执行：收集信息→制定协商策略→联系服务提供商→协商→报告结果 |
+
+这些系统有三个共同特征：**开放式行动空间**——不是从固定的按钮集中选择，而是生成任意自然语言和代码；**内部推理**——行动前进行规划；**连续交互**——根据环境反馈调整策略。这些能力恰好来自推理引擎、工作上下文和行动接口的相互作用——即LLM、上下文和工具。
+
+### 工具：代理的行动接口
+
+工具是代理与外部世界的桥梁。它们将代理从被动观察者转变为可以搜索、写入文件、运行代码、调用API、发送消息或操作接口的主动系统。没有工具，代理仅限于文本生成；有了工具，它可以对外部系统采取行动。
+
+为了系统地讨论工具，我们可以根据代理与世界交互的方向将其分为五种类型。在这个阶段，简要概述每种类型的代表性场景足以建立整体图景；后面的章节将深入讨论每种类型。
+
+**感知工具**允许代理访问信息：搜索引擎提供实时网络数据，文件系统读取本地文档，API和数据库连接到外部服务和企业核心数据。
+
+**执行工具**允许代理对外部系统采取行动：代码执行、文件操作、系统命令和外部API调用将决策转化为具体行动。
+
+**协作工具**允许代理与其他代理分工：将专门任务委托给子代理，在关键决策点请求人类确认，或在多代理系统中协调行动。
+
+**事件触发工具**以与前三种类别根本不同的方式被调用：代理不调用它们；它们作为外部输入到达，触发代理开始工作。新邮件到来、预定时间到达或另一个系统触发Webhook回调；事件激活代理并启动推理和行动。代理永远不会自己调用这些工具，但它们仍然是与外部世界交互的通道，因此我们将它们计入广义的工具系统中。
+
+**用户通信工具**是代理与用户通信的通道。执行工具改变外部世界，而通信工具传递信息——通过短信、语音通话、电子邮件等传递代理的进度或主动签到。
+
+第4章涵盖了这五种类型的完整分类法和设计原则。工具设计的质量直接决定了代理可以可靠完成的任务：模糊定义接口，模型会滥用它们；处理错误不佳，单个失败的工具可能会让代理陷入困境；权限范围太广，一个代理错误可能会不可逆转。随着MCP（模型上下文协议）标准的传播，集成工具变得像安装插件一样容易——生态系统正在迅速扩展，但设计原则不会过时。
+
+**工具调用**（也称为函数调用）是现代大语言模型代理的核心能力：它让模型以结构化方式调用外部工具，将大语言模型从纯文本生成器转变为可以通过外部接口行动的智能系统。本书通篇使用“工具调用”这个术语。
+
+工具调用分为四个步骤：首先，上下文告诉模型哪些工具可用（名称、用途、参数）；然后模型自行决定是否调用工具、调用哪个工具以及使用什么参数；接下来，工具运行后，其结果附加到上下文中；最后，模型根据该结果决定下一步行动。这个循环是后面介绍的ReAct的基础。
+
+以天气查询为例，API级别上四步过程的简化表示如下：
+
+```
+步骤1：声明工具                  步骤2：模型决定调用
+tools: [{                             assistant: {
+  name: "get_weather",                  tool_calls: [{
+    parameters: {                           function: "get_weather",
+      city: "string"                        arguments: {city: "Beijing"}
+  }                                      }]
+}]                                    }
+
+步骤3：结果附加到上下文          步骤4：模型根据结果响应
+tool: {                               assistant: {
+  tool_call_id: "call_1",               content: "Today in Beijing: 28°C, sunny."
+  content: '{"temp":28,"sky":"clear"}' }
+}                                     }
+```
+
+开发者只需定义工具并执行调用；模型自己决定是否调用、调用哪个工具以及传递什么参数。第2章将详细检查这个API结构。
+
+为代理设计工具时，从任务所需的最窄能力开始，然后随着任务变得更复杂逐步扩展。如果任务只需要基本算术，一个参数明确的计算器就足够了；当任务发展到读取电子表格、清理缺失值、计算统计数据和绘制图表时，一个受约束的Python代码解释器比不断增长的专门工具集合更容易组合和探索。但通用性也增加了错误风险并扩大了攻击面：代码必须在隔离沙盒中运行，默认禁用网络访问，无法访问授权工作目录之外的文件，并且对执行时间、CPU、内存和输出大小有限制。
+
+同样，单个日志工具适合记录一次执行；对于耗时数小时甚至数天的长期任务，受控的虚拟工作目录可以保存计划、中间结果、执行日志和最终工件，以便代理可以在多次运行中恢复。这个目录还应限制可读和可写路径、存储容量和文件类型，并防止路径遍历，而不是将整个主机文件系统暴露给代理。
+
+通用工具并不总是比专门工具更好。高风险操作或受严格业务约束的操作——例如支付、数据删除、发送电子邮件和生产部署——仍然应该作为具有明确参数、受限权限和端到端可审计性的专用工具暴露，必要时添加预览和人类确认。因此，工具设计的核心原则是：**使用通用基础能力进行组合和探索；使用专门工具约束高风险操作并强制执行严格业务规则**。
+
+### LLM：代理的推理引擎
+
+大语言模型（LLM）是代理的决策核心。给定用户请求，它首先必须推断真实意图（用户所说的往往不是他们真正想要的），然后将模糊或复杂的任务分解为可执行步骤。在整个执行过程中，它不断做出决策：下一步做什么、是否调用工具、调用哪个工具以及使用什么参数。这种理解-规划-执行能力来自预训练期间积累的知识，是工作流和自主代理都依赖的基础。
+
+大语言模型代理的一个独特能力是**内部推理**——在行动前，代理可以规划和推理任务。这不会改变外部环境，但会显著改善后续行动。这种能力来自预训练（在大量互联网文本上的初始训练，通过它模型学习语言模式和世界知识）：模型利用编码在人类知识中的推理模式，包括数学定律、因果关系和分解问题的策略。因此，代理的推理不是盲目试错；它建立在结构化知识体系之上。
+
+这种结构化推理让大语言模型代理能够处理全新的任务而无需先前示例——零-shot和few-shot两个概念说明了这一点。直接表现是**零-shot泛化**：面对从未见过的任务，代理通过重组已有的知识来处理它，无需示例。模型可能从未被明确教导过写关于量子物理的诗歌，但它可以根据现有语言和物理知识生成合理的诗歌。
@@ -0,0 +1,34 @@
+# 人工智能代理入门 [第2部分/共5部分]
+
+### 少样本适配与模型即代理
+
+通过几个例子，大语言模型代理还可以执行**少样本适配**：提示词中的两三个演示就足以让它学习新的任务模式。如果展示几个“用户评论→情感标签”的例子，它就能对新评论进行情感分类。简而言之：零样本意味着用零个示例解决任务；少样本意味着从少量示例中学习模式。
+
+#### 模型即代理：当模型本身成为产品
+
+“模型即代理”范式是人工智能代理发展的最新方向。先进模型通过微调（尤其是强化学习）将工具调用内化为原生能力：何时调用工具、调用哪个工具、使用什么参数——模型自行决定，无需手动编排。这并不意味着框架层不重要。相反：模型越强，周围的框架就越重要。在代理语境中，框架是将模型能力转化为可靠任务执行的工程基础设施。它包括上下文管理、工具接口、安全约束以及验证和纠正机制（见本章最后一节）。
+
+模型拥有的决策权限越大，错误决策的影响就越大——这需要更细粒度的约束、验证和纠正来保持其可靠性。模型提供商的真正优势不是“让框架更薄”，而是能够共同优化模型及其周围的框架，持续迭代。
+
+但随之而来的是一个更深层次的问题：如果模型不断变强，今天的框架最终会被模型吸收吗？在《苦涩的教训》中，里奇·萨顿回顾了人工智能研究七十年中反复出现的模式[^ch1-1]：研究人员反复将对领域的理解编码到系统中，实现短期收益，但最终输给了随计算和数据扩展的通用方法——搜索和学习。从这个角度看，框架中的多少约束、验证和纠正属于“人类先验”，是模型注定要内化的？本书的立场可以用八个汉字总结：**方向认同，节奏务实**。从方向上看，我们不怀疑模型会继续吸收框架的部分内容——工具调用和长视野规划曾经依赖外部编排，现在已成为原生模型能力。然而，在实践中，这种吸收比直觉慢得多：训练以月为时间尺度进行，没有模型能在一次训练中内化所有真实业务的约束和偏好。模型当前的能力边界正是框架创造价值的地方。因此，框架工程不是对抗《苦涩的教训》，而是在工程时间尺度上践行它：模型尚不能可靠完成的，框架先覆盖；每当模型内化另一层，框架就剥离该层，转向支持下一个能力前沿。这条主线贯穿全书——第2章从上下文工程角度提供务实答案，第8章进一步讨论代理如何从操作经验中选择和验证下一次系统更新，后记回到模型是否会吸收框架的完整答案。
+
+[^ch1-1]: 萨顿，里奇。“苦涩的教训”，2019年。http://www.incompleteideas.net/IncIdeas/BitterLesson.html
+
+#### 代理学习机制：从上下文适配到持续更新
+
+前面的讨论指出，模型可以通过强化学习将工具使用策略内化为原生能力。但代理行为的变化不仅发生在训练期间。根据更新发生的位置和持续时间，这些变化可以理解为三个互补路径（图1-1）：任务内上下文适配、跨任务外部工件更新、训练周期内的参数更新。
+
+![图1-1：代理能力更新的三个层次](images/fig1-1.svg)
+
+**上下文适配**发生在当前任务内。一旦示例、状态和检索结果进入上下文，模型可以立即调整行为，但这不会改变下一会话的持久状态。其优点是速度快、成本低；局限性源于上下文窗口和信息组织方式。第2章详细解释这种适配形式的工作原理。
+
+为了让变化跨任务持久，系统可以更新**外部工件**：事实和经验可以组织成知识文档，可用语言表达的策略可以写入提示词或技能，确定性程序和约束可以编码到程序和框架中。这些工件可审计且可修订，但代理仍必须在执行时通过上下文或工具接口访问它们。第3章到第5章建立知识和程序的基础，第8章讨论如何从评估的操作轨迹中生成此类更新。
+
+当目标是高维能力——如医学图像理解、自然语言风格或隐式决策策略——外部规则无法完全表达时，必须通过微调更新**模型参数**。参数更新带来更高的部署成本，但可以产生自然且广泛的泛化；第7章系统介绍其方法。因此，这三个路径不是互斥的类别，而是在不同时间尺度上运行的协调机制：上下文支持即时适配，外部工件支持受控积累，参数内化难以显式表达的能力。
+
+### 上下文：代理的工作信息集
+
+上下文是代理在每个决策点可用的工作信息集。就像一个人做决策时需要桌上有正确的材料——任务说明、参考手册、之前的通信、最新数据——代理的上下文窗口就是它可以使用的信息。从API角度（第2章详细介绍），每次大语言模型调用的上下文由五部分组成：
+
+- **系统提示词**：不同于用户在对话中输入的提示词，系统提示词由开发者编写，在整个对话中保持固定。它是代理的“工作描述”——定义其身份、权限和行为规则。精心设计系统提示词是塑造代理操作行为的方式。系统提示词还包含跨会话持久的**用户记忆**（偏好、过去行为、背景设置等个性化信息；见第3章），以及动态注入的环境状态。
+- **工具定义**：声明代理可用工具的名称
@@ -0,0 +1,98 @@
+# 人工智能代理入门 [第3部分/共5部分]
+
+### Kimi K3的原生代理能力实验
+Kimi K3在代理任务中的显著优势是**长链式工具调用的稳定性**——它可以持续进行200-300次连续的工具调用，整个过程中推理连贯，远远超过大多数模型开始退化时的几十次调用。K3针对长视野编程和代理工作负载进行了优化，发布了两个变体：K3 Max（用于对话和代理任务）和K3 Swarm Max（用于大规模并行处理）。作为开源模型，它在软件工程和代理基准测试中与顶级闭源系统相当——这证明强化学习可以赋予模型原生的代理能力。
+
+#### 实验1-3 ★：GPT-5.6的原生深度研究能力
+第二个实验使用**OpenAI GPT-5.6**展示先进模型如何在API级内置工具的支持下，在服务器端闭合“搜索-阅读-分析”的编排循环，用于深度研究。GPT-5.6有三个变体——Sol（旗舰前沿模型）、Terra（日常工作的平衡模型）和Luna（快速、经济的轻量模型），所有变体都将工具调用决策原生留给模型，因此客户端无需自己的编排框架。一个方便的功能是**自由格式工具调用**。传统上，模型调用工具必须将每个参数序列化为严格的JSON（结构化数据格式），很像用严格格式规则填写表格。自由格式工具调用（通过API中类型为`"custom"`的工具声明）允许模型直接将原始文本发送给工具（一段Python代码、一个SQL查询），完全避免JSON转义。值得强调的是，这是API参数格式的演进，而非模型架构的创新——客户端的工具调用循环（检测`tool_calls`→执行→返回结果）保持不变；仅参数从JSON字符串变为原始文本。GPT-5.6还引入了详细程度参数（控制输出细节）和推理努力参数（调整推理深度；Sol添加了最彻底推理时间的最大级别），让开发者根据任务复杂度调整模型行为。
+
+GPT-5.6与Responses API的**网络搜索和代码解释器**内置工具配合，提供深度研究的核心机制：模型可以自主搜索网络获取实时信息并编写代码进行深入分析，实现“搜索→阅读→分析→再次搜索”的迭代研究过程。例如，面对“东盟10国首都之间的最短距离是多少？”这样的问题，GPT-5.6会自动搜索每个首都的地理坐标，然后编写Python代码计算所有首都对之间的大圆距离，最终识别出最近的一对。类似地，在“搜索比特币过去一个月的趋势并进行技术分析”这样的任务中，它可以从多个金融数据源获取实时价格数据，使用专业技术分析库计算移动平均线、相对强弱指数（RSI）、MACD等技术指标，生成可视化图表并提供交易建议。
+
+更重要的是，GPT-5.6在模型层面内化了OpenAI深度研究产品的设计理念，引入了**意图澄清过程**。接到研究请求时，GPT-5.6不会立即执行，而是首先通过一系列问题澄清用户的真实意图。对于“搜索比特币过去一个月的趋势并进行技术分析”，它会首先询问：“您偏好哪个数据源？您想分析哪些技术指标？”这种交互式澄清让GPT-5.6能生成更精确且更符合用户实际需求的研究报告。
+
+GPT-5.6是“模型即代理”的成熟示例——网络搜索、代码解释器和Responses API的其他内置工具在服务器端闭环执行；编排循环从客户端转移到API服务器，简化了客户端实现。模型仍发出标准的工具调用；客户端只是不再需要自己构建“搜索-阅读-分析”的编排框架。其最值得注意的方面是意图澄清机制：模型不是立即执行任务，而是首先确认用户真正需要什么，然后制定研究策略。在执行开始前解决了“用户所说的”和“用户实际想要的”之间的差距。
+
+图1-4展示了“模型即代理”范式下原生工具调用的完整架构，以及Kimi K3和GPT-5.6在实际任务中的ReAct执行过程。
+
+![图1-4：“模型即代理”架构——原生工具调用](images/fig1-4.svg)
+
+## 框架工程：超越模型的竞争力
+到目前为止，你已经了解了代理的核心工作原理：大语言模型在上下文的引导下运行ReAct循环，使用工具完成任务。上述实验表明基本机制可行——但也暴露了其脆弱性。模型可能会幻觉（编造不存在的工具或参数）、选错工具或无法从错误中恢复。从工作演示到可靠产品存在巨大差距，而这些脆弱性正是框架工程要解决的。本章前半部分回答了代理是什么；后半部分回答了代理如何在生产中可靠运行。
+
+前面的章节建立了核心公式：**代理=大语言模型+上下文+工具**。它描述了代理的**内部组成**：推理引擎、工作上下文和行动接口。框架工程为同一系统添加了第二个**实现层面**的视角：将大语言模型视为一个核心组件（模型），将围绕它构建的所有支持代码称为框架。这两个视角不是竞争关系；它们在不同抽象层次描述同一系统。我们切换到更通用的“模型”一词，因为框架工程的原则适用于任何能推理和调用工具的模型，而非特定种类。框架的核心是原始公式中的“上下文+工具”，加上三层保障：**约束**（代理可以和不可以做什么）、**验证**（是否正确完成了事情）和**纠正**（出现错误时如何恢复）。
+
+展开为等式，完整的生产级组成是：
+
+> **代理=大语言模型+[上下文+工具+约束+验证+纠正]=模型+框架**
+
+一个最小化的工作代理仅靠大语言模型、上下文和工具就能运行。要在长期生产工作负载中可靠运行，它还需要三层外部工程层——约束防止越界，验证捕获错误，纠正从失败中恢复。这些层不是事后添加的独立模块；它们是围绕“上下文+工具”的保障。换句话说：最小公式是演示视角，扩展公式是生产视角——后者完全包含前者并在其周围添加安全网。
+
+一个例子阐明边界：将退款政策嵌入上下文中属于**上下文**，而检查退款金额不超过订单总额属于**约束**。执行API调用属于**工具**，而API超时后自动重试属于**纠正**。模型提供底层理解和推理；框架引导、约束并放大这些能力，使其成为可靠的任务执行。在模型之外设计和优化此基础设施的工程实践是**框架工程**。
+
+一个具体例子展示框架的价值。假设你让代理退还用户3天前下的订单。**没有框架**：模型没有收到退款政策（没有上下文），不知道调用哪个API（没有工具），为用户编造退款结果（没有验证），用户发现退款从未发生（没有纠正）。**有框架**：系统提示指定7天退款政策（上下文），代理调用`query_order`和`process_refund`工具执行操作（工具），框架检查退款不超过订单总额（约束），根据数据库确认退款已完成（验证），API调用超时后自动重试（纠正）。同样的模型，结果大不相同。
+
+简而言之，没有框架的模型可能能力很强，但缺乏可靠完成任务所需的周围控制。
+
+更精确地说，模型之外的所有基础设施都属于框架。框架的核心是上下文和工具，围绕它们构建三种工程保障：
+
+| 功能     | 一句话职责                     | 与上下文/工具的关系 |
+|----------|--------------------------------|---------------------|
+| **上下文** | 为模型提供相关信息             | 核心能力            |
+| **工具**   | 为模型提供行动接口             | 核心能力            |
+| **约束**   | 设置行为边界——可以做什么和不可以做什么 | 围绕上下文和工具的安全边界 |
+| **验证**   | 自动判断工具执行结果的正确性   | 围绕工具执行结果的检查机制 |
+| **纠正**   | 发现问题时自动恢复或回滚       | 围绕工具调用失败的恢复机制 |
+
+上下文和工具让代理完成任务——理解任务并采取行动。约束、验证和纠正确保其可靠安全地完成任务——不是脱离上下文和工具，而是作为确保它们在生产中可靠工作的工程。随着代理产品的成熟度曲线，这两组之间的重点发生转移。
+
+早期的代理框架专注于上下文和工具：给模型工具，给它上下文，让它完成任务。生产级系统已将重心转移到约束、验证和纠正：确保工具调用安全，上下文得到管理，错误可恢复。
+
+以Claude Code为例。它的框架代码绝大多数用于约束、验证和纠正，而非上下文和工具——工具本身（文件读写、命令执行、搜索）只是一小部分；围绕它们构建的保障才是真正的核心。这些机制包括：
+
+- **进程状态管理**：跟踪代理当前执行的步骤
+- **多层上下文压缩**：信息过多时自动修剪
+- **权限分类**：控制哪些操作需要用户确认
+- **断路器**：重复错误后自动停止重试，防止一个失败操作级联影响整个系统
+- **错误恢复机制**：捕获异常，回滚到最后稳定状态，重试或移交人类
+
+**行业正在从任务完成转向可靠任务完成，使框架工程成为代理系统的核心竞争力。**
+
+### 从提示工程到循环工程：工程范式的演进
+回顾人工智能应用工程的发展，出现了清晰的演进弧线：
+
+**软件工程**是基础——传统系统设计、架构、测试和部署。**提示工程**是第一波创新——通过优化喂给模型的自然语言指令提高输出质量。**上下文工程**是第二波——意识到仅优化提示词不够：模型的工作上下文（系统指令、工具定义、对话历史、外部知识）必须系统管理。**框架工程**是第三波——将视角从“模型接收什么信息”拓宽到“模型运行在什么样的系统中”，纳入模型之外的所有基础设施：约束机制、验证方法、反馈循环、错误恢复。**循环工程**紧随其后，将视角从单次运行拓宽到跨运行的持续自主操作：谁发现下一个工作，何时验证，何时任务才算真正完成（第10章与多代理协作系统一起展开）。
+
+2026年7月，行业开始使用**图工程**从更高层次的编排视角：将代理循环、确定性程序和人类审批组织成显式的执行图，其中节点提供能力，边定义路由和依赖，结构化状态沿边传递并在关键边界持久化[^ch1-graph-engineering]。图工程不是循环工程的替代，也不应简单视为上述演进中的“第六层”。循环本身就是带有回边的图，图中的节点仍可在内部运行ReAct或其他代理循环。名称尚未稳定，因此本书将其视为现有编排和框架实践的新兴术语；第10章展开多代理部分。这里的“图”指控制流或执行图，而非GraphRAG使用的知识图。
+
+[^ch1-graph-engineering]: 乔希·C·西蒙斯在2026年7月4日的文章《我们进入图工程阶段》中明确使用了该名称，用节点、类型化边和检查点状态进行总结。7月18日，彼得·施泰因贝格尔关于讨论是否从循环转向图的问题进一步推动了该名称的传播。这些实践早于标签出现：LangGraph、微软代理框架和谷歌ADK的官方文档将它们描述为图编排或基于图的工作流。见https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase，https://x.com/steipete/status/2078277297791189132，https://docs.langchain.com/oss/python/langgraph/overview，https://learn.microsoft.com/en-us/agent-framework/workflows/，以及https://adk.dev/workflows/。
+
+这五个阶段不是替代关系，而是嵌套层：提示工程是上下文工程的子集，上下文工程是框架工程的子集，框架工程是循环工程的子集。每层都拓宽了工程师的关注点和影响力范围。**随着模型能力趋同且不再是决定性差异因素，竞争优势转移到模型之外的工程上。** 最近的工程实践支持这一观点。LangChain在Terminal Bench 2.0（评估代理在终端环境中完成复杂任务能力的基准）上的工作是一个显著示例：他们的编码代理从52.8%提高到66.5%（从排行榜前30名外跃升至前5名）。改变的不是模型，而是框架——让代理检查自己的执行结果，检测何时陷入重复循环，并完善其推理策略。OpenAI的工程团队分享了类似经验：3名工程师在5个月内完成了约100万行代码和近1500个PR，约为传统开发速度的10倍。主要驱动力不是更强的模型；而是正确的框架。
+
+### 框架五大功能的核心原则
+前面的表格列出了框架的五大功能。下表添加了每个功能的核心设计原则及本书的处理位置，将概念映射到实践：
+
+| 功能     | 核心原则                     | 实践示例                     | 见章   |
+|----------|------------------------------|------------------------------|--------|
+| **上下文** | 信息充足：确保代理在每个决策点基于充足信息做决策 | 系统提示、知识库、代理状态栏、Sidecar旁路查询 | 第2章&第3章 |
+| **工具**   | 接口清晰：工具名称直观，参数有示例，边界有说明 | MCP工具、代码解释器、搜索工具 | 第4章  |
+| **约束**   | 故障安全默认：所有能力默认关闭，必须显式启用（类似移动应用权限管理） | 在Claude Code中，每个工具默认执行前需用户授权 | 第4章  |
+| **验证**   | 输入隔离：安全检查仅查看工具返回的结构化数据（如JSON字段），不查看模型生成的自由格式文本（因为攻击者可能通过提示注入操纵模型输出） | 林特检查、类型系统、工具调用结果验证 | 第5章&第6章 |
+| **纠正**   | 未确认不可恢复前不暴露中间状态（例如静默重试失败的工具调用，而非向用户显示半成品结果） | 静默重试、续生生成、连续失败后移交人类判断（断路器机制） | 第2章&第5章 |
+
+五大功能形成闭环：上下文和工具支持决策，约束防止错误，验证检测偏差，纠正闭合循环。任何环节缺失都会导致系统出现可靠性缺口。在检查具体编排模式和护栏设计之前，我们首先列出构建有效代理的核心原则和选择模型的原则——这是后续所有设计决策的基础。
+
+### 构建有效代理的核心原则
+基于Anthropic的经验，成功的代理系统遵循三个核心原则。
+
+**保持简单。** 从最简单的解决方案开始，仅在真正必要时添加复杂性。直接API调用优于复杂框架；清晰代码优于巧妙抽象——每个额外的抽象层都是调试时的新盲点。
+
+**保持透明。** 清晰展示代理的规划步骤、执行日志和决策轨迹。这不仅是调试便利；更是用户信任的前提——黑盒内的错误难以从外部定位或修复。
+
+**设计良好结构的工具接口（ACI，代理-计算机接口）。** ACI意味着从代理的角度设计接口——便于代理理解和使用，而非传统API中的程序员视角。工具名称和参数应直观，在可能滥用的地方应从一开始就设计得不可能出错：SIM卡的缺口使其只能以一种方向滑入托盘，微波炉门打开时拒绝加热。制造业将此称为“消除错误”理念**防错法**（Poka-yoke），源自丰田生产系统。设计不佳的工具会导致即使最强的模型也反复失败：接口是模型和工具之间的唯一通道，模糊的接口会放大为系统性错误。
+
+接下来的三个部分讨论框架工程中三个独立但重要的主题：模型选择、编排模式、护栏和安全。它们不属于五大框架元素本身，但在工程实践中不可避免。
+
+### 如何选择模型
+在讨论编排模式之前，我们首先需要回答一个实际问题：哪种模型应该驱动你的代理？
+
+模型是代理智能的基础，选择合适的模型往往比任何提示调整都重要。模型发布速度太快，具体版本推荐难以保持有用，因此本节提供方向而非具体推荐。