Wiki Notes

Appearance

AI Agents 详细学习资料 ​

版本：v1.0

最后更新：2026-07-01

适用对象：希望系统学习 AI Agent 理论、工程实现、工作流设计、评测、安全与项目落地的学习者

1. 这份资料适合谁 ​

这份资料适合三类人：

  • 已经会调用大模型 API，但还不清楚 Agent 到底是什么的人
  • 会做简单 LLM 应用，但不知道如何把“问答”升级成“可执行系统”的人
  • 想做 AI Agent 项目、写知识库、求职面试或搭建企业内部 Agent 的人

这份资料的目标不是让你“会几个框架名”，而是让你建立下面这套能力：

  1. 能清楚解释什么是 Agent，什么不算 Agent。
  2. 能判断什么时候该用工作流，什么时候才该引入 Agent。
  3. 能设计一个可控、可测、可维护的 Agent 系统。
  4. 能从 Demo 走到真实项目。

2. 先建立一个正确预期 ​

学习 Agent 最容易踩的坑，不是技术不够，而是预期错了。

你要先接受 4 个事实：

  1. Agent 不是“让模型自己思考得更久”这么简单。
  2. Agent 的难点不只是 Prompt，而是 工具设计 + 状态管理 + 评测 + 安全。
  3. 很多问题并不需要 Agent，固定工作流往往更稳。
  4. 一个能上线的 Agent，通常更像“有模型参与的系统工程”，而不是“一个聪明的对话机器人”。

3. 什么是 AI Agent ​

一个足够实用的定义是：

  • AI Agent 是一个以 目标 为中心，能够 理解上下文、调用外部工具、根据反馈继续执行、并在必要时 维护状态与记忆 的智能系统。

你可以把它理解成“会推理的调度器 + 会调用工具的执行者 + 会根据结果调整策略的控制循环”。

3.1 Agent 和普通 LLM 应用的区别 ​

普通 LLM 应用常见形态：

  • 用户输入问题
  • 模型生成回答
  • 应用展示结果

Agent 常见形态：

  • 用户给出目标
  • 系统判断是否需要查询、调用 API、读文件、执行代码、访问数据库
  • 系统分步执行
  • 根据工具结果决定下一步动作
  • 最终返回结果或继续循环

3.2 什么不算 Agent ​

以下场景通常不必称为 Agent：

  • 单次总结
  • 单次改写
  • 结构化抽取
  • 文本分类
  • 普通聊天机器人
  • 固定步骤、没有动态决策的脚本

3.3 一个简单判断规则 ​

如果你的问题可以被下面这套流程稳定解决：

  • 单次模型调用 + 少量业务代码

那就优先不要上复杂 Agent 架构。

根据 2026-07-01 可访问的 OpenAI 官方文档：

  • 当 单次调用 + tools + 应用侧编排 足够时，优先考虑 Responses API
  • 当你需要更完整地处理 状态、编排、审批、多步骤运行 时，再考虑 Agents SDK

4. Agent 的核心思维模型 ​

学习 Agent 时，不要一开始就把注意力放在框架 API 上。先把思维模型吃透，后面学任何框架都会轻松很多。

4.1 Goal → Plan → Act → Observe → Update → Finish ​

几乎所有 Agent 都能被抽象成这 6 步：

  1. Goal
    • 目标是什么？
  2. Plan
    • 下一步该做什么？
  3. Act
    • 是否需要调用工具？
  4. Observe
    • 工具返回了什么？
  5. Update
    • 当前状态要如何更新？
  6. Finish
    • 任务是否已经完成？

4.2 Thought-Action-Observation ​

很多 Agent 框架背后都能映射到类似的循环：

  • Thought：下一步要做什么
  • Action：调用哪个工具
  • Observation：工具返回什么

即便你不显式输出“思维链”，这个结构依然存在。

4.3 Agent 不是“无限自主” ​

真正可用的 Agent 一般都被强约束：

  • 允许调用哪些工具
  • 每次最多走几步
  • 什么时候必须人工确认
  • 哪些数据不能访问
  • 哪些结果必须结构化输出

所以，好的 Agent 设计往往不是“尽量放手”，而是“在关键位置做控制”。

5. Agent 的核心组成 ​

5.1 模型 ​

模型负责：

  • 理解目标
  • 做局部决策
  • 选择工具
  • 生成参数
  • 综合结果

你需要关注的不是抽象地说“模型越强越好”，而是：

  • 工具调用能力
  • 结构化输出稳定性
  • 延迟
  • 成本
  • 长上下文能力
  • 是否擅长规划或摘要

5.2 工具 ​

工具是 Agent 连接真实世界的桥梁。

常见工具类型：

  • 搜索工具
  • 网页浏览工具
  • 文件读写工具
  • 数据库查询工具
  • 企业业务 API
  • 代码执行工具
  • 文档系统工具
  • 邮件、日历、CRM、工单系统工具

一个好工具通常有这些特征：

  • 名字清晰
  • 描述准确
  • 参数少而精
  • 输入输出稳定
  • 错误信息对模型友好
  • 副作用边界清楚

工具设计的一个关键原则 ​

不要把一个工具做成“万能函数”。

更好的方式通常是：

  • 把高风险操作拆成多个小工具
  • 把查询和修改分开
  • 把读取和执行分开

这样更容易加权限控制、审批和日志。

5.3 状态 ​

状态是 Agent 在执行过程中“当前知道什么”的集合。

例如：

  • 当前任务 ID
  • 已完成步骤
  • 已查询的结果
  • 当前审批状态
  • 当前轮次
  • 失败原因

如果没有状态，复杂 Agent 很快就会失控。

5.4 记忆 ​

记忆通常分为两种：

  • 短期记忆
    • 当前任务执行过程中要保留的信息
  • 长期记忆
    • 跨任务保存的偏好、事实、历史和画像

根据 2026-07-01 可访问的 LangGraph 官方文档：

  • checkpoints 更偏向任务运行中的持续状态
  • stores 更偏向长期、跨线程的数据保存

即使你不用 LangGraph，这种区分方式也非常值得借鉴。

5.5 规划 ​

规划不是必须先输出一张大计划表。

它可以是：

  • 是否要调用工具
  • 要先查什么
  • 要不要把任务交给别的节点或子系统
  • 如果失败是重试、降级还是终止

5.6 执行器 ​

执行器是让 Agent 真正“跑起来”的部分。

它通常要负责：

  • 驱动循环
  • 管理状态
  • 调用工具
  • 处理异常
  • 记录 trace
  • 判断结束条件

5.7 护栏 ​

护栏是生产级 Agent 的必修课。

护栏常见做法：

  • 人工审批
  • 工具白名单
  • 输入输出校验
  • 角色权限
  • 成本上限
  • 步数上限
  • 超时终止
  • 结果置信度校验

6. Agent 常见架构模式 ​

6.1 单 Agent + Tools ​

最简单，也最值得先学。

特点：

  • 一个 Agent
  • 若干工具
  • 简单循环

适合：

  • 搜索总结
  • 文档问答
  • 数据查询助手

6.2 Router 模式 ​

一个入口把请求路由到不同处理路径。

适合：

  • 请求类型差异很大
  • 每条路径都相对稳定

例如：

  • 售前问题 → FAQ 路线
  • 售后问题 → 工单路线
  • 技术问题 → 代码/文档路线

6.3 Planner-Executor ​

先规划，再执行。

适合：

  • 任务复杂
  • 需要拆步骤
  • 步骤之间依赖明显

6.4 Reviewer / Critic 模式 ​

一个模块产出结果，另一个模块负责审查。

适合：

  • 输出质量要求高
  • 风险较大
  • 需要纠错

6.5 Multi-Agent ​

多个 Agent 分工协作。

常见角色：

  • 研究员
  • 分析员
  • 写作者
  • 审核员

优点：

  • 角色边界清晰

缺点：

  • 成本高
  • 延迟高
  • 难调试
  • 容易出现“看上去很复杂但收益不明显”

新手建议：

  • 先学单 Agent 和工作流
  • 再考虑多 Agent

6.6 Graph / Stateful Workflow ​

任务被建模成显式状态图。

适合：

  • 长时间运行
  • 状态复杂
  • 需要暂停恢复
  • 需要人工介入
  • 需要稳定重试

根据 2026-07-01 可访问的 LangGraph 官方文档，LangGraph 的重点就是为这类 stateful, long-running 的工作流和 Agent 提供基础设施。

7. Agent 学习中最重要的 8 个能力 ​

能力 1：结构化输出 ​

你必须学会：

  • JSON 输出
  • schema 约束
  • 字段校验
  • 异常兜底

因为没有结构化输出，后面的工具调用、工作流分支、评测都会很痛苦。

能力 2：工具调用 ​

你必须学会：

  • 如何描述工具
  • 如何设计参数
  • 如何处理错误
  • 如何控制副作用

能力 3：任务拆解 ​

你必须学会：

  • 把业务问题变成步骤
  • 区分“模型决定”和“代码决定”
  • 找出确定性步骤和非确定性步骤

能力 4：状态管理 ​

你必须学会：

  • 当前运行状态怎么存
  • 中间结果怎么存
  • 暂停恢复怎么做
  • 失败重试怎么记录

能力 5：检索与上下文工程 ​

你必须学会：

  • 文档切分
  • 检索
  • 上下文拼接
  • 历史压缩
  • 引用来源

能力 6：评测 ​

你必须学会：

  • 构造测试集
  • 定义成功标准
  • 跟踪失败样本
  • 做回归测试

能力 7：可观测性 ​

你必须学会：

  • 看 trace
  • 看每步输入输出
  • 看工具调用链
  • 定位失败是模型问题、工具问题还是状态问题

能力 8：安全与权限 ​

你必须学会：

  • 限制高风险工具
  • 做审批
  • 做越权防护
  • 做审计日志

8. 一个实用的学习顺序 ​

建议严格按下面顺序学，不要跳：

  1. 普通 LLM 调用
  2. 结构化输出
  3. 单工具调用
  4. 多工具调用
  5. 简单循环 Agent
  6. Router / Planner-Executor
  7. 状态持久化
  8. 人工审批
  9. 评测与 trace
  10. 多 Agent 或复杂图工作流

这个顺序的核心原因是：

  • 先解决“能用”
  • 再解决“能控”
  • 最后解决“能稳”

9. 推荐技术栈与选型思路 ​

学习 Agent 时，不建议同时堆太多框架。先选一条主线。

9.1 如果你想从官方能力栈学起 ​

推荐优先级：

  1. Responses API
  2. Tools / Function Calling
  3. Agents SDK
  4. Agent evals / traces / guardrails

适合：

  • 想先吃透 Agent 最核心的官方范式
  • 想避免一上来陷入过重抽象

9.2 如果你更偏工作流工程 ​

推荐优先级：

  1. LangGraph
  2. Persistence
  3. Human-in-the-loop
  4. LangSmith

适合：

  • 想做复杂流程
  • 想显式管理状态
  • 想做可恢复任务

9.3 如果你更偏标准化工具接入 ​

推荐优先级：

  1. MCP
  2. MCP server / tools / resources
  3. 把内部系统封装成可复用能力

适合：

  • 想做企业 Agent
  • 想把外部工具统一接入
  • 想让 Agent 接不同数据源

10. OpenAI、LangGraph、MCP 各自适合学什么 ​

OpenAI 路线适合学什么 ​

  • 工具调用的基本范式
  • 单 Agent 构建方式
  • 结构化输出
  • Agent 执行与评测思路

LangGraph 路线适合学什么 ​

  • 有状态工作流
  • 图式编排
  • 持久化
  • 人工介入
  • 长任务管理

MCP 路线适合学什么 ​

  • Agent 如何标准化连接外部世界
  • 工具与资源接口设计
  • 企业系统能力的统一暴露

最好的学习顺序通常是：

  1. 先学 OpenAI 的工具调用与 Agent 基础
  2. 再学 LangGraph 的状态工作流
  3. 然后理解 MCP 的能力接入标准

11. 一份 12 周详细学习路线 ​

这是一份适合已经有基础 Python 能力、每周可投入 8-12 小时 的学习计划。

第 1 周：Agent 基础概念 ​

学习目标：

  • 能解释 Agent 是什么
  • 能区分 Agent 和普通 LLM 应用

学习内容：

  • Agent 的定义
  • Goal / Plan / Act / Observe 循环
  • 常见架构模式

本周练习：

  • 用自己的话写出“什么时候不该用 Agent”
  • 画一张 Agent 控制循环图

本周产出：

  • 1 份概念笔记

第 2 周：结构化输出与工具描述 ​

学习目标：

  • 让模型稳定返回可用结果

学习内容：

  • JSON 输出
  • schema 设计
  • 工具描述写法
  • 参数校验

本周练习：

  • 为一个天气查询工具写 schema
  • 为一个搜索工具写 schema

本周产出：

  • 2 个可调用工具定义

第 3 周：单工具调用 ​

学习目标：

  • 完成最基础的 tool use

学习内容：

  • 单轮工具调用
  • 工具结果回填
  • 错误处理

本周练习：

  • 做一个“查天气再回答”的 Demo

本周产出：

  • 1 个单工具 Agent Demo

第 4 周：多工具调用 ​

学习目标：

  • 让系统能在多个工具之间做选择

学习内容：

  • 工具路由
  • 参数生成
  • 重试与失败处理

本周练习：

  • 搜索工具 + 网页读取工具
  • 文件检索工具 + 总结工具

本周产出：

  • 1 个多工具问答助手

第 5 周：简单循环 Agent ​

学习目标：

  • 从一次调用升级到多步执行

学习内容：

  • 循环执行
  • 结束条件
  • 步数限制
  • 超时控制

本周练习：

  • 做一个“先搜索，再找依据，再生成总结”的 Agent

本周产出：

  • 1 个带执行循环的 Agent

第 6 周：RAG 与上下文工程 ​

学习目标：

  • 让 Agent 能基于外部知识更稳定回答

学习内容：

  • 文档切分
  • 检索
  • rerank 基础
  • 引用来源

本周练习：

  • 做一个本地文档问答助手

本周产出：

  • 1 个带引用的知识库 Agent

第 7 周：状态与记忆 ​

学习目标：

  • 学会管理会话和任务状态

学习内容：

  • session state
  • checkpoint
  • store
  • 用户偏好和历史记录

本周练习：

  • 为一个 Agent 增加任务状态保存
  • 做暂停后恢复执行

本周产出：

  • 1 个有状态 Demo

第 8 周：Router 与 Planner-Executor ​

学习目标：

  • 学会任务分发和任务分解

学习内容：

  • Router
  • Planner
  • Executor
  • 手工规则与模型决策的边界

本周练习：

  • 做一个“问题分类 + 分路径处理”的助手

本周产出：

  • 1 个 Router 或 Planner 项目

第 9 周：人工审批与护栏 ​

学习目标：

  • 为 Agent 增加可控性

学习内容：

  • 审批节点
  • 敏感工具拦截
  • 输出过滤
  • 角色权限

本周练习：

  • 为“发送邮件”或“写入数据库”类工具增加审批

本周产出：

  • 1 个带人工确认的 Agent

第 10 周：Trace 与评测 ​

学习目标：

  • 建立 Agent 调试能力

学习内容：

  • traces
  • 失败分类
  • 测试集
  • 回归测试

本周练习：

  • 给现有 Agent 做 20 条测试数据
  • 记录失败样本并分类

本周产出：

  • 1 份评测报告

第 11 周：完整项目实现 ​

学习目标：

  • 做一个接近真实业务的 Agent

项目可选：

  • 研究助手
  • 客服助手
  • 工单分流与处理助手
  • 代码解释/修复助手
  • 报告生成助手

本周产出：

  • 1 个完整项目初版

第 12 周：项目打磨与作品集整理 ​

学习目标：

  • 让项目具备展示和复用价值

本周要做：

  • 写 README
  • 补架构图
  • 补评测方法
  • 补已知问题
  • 补安全限制说明

本周产出：

  • 可演示项目
  • 作品集页面或仓库说明

12. 你应该做的 6 个练习项目 ​

项目 1：天气/搜索工具 Agent ​

目标：

  • 学会 schema
  • 学会单工具调用

项目 2：网页研究助手 ​

目标：

  • 学会搜索
  • 学会网页读取
  • 学会多轮整理

项目 3：知识库问答 Agent ​

目标：

  • 学会 RAG
  • 学会引用来源

项目 4：任务路由助手 ​

目标：

  • 学会 Router
  • 学会规则与模型协同

项目 5：审批型 Agent ​

目标：

  • 学会安全设计
  • 学会敏感操作拦截

项目 6：完整业务 Agent ​

目标：

  • 学会状态、工具、护栏、评测和部署的组合使用

13. 怎样判断自己真的学会了 ​

如果你只是“跑通了教程”，其实还不算会。

你至少要能独立回答下面这些问题：

  1. 为什么这个场景需要 Agent，而不是普通工作流？
  2. 哪些步骤应该交给模型决定，哪些应该由代码固定？
  3. 工具的副作用边界是什么？
  4. 如果工具失败，系统应该怎么退化？
  5. 如果用户重复触发高风险操作，系统怎么拦截？
  6. 如何判断 Agent 的质量在提升，而不是只是“看起来更会说”？

14. Agent 评测应该怎么学 ​

Agent 做不好，最常见原因不是模型弱，而是没有评测体系。

14.1 评测什么 ​

常见指标：

  • 任务完成率
  • 工具选择正确率
  • 工具参数正确率
  • 输出格式通过率
  • 引用正确率
  • 人工复核通过率
  • 平均步数
  • 平均成本
  • 平均延迟

14.2 如何做最小评测闭环 ​

从最小可行版本开始：

  1. 先收集 20-50 条真实任务
  2. 每条任务定义“成功标准”
  3. 跑 Agent
  4. 记录失败类型
  5. 改动后重复跑
  6. 比较是否真的变好

14.3 失败样本如何分类 ​

建议按下面分类：

  • 模型理解错误
  • 工具选择错误
  • 工具参数错误
  • 状态管理错误
  • 检索结果不相关
  • 输出结构错误
  • 护栏拦截不当

14.4 一个当前需要注意的时间信息 ​

根据 2026-07-01 可访问的 OpenAI 官方评测文档：

  • OpenAI 仍提供 Agent 评测相关指南
  • 但 Evals platform 已处于弃用流程
  • 文档说明其在 2026-10-31 进入只读
  • 并计划在 2026-11-30 关闭

这意味着你应该重点学习：

  • 评测思路
  • grader 设计
  • traces 分析
  • datasets 组织方式

而不是过度依赖某个即将关闭的平台界面。

15. Agent 安全是必修课 ​

越靠近真实业务，安全越重要。

15.1 常见风险 ​

  • 越权访问内部数据
  • 调用了不该调用的工具
  • 误发邮件、误写数据库、误提交工单
  • 把检索来的错误信息当真
  • 被提示词注入影响

15.2 最常见的控制手段 ​

  • 工具白名单
  • 只读与写入分离
  • 高风险操作审批
  • 角色权限隔离
  • 步数与成本限制
  • 输入清洗
  • 输出格式校验
  • 审计日志

15.3 一条很重要的工程原则 ​

不要让 Agent 直接拥有“无限制写权限”。

更稳的做法是：

  • 先查
  • 再生成建议
  • 最后人工确认执行

16. 学习 Agent 时的常见误区 ​

误区 1：框架越多越强 ​

不是。你更需要的是理解抽象层。

误区 2：多 Agent 一定比单 Agent 高级 ​

不是。复杂度和调试难度通常也会一起上升。

误区 3：只调 Prompt，不看工具和状态 ​

很多 Agent 问题本质上不是 Prompt 问题。

误区 4：没有测试数据就开始频繁改系统 ​

这样最后很难知道系统到底是变好还是变差。

误区 5：忽略人工审批 ​

只要 Agent 连接真实业务系统，审批通常就不是可选项。

17. 推荐资源与阅读顺序 ​

以下资源在 2026-07-01 检查时可访问，优先选择官方与一手文档。

第一层：先读 OpenAI 官方基础能力 ​

推荐阅读顺序：

  1. Quickstart
  2. Tools
  3. Function Calling
  4. Responses API
  5. Agents Guide
  6. Evals

第二层：补 LangGraph 的状态工作流思维 ​

推荐阅读顺序：

  1. Overview
  2. Quickstart
  3. Graph API
  4. Persistence
  5. Human in the loop
  6. LangSmith

第三层：理解 MCP 的工具接入标准 ​

推荐阅读顺序：

  1. MCP Intro
  2. Build an MCP Server
  3. MCP Tools
  4. Docs MCP
  5. Connectors / MCP

第四层：用 Hugging Face 补概念与开源视角 ​

18. 一份建议收藏的术语表 ​

Agent ​

能围绕目标做多步决策和工具调用的系统。

Tool Use ​

模型通过结构化方式请求外部能力。

Function Calling ​

模型返回函数名称和参数，由应用执行对应逻辑。

Workflow ​

由代码明确规定步骤顺序的流程。

Router ​

把请求分类并路由到不同处理链路的组件。

Planner ​

负责把任务拆解成步骤的模块。

Executor ​

负责具体执行任务和工具调用的模块。

Checkpoint ​

任务运行中的持久状态快照。

Store ​

长期保存信息的数据存储层。

Human-in-the-loop ​

把人工审批、人工补充信息、人工确认嵌入执行流程。

Trace ​

一次 Agent 运行的完整过程记录。

Guardrails ​

用于限制行为、校验结果和降低风险的控制机制。

19. 自测题 ​

如果你学完后能回答下面这些问题，说明基础已经比较扎实。

  1. 为什么很多场景应该先用工作流，而不是直接用 Agent？
  2. 工具设计时，为什么要把查询操作和写入操作分开？
  3. 长任务为什么往往需要状态持久化？
  4. 多 Agent 方案为什么容易失控？
  5. 什么是人机协作节点，它通常在什么场景最有价值？
  6. 为什么评测比“再改几个 Prompt”更重要？
  7. MCP 对企业 Agent 的意义是什么？

20. 一份现实可执行的学习节奏 ​

如果你是上班族，推荐这个节奏：

  • 工作日每天 1 小时
    • 20 分钟 读文档
    • 30 分钟 写代码
    • 10 分钟 记笔记
  • 周末 3-4 小时
    • 2 小时 做项目
    • 1 小时 修 bug / 看 trace
    • 1 小时 写复盘

每周都至少交付 1 个东西：

  • 一份笔记
  • 一个 Demo
  • 或一个项目增量

21. 最后给你的学习建议 ​

如果你想真正学会 Agent，不要追求“一次学全”。

最稳的路径永远是：

  1. 先把结构化输出学稳
  2. 再把工具调用学稳
  3. 再做简单循环
  4. 再做状态与审批
  5. 最后做复杂工作流和多 Agent

换句话说：

  • 先学“让模型能动”
  • 再学“让系统可控”
  • 最后学“让产品可靠”

这三个阶段都走通了，你的 Agent 能力才真正成体系。

22. 资源核验说明 ​

本资料中的重点链接已在 2026-07-01 进行可访问性检查，主要来源包括：

  • OpenAI Developer Docs
  • OpenAI Agents SDK 官方文档
  • LangGraph / LangSmith 官方文档
  • Model Context Protocol 官方文档
  • Hugging Face Agents Course

后续维护建议：

  • 每 1-2 个月复查一次 Agent 相关平台变化
  • 对“最新产品形态、平台弃用计划、API 入口”这类信息，优先以官方文档日期为准