1
2
3
- 最初做笔记是在2026.8.23开始,时隔两个月于2026.10.23重启。
- 本阅读笔记是根据《深入理解 AI Agent:设计原理与工程实践》(李博杰 著)此书来用于个人学习。
- GitHub仓库:https://github.com/bojieli/ai-agent-book

AI Agent入门

Agent = LLM + 上下文 + 工具

我们将Agent看作一个人的话,LLM就是大脑(负责决策和思考),上下文就是眼睛(接受环境提供的观察),工具就是手脚(将决策转化为作用于环境的行动)。

Agent = 大脑 + 眼睛 + 手脚

LLM:大语言模型(Large Language Model)。LLM是Agent的决策内核,就像人脑一样起到一个理解意图、思考规划、做出判断的作用。其能力来自预训练积累的世界知识与语言能力,及后训练(监督微调与强化学习等技术)固化的决策策略。

上下文:Agent在每个决策点收到并保留的信息表示(包括来自环境的观察、用户记忆、领域知识、自身状态和任务进展)。

工具:Agent感知或改变世界的接口,包括工具定义、调用协议和适配器。

1
2
- 环境状态也可以被读取、筛选并编码进上下文,上下文≠环境。
- 工具背后的文件系统、数据库、网页、用户或物理世界也仍属于环境。

Agent的最小交互结构:

  • 在经典的强化学习和控制论视角下,Agent与Environment是闭环交互的两方,彼此独立。

    • 循环过程:
      1、环境向Agent返回当前观察
      2、Agent根据已有上下文进行下一步行动
      3、行动改变环境状态
      4、新状态产生下一次观察、
      5、循环继续进行

      1
      2
      - 环境包括:文件、数据库、网页、用户、其他 Agent、物理或仿真世界
      - Agent通过观察接口和行动接口与环境交互
  • 两个抽象层次:

    • 外层 Agent <-> Environment

    • 内层 Model-Harness

      1
      2
      3
      4
      5
      6
      - Model负责决策。
      - Harness:Agent边界内环绕模型的运行与治理层。
      - 构造上下文
      - 暴露接口工具
      - 维护循环和状态
      - 实施权限、验证与纠正

综上,Agent = LLM + 上下文 + 工具 此公式可展开为: LLM 对应Model,而 上下文 + 工具 构成最小Harness;生产系统中,会在Harness中加入约束、验证和纠正。

观察空间与动作空间

观察通道与动作接口构成了Agent与外部环境之间的边界。

模型固定时,Agent任务表现的提升是重新定义或扩展观察空间与动作空间(即扩展上下文和工具)。

Harness构造上下文 -> 模型处理 -> 模型选择行动 -> 调用工具影响环境

Manus将 Deep Research(深度调研)、Coding(代码生成)和 Computer Use(电脑操控)三条相对独立的路线合并,使同一个Agent拥有了更大的观察空间与动作空间,从而使得同一个Agent能跨越原有产品边界完成任务。

OpenClaw本地优先。数字文件由用户进行授权,进入同一个Agent的观察空间。OpenClaw相比于早期以隔离云端沙盒为中心的Manus,无需上传文件或额外配置连接器。OpenClaw把接口延伸到了用户的数字生活中,把观察空间和动作空间向外推进了一层。

(感觉网页版的DeepSeek就像是早期的Manus,观察空间和动作空间都被限制在了网页,不过应该不是很对。后面去了解一下。)

工具

工具的种类

image-20260901192540407

工具调用的流程(page55)

工具调用(Tool Calling,也叫Function Calling)是现代LLM Agent的一项核心能力,让模型通过结构化方式调用外部工具。这也使得LLM转变为可以执行实际操作的智能系统。

  • 1、在上下文中告诉模型可用的工具(包括名称、用途和参数)
  • 2、模型自主判断是否调用工具、选择哪个工具、传什么参数
  • 3、工具执行完毕,结果追加到上下文中
  • 4、模型据此决定下一步行动

此循环也是ReAct的基础。

LLM

LLM是Agent决策核心,其“理解-规划-执行”的能力表现为:

LLM -> 收到用户请求 -> 解析真实意图 -> 将任务拆解为可执行的步骤 -> 执行过程中还需持续做出判断(下一步该做什么、是否调用工具、调用哪个工具、传什么参数)

LLM Agent具有内部思考的独特能力。即Agent在实际行动前,先进行规划与推演。

1
2
- “理解-规划-执行”的能力是工作流和自主Agent的基础,来自预训练积累的知识。
- LLM能进行有效的内部推演也得益于预训练,模型推演遵循的是人类知识中沉淀下来的逻辑规则(数学定律、因果关系、问题分解策略等)。

模型即Agent:模型通过后训练(强化学习)将工具调用能力内化为原生能力,自主决策工具调用。

Harness是用来引导模型能够可靠执行任务,Harness应该同模型协同优化,持续迭代,减少模型出错时所造成的影响。 Harness是对模型尚未内化能力部分的兜底约束,倘若模型已将某能力彻底内化,那么Harness则会转去兜底新的能力前沿。

Agent的学习机制:上下文适应 -> 持久更新。

  • **任务内上下文适应。**示例、状态和检索结果进入上下文后,影响模型调整行为,但不影响下次绘画的持久状态。

  • **外部产物更新。**知识文档、 Prompt 或 Skill、程序和 Harness。这些外部产物可审计、可修订,执行时Agent通过上下文或工具接口使用。

  • 模型参数更新。参数更新能够形成自然、广泛的泛化能力。

1
2
- Tool是Agent可以调用的具体函数、API脚本。只负责“执行”,不负责“思考”。
- Skill是一套结构化的完整流程,告诉 Agent:在什么场景下,按照什么步骤,以什么参数去调用哪些工具。

上下文

调用LLM时的上下文由以下五个部分构成:

  • 系统提示词(System Prompt):由开发者编写,整个对话过程中保持不变。定义Agent的身份、权限和行为准则。
  • 工具定义(Tool Definitions):声明 Agent 可用工具的名称、功能描述和参数格式。
  • 用户消息(User Messages):来自用户的输入。
  • 模型回复(Assistant Messages):模型之前生成的回复,最多包含三个部分,即思考过程(reasoning)、文本内容(content)、工具调用请求(tool_calls)。
  • 工具执行结果(Tool Results):Agent框架执行工具后返回的结果。
1
2
3
4
5
6
7
8
9
10
11
- 系统提示词中还会包含跨会话保存的用户记忆(用户偏好、历史行为、背景设定等个性化信息)
- 没有工具定义,Agent就无法识别和调用任何工具。
- 用户消息中还可能包含通过RAG检索引入的外部知识。(覆盖训练数据截至后的 信息 or 私有领域知识)
- 模型回复的三个部分
- 思考过程,即内部思考链,保持思维连贯性和决策可解释性
- 文本内容,即对用户的回复
- 工具调用请求,即Agent采取行动的方式
- 模型回复的三个部分不一定同时出现
- Agent决定调用工具时,通常只有reasoning + tool_calls
- Agent给出最终回答时,通常只有 reasoning + content
- 工具执行结果是Agent下一步思考的依据,也可以使它从执行结果中学习、避免重复犯错

ReAct循环

ReAct = Reasoning + Acting

ReAct实际循环(想→做→看→想→做→看):模型思考当前应该做什么 -> 调用工具行动 -> 观察工具返回的结果 -> 继续思考下一步

1
2
3
- Agent轨迹是在执行任务过程中不断积累的消息历史(用户消息、模型回复、工具执行结果)
- 静态前缀 = 系统提示词 + 工具定义
- Agent的上下文 = 静态前缀 + 轨迹

Harness工程(能做事 -> 做事可靠)

1
2
3
4
5
以Harness工程视角看:
- LLM为Model
- Harness:Agent边界负责支撑模型运行、并中介模型与环境交互的代码、配置和服务

Harness工程原则适用于任何具备推理和工具调用能力的模型

生产形态下方程式可展开为:

1
2
3
- Agent = Model + Harness
- Harness = 上下文管理(核心能力) + 工具接口(核心能力) + 约束(上下文和工具构建的安全边界) + 验证(工具执行结果构建的检查机制) + 纠正(工具调用失败构建的恢复机制)
- Agent <-> Environment
  • Harness的五项职责(功能)及其核心原则:
功能 核心原则 例子
上下文 信息充分性:让 Agent 在每个决策点都基于足够的信息判断 系统提示词、知识库、Agent 状态栏、Sidecar 旁路查询
工具 接口清晰:工具命名直观、参数有例子、边界有说明 MCP 工具、代码解释器、搜索工具
约束 故障安全默认值:所有能力默认关闭,必须显式开放(类似手机 App 权限管理) Claude Code 中每个工具默认需要用户授权才能执行
验证 输入隔离:安全检查只看结构化数据(如工具返回的 JSON 字段),而不是模型自由生成的文本(因为攻击者可能通过提示注入操纵模型输出) Linter 检查、类型系统、工具调用结果校验
纠正 在确认无法恢复之前,不暴露中间态(例如工具调用失败时先静默重试,不将半成品结果展示给用户) 静默重试、接续生成、连续失败时回退到人工判断(熔断机制)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
补充:
- 上下文
- 知识库:外部存储的私有数据或文档集合
- Agent状态栏:Agent执行任务时,实时显示当前进度的区域
- Sidecar旁路查询:在主对话流程之外,并行发起的独立信息查询
- 工具
- MCP工具:MCP(模型上下文协议)是一种标准化的工具接入协议
- 代码解释器:AI能够实际编写并运行代码的沙箱环境
- 搜索工具:AI联网或检索内部数据能力的接口,一般是搜索引擎api或者企业内部搜索系统
- 验证
- Linter检查:一种静态代码分析工具,用于检查代码中的语法错误、风格问题或潜在Bug。(不运行代码)
- 类型系统:编程语言中对数据类型(如整数、字符串)的校验机制。确保函数传入的参数和返回值符合预期类型,防止程序崩溃。
- 纠正
- 静默重试:调用工具/api时因网络波动失败,系统后台自动重试几次。(用户感知不到)
- 持续生成:ai输出回答时,如果因字数/网络而截断,系统会自动补全剩余的上下文。
- 熔断机制:多次静默重试失败,系统停止操作。
1
2
3
4
5
6
Harness中围绕工具构建的保障机制:
- 流程状态管理:追踪 Agent 当前执行到哪一步
- 多层上下文压缩:当信息太多时自动精简
- 权限分类:控制哪些操作需要用户确认
- 熔断器(Circuit Breaker):当错误连续发生时自动“断电”停止重试,防止整个系统崩溃
- 错误恢复机制:捕获异常、回滚到上一稳定状态、重试或交还给人类

Harness是Agent边界内、模型之外的运行与治理层。

工程范式的演进

image-20260906200933213

1
2
3
4
5
- 提示工程:通过优化输入的自然语言指令来提升输出质量
- 上下文工程:系统管理模型能看到的所有信息(系统指令、工具定义、对话历史、外部知识)
- Harness工程:“Agent 如何组织模型运行并与环境交互”,涵盖上下文与工具接口、约束机制、验证手段、反馈循环和错误恢复等 Agent 边界内、模型之外的运行与治理机制。
- Loop工程:跨轮次的持续自主运转:谁来发现下一件该做的事、何时验证、何时才算真正完成。
- Graph工程:把 Agent 循环、确定性程序和人工审批组织成显式的执行图,其中节点承担具体能力,边规定路由与依赖,结构化状态沿边传递并在关键边界处持久化

Agent系统的核心原则

  • 保持简单
  • 保持透明
  • 设计好工具接口(ACI,Agent-Computer Interface):强调从Agent视角设计接口,让Agent容易理解和使用。

Agent选择模型

  • 考虑模型的能力
  • 考虑模型的策略边界
  • 支持思考(Reasoning)的模型
  • 关注输出速度与多模态能力

编排模式

编排模式是Harness中上下文与工具层面的组织方式——决定了上下文如何在 LLM 调用之间流动、工具如何被调度、以及 Agent 的执行路径是预先设定还是动态生成。

确定性的编排

即工作流模式。通过预定义的代码路径编排LLM和工具的系统。执行路径是确定性的,由开发者预先设计好,LLM只在每个节点内部负责理解和生成。

动态自主决策

即自主Agent(适用开放式的问题)。自主Agent的执行路径是Agent根据环境反馈实时决定的。

但自主Agent必须设计明确的停止条件(任务完成、达到最大迭代次数或遭遇不可恢复的错误),否则 Agent 容易陷入死循环或过度执行。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
自主Agent的循环
- 思考(Reasoning)
- 行动(Acting)
- 观察(Observing)
- 判断是否满足退出条件?
- 满足 --> 输出最终结果
- 不满足 --> 继续下一轮循环从思考开始

退出条件(任一满足即可退出):
- 任务完成
- 调用final_answer
- 无工具调用返回
- 错误次数超限
- 达到最大轮次

补充:
- final_answer 是一个专门用来“终止循环并正式交付结果”的特殊工具(函数)。

n8n框架

n8n 是一个成熟的工作流自动化开源框架,开发者通过可视化界面拖拽功能组件来构建 Agent,可以在同一个系统中同时使用工作流节点和自主 Agent 节点。

(留着之后单独去了解学习吧)

主流框架对比

对比表格见page95。

上下文工程

上下文的质量决定Agent能力的真正关键

消息的四种角色

  • system:系统提示词。开发者编写,定义Agent的身份、行为准则、约束条件。模型将其视为最高优先级指令。
  • user:用户消息。Agent需要响应的请求。
  • assistant:助手消息。之前的assitant消息会被放回消息列表,让模型记住自己说过什么。
  • tool:工具结果。

单轮对话与带工具调用的多轮交互

单轮对话:

image-20260908210023358

带工具调用的多轮交互:

image-20260908210204094

API层面上的Agent

api视角上的上下文构成

image-20260908210754550

ReAct在api层面上的实现

请求→工具调用→执行→送回结果→再请求”

KV Cache

KV Cache将前文所有token的中间计算结果缓存下来,下一轮只需计算新增token的部分。(前提:复用的上下文token前缀保持不变)

三条核心结论:

1、系统提示词和工具定义一旦确定就不要修改

2、动态信息永远追加到末尾

3、使用标准API格式,不要自行拼接消息

LLM在处理上下文时,会把前面已经处理过的内容缓存起来,下次只需要处理新增的部分。

Chat Template:API消息 –> 模型token

api的结构化消息需要被转换为模型可以理解的token流

image-20260916193049364

原理与约束

复用机制

image-20260916193444707

KV Cache与Prompt Cache

KV Cache 是模型内部的机制

Prompt Cache 则是推理引擎的优化

Prompt Cache 的工作方式是:API 服务商对请求的前缀进行匹配,如果多次请求的前缀相同,就直接复用之前计算好的 KV Cache,而不需要重新计算这部分 token 的键值对。

提示工程

语气与风格:系统提示词的“人格”:

例如,“You MUST answer concisely with fewer than 4 lines”(你必须简洁地回答,不超过 4 行)

在无法完成任务时要求 “keep your response to 1-2 sentences”(把回复控制在 1-2 句话),并且“不要解释为什么不能做某事”——这种设计避免了 Agent 陷入冗长的自我辩护。

“NEVER do X” 比 “Please avoid doing X” 更能引起模型注意,但如果满篇都是这种大写单词,Model分不清哪条重要,会造成效果稀释。

结构化提示:系统提示词的“格式”:

LLM对结构化输入及其敏感。XML标签使用遵循层次化原则,标签名携带语义信息。

例如,<working_directory>能直接告诉Model,这是工作目录的信息。

系统提示词的“组织方式”

流程驱动 VS 规则堆砌:

如果只是给出零散规则的手册,没有流程图,也没有优先级说明,会造成多条规则同时适用时该如何选择?规则未覆盖的情况又该如何处理?的疑惑。

而流程驱动的提示词,提供了清晰的标准操作流程(SOP):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
File Processing Standard Operating Procedure:

Step 1: Validation
Check if file exists and is accessible
- If not found → log error and stop
↓
Step 2: Classification
Determine file type based on extension and content
↓
Step 3: Preprocessing
Config files → create backup
Large files (>1MB) → stream processing
↓
Step 4: Execution
Execute core processing logic based on file type
↓
Step 5: Verification
Ensure integrity of the processed file

能够让模型知道自己的位置、当前步骤的目标、完成后进入哪个步骤。同时,方便确定异常的处理方式。

业务规则细化:系统提示词的“内容”

0x04. 工具

a. 分类:

  • 感知工具

    • 调用方向:Agent主动调用
    • 作用对象:获取信息
  • 执行工具

    • 调用方向:Agent主动调用
    • 作用对象:改变世界
  • 协作工具

    • 调用方向:Agent主动调用
    • 作用对象:驱动其他 Agent 或人类
  • 事件触发工具

    • 调用方向:Agent 注册、外部触发
    • 驱动 Agent 开始执行
  • 用户沟通工具

    • 调用方向:Agent主动调用
    • 作用对象:向用户传递信息

b. 工具设计的通用原则

能力表达形式的选择

Agent 能力的两种基本表达形态:

  • 专用代码工具
    • 结构化的函数调用,确定性高、可测试。
  • Skill + 通用执行器
    • 用自然语言编写的 Skill 文档来描述操作流程,Agent 通过终端或代码解释器来执行

选择哪种形态由三个维度决定:

  • 参数复杂度:涉及嵌套对象、多字段联合校验、复杂类型约束的操作,专用工具的结构化 schema 能更好地引导模型正确传参
  • 变更频率:频繁变化的能力用 Skill 来维护,成本远低于专用工具
  • 模型能力:SOTA 模型可以用 Skill + 通用执行器的方式表达更多能力、减少工具数量;较弱的模型则需要结构化的工具 schema 来引导正确调用

工具粒度的权衡:

工具划分的太细会导致工具数量激增,不利于 LLM 选择;而工具划分的太粗会导致单个工具过于复杂。

  • 工具整合的核心标准:功能相似性 和 使用场景 的重叠度
    • 以文档处理为例子:假如存在doc、pdf、pptx等文件的提取文本的工具,如果划分的很细那么此时就会分为doc、pdf、pptx这三个工具,数量增多,给 LLM 也会造成负担。假如我们把这三个文件处理的工具函数整合成一个工具函数,只是在函数入口增加一个形参 file_type 那么则会降低 LLM 的负担。

工具的通用性设计

通用工具优于专用工具,除非存在明确的安全、权限或性能理由。

LLM 本身具有强大的思考和代码生成能录,我们应该利用这种能力而不是限制。

通用性的边界:需要特殊权限、复杂配置、有安全风险的操作。封装良好的专用工具仍然是必要的。

工具描述

工具描述的质量直接决定 Agent 使用工具的准确性。

  • 清晰列出工具的边界条件
  • 参数描述应该用具体的例子代替抽象的规范
  • 返回值需要描述清楚
  • 更进一步的做法是为每一个工具附带 1-5 个真实的调用示例

实用的调试原则:当 Agent 频繁选错工具时,应优先检查工具描述而不是怀疑模型能力。

参数传递的保真性

保真性违规:

  • 静默输入转换

    • 工具在执行前悄悄修正模型的输入参数,导致实际操作偏离了模型的意图
  • 静默参数注入

    • 工具在模型不知情的情况下向命令追加额外的参数

更为基础的工具设计原则:模型感知到的世界与工具操作的世界之间,不能存在系统性的偏差

工具设计的演进

  • 直接的 API 封装

    • 将每个 API 端点对应一个工具,粒度过细,Agent 往往需要协调多个工具才能完成一个目标
  • ACI (Agent-Computer Interface) 原则

    • 工具应该对应 Agent 的目标而非底层的 API 操作,上文的粒度权衡、通用性设计、描述规范都属于这一阶段
  • 在单个工具设计上,进一步优化工具被调用、串联和发现的方式,分别回答 “工具如何被准确调用”(示例驱动)、“工具如何被发现”(动态工具发现)、“工具如何被串联”(代码编排执行)