Wiki Notes

Appearance

AI Agents 学习文档 ​

版本：v1.0

最后更新：2026-07-01

适用对象：想系统学习 AI Agent 概念、架构设计、工具调用、工作流编排、评测与落地开发的学习者

1. 文档目标 ​

这份文档的目标不是只介绍几个热门框架，而是帮你建立一套完整的 Agent 学习框架：

  1. 先搞清楚什么是 Agent，什么又不算 Agent。
  2. 学会判断什么时候该用工作流，什么时候才需要 Agent。
  3. 理解 Agent 的核心组成：模型、工具、状态、记忆、规划、执行、评测、护栏。
  4. 能独立做出至少 2 个可演示的 Agent 项目。
  5. 建立从 Demo 到生产系统的思维方式。

2. 什么是 AI Agent ​

一个实用的定义是：

  • Agent 是一个以 目标 为中心、能 感知上下文、能 调用工具、能 分步执行、并根据结果继续调整行为的 AI 系统。

从学习角度看，Agent 至少包含以下能力中的大部分：

  • 接收目标，而不是只回答单轮问题
  • 能访问外部能力，例如搜索、数据库、代码执行、API、文件系统
  • 能把任务拆成多个步骤
  • 能基于工具结果继续推理
  • 能保留必要状态，直到任务完成

如果一个系统只有“单次提问 + 单次回答”，通常更接近 LLM 应用，不一定算 Agent。

3. 什么时候该用 Agent ​

很多新手一开始就想“做 Agent”，但实际上有些问题根本不需要。

优先用普通 LLM 应用的场景 ​

  • 一次生成结果就够
  • 没有外部工具调用需求
  • 任务路径稳定、步骤固定
  • 只需要分类、总结、改写、抽取

这类场景通常用：

  • Prompt + 结构化输出
  • 一次模型调用
  • 少量业务逻辑

适合用 Agent 的场景 ​

  • 任务是多步骤的
  • 需要动态选择工具
  • 结果依赖外部环境
  • 执行过程中需要“先查再做”
  • 需要长任务、审批、暂停恢复、人机协作

典型例子：

  • 研究助手
  • 客服工单处理助手
  • 自动化报表生成助手
  • 代码修复/审查助手
  • 企业知识库检索与行动系统

一个非常实用的判断标准 ​

如果 一次模型调用 + 你自己的代码逻辑 就能稳定解决问题，优先不要上复杂 Agent 架构。

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

  • 当 单次模型调用 + 工具 + 应用侧逻辑 已经足够时，优先考虑 Responses API
  • 当应用需要自己管理 编排、工具执行、审批、状态、多轮运行 时，再考虑 Agents SDK

4. Agent 的核心组成 ​

理解 Agent 最重要的不是背框架名，而是先理解结构。

4.1 模型 ​

模型是 Agent 的“推理核心”，负责：

  • 理解用户目标
  • 决定下一步动作
  • 生成工具参数
  • 综合工具结果
  • 输出最终答案

你需要掌握的不是某个模型的全部细节，而是：

  • 模型擅长什么
  • 模型上下文窗口限制
  • 成本与延迟
  • 工具调用能力
  • 结构化输出能力

4.2 工具 ​

工具是 Agent 与外部世界交互的桥梁。

工具常见类型：

  • Web 搜索
  • 文件检索
  • 数据库查询
  • 业务 API
  • 代码执行
  • 浏览器操作
  • 邮件/日历/文档系统

工具设计质量会直接决定 Agent 的可用性。一个优秀工具通常具备：

  • 明确名称
  • 清晰说明
  • 输入输出模式稳定
  • 参数尽量少而准
  • 错误信息可被模型理解

4.3 状态与记忆 ​

很多人会把“上下文”与“记忆”混在一起。

  • 短期状态：当前任务中需要持续带着走的信息
  • 长期记忆：跨任务保留的用户偏好、事实、历史记录

在 LangGraph 官方文档中，Persistence 把这类能力区分为：

  • checkpoints：偏线程级、任务级的持续状态
  • stores：偏跨线程、长期的数据存储

这套思路对学习 Agent 很有帮助，即便你不用 LangGraph，也应该按这个方式思考状态设计。

4.4 规划 ​

规划不一定意味着复杂的“先写完整计划再执行”。

它可能只是：

  • 决定要不要调用工具
  • 决定先搜哪类信息
  • 决定调用哪个子 Agent
  • 决定下一步是继续、重试还是结束

4.5 执行循环 ​

Agent 一般都存在一个控制循环：

  1. 读取目标和上下文
  2. 推理下一步动作
  3. 调用工具
  4. 读取工具结果
  5. 判断是否继续
  6. 结束或进入下一轮

你真正要掌握的是这个循环，而不是某个框架的“魔法封装”。

4.6 护栏与审批 ​

越接近真实业务，护栏越重要。

常见护栏包括：

  • 敏感操作前人工确认
  • 工具白名单
  • 输出格式校验
  • 越权检查
  • 成本和步数限制
  • 失败回退机制

5. Agent 常见架构模式 ​

学习 Agent 时，建议从简单到复杂。

5.1 单 Agent + 工具调用 ​

这是最基础也最实用的模式：

  • 一个 Agent
  • 若干工具
  • 一个控制循环

适合场景：

  • FAQ 增强问答
  • 搜索总结
  • 数据查询助手

5.2 Router 模式 ​

由一个路由器决定把请求交给哪个专长模块。

适合场景：

  • 用户问题类型多
  • 每种问题已有独立处理链路

例如：

  • 售前问题走知识库
  • 售后问题走工单系统
  • 技术问题走代码助手

5.3 Planner-Executor 模式 ​

一个模块负责规划，另一个模块负责执行。

适合场景：

  • 任务较复杂
  • 步骤依赖明显
  • 需要把大任务拆成多个子任务

5.4 Multi-Agent 模式 ​

多个 Agent 分工协作，例如：

  • 研究员 Agent
  • 数据分析 Agent
  • 报告撰写 Agent
  • 审核 Agent

这种模式很强，但也最容易失控。新手不要过早上多 Agent。

5.5 Graph / Workflow 模式 ​

任务被建模成图或有状态流程。

适合场景：

  • 长任务
  • 状态复杂
  • 需要暂停与恢复
  • 需要人工介入
  • 需要可靠重试

根据 2026-07-01 可访问的 LangGraph 官方文档，LangGraph 的定位是为 长时间运行、带状态的工作流或 Agent 提供底层支持，这也是它和普通链式封装的关键差异。

6. 学 AI Agents 要掌握哪些能力 ​

可以把能力树拆成 6 层。

第 1 层：LLM 基础 ​

你需要理解：

  • Prompt 基础
  • 结构化输出
  • Token 和上下文
  • 工具调用的基本流程
  • 温度、系统提示词、约束输出

第 2 层：Tool Use ​

你需要会：

  • 定义工具 schema
  • 设计输入参数
  • 处理工具失败
  • 把工具结果安全地返回给模型

第 3 层：Workflow 设计 ​

你需要会：

  • 把业务任务拆成步骤
  • 设计路由、重试、回退
  • 决定哪些步骤必须人工确认

第 4 层：State / Memory ​

你需要会：

  • 维护当前任务状态
  • 保存关键中间结果
  • 区分短期记忆与长期记忆

第 5 层：评测与调试 ​

你需要会：

  • 建数据集
  • 看 trace
  • 分析失败样本
  • 做回归测试
  • 定义质量指标

第 6 层：生产化 ​

你需要会：

  • API 封装
  • 日志
  • 监控
  • 成本控制
  • 权限控制
  • 部署

7. 推荐学习顺序 ​

第一步：先学“工具调用”，不要一开始就学多 Agent ​

因为 Agent 的本质不是“有多个模型互相聊天”，而是：

  • 能根据目标采取动作
  • 能使用工具解决问题
  • 能根据外部反馈继续执行

第二步：从固定工作流过渡到半动态 Agent ​

推荐顺序：

  1. 单次调用
  2. 单次调用 + 工具
  3. 简单循环
  4. 有状态工作流
  5. 多角色/多 Agent

第三步：把“能跑”升级成“可靠” ​

很多 Agent Demo 的问题不是跑不起来，而是不稳定。

你需要逐步学会：

  • 限制输出
  • 限制工具调用
  • 处理超时与异常
  • 做日志和 tracing
  • 设计评测集

8. 12 周 AI Agents 学习路线 ​

如果你已经具备 Python 和基础 LLM 使用经验，可以按下面的 12 周路线推进。

第 1-2 周：打基础 ​

目标：

  • 理解 Agent 概念
  • 理解工具调用
  • 学会结构化输出

学习内容：

  • Function calling / tools
  • JSON schema
  • Prompt 设计
  • 简单工具循环

产出：

  • 1 个“问答 + 工具调用”小 Demo

第 3-4 周：做第一个单 Agent ​

目标：

  • 完成一个可以搜索、读取信息、总结结果的 Agent

学习内容：

  • 搜索工具
  • 文件检索
  • 错误处理
  • 多轮执行

产出：

  • 研究助手或网页信息整理助手

第 5-6 周：进入工作流 ​

目标：

  • 学会把 Agent 变成可控流程

学习内容：

  • Router
  • Planner-Executor
  • 有状态执行
  • 人工审批节点

产出：

  • 一个带路由或计划分解的 Agent

第 7-8 周：记忆与上下文工程 ​

目标：

  • 学会管理状态和长期信息

学习内容：

  • 会话状态
  • 检索增强
  • 长期用户偏好
  • 历史记录压缩

产出：

  • 一个具备基础记忆能力的 Agent

第 9-10 周：评测与调试 ​

目标：

  • 不再只凭感觉判断 Agent 是否“好用”

学习内容：

  • Trace
  • 数据集
  • Graders
  • 回归测试
  • 错误分类

产出：

  • 一份 Agent 评测报告

第 11-12 周：完整项目 ​

目标：

  • 完成 1 个接近真实业务的 Agent 项目

推荐项目：

  • 企业知识库行动助手
  • 代码审查/修复助手
  • 自动化研究与报告助手
  • 客服工单分流与处理助手

产出：

  • 项目代码
  • README
  • 评测说明
  • 演示文档

9. 技术栈怎么选 ​

学习 Agent 时，不建议同时上太多框架。

方案 A：偏 OpenAI 官方能力栈 ​

适合人群：

  • 想先学最直接的 Agent 实现方式
  • 想从工具调用开始

优先学习：

  • Responses API
  • Tools
  • Function calling
  • Agents SDK
  • Agent tracing / eval guides

方案 B：偏 Workflow / Graph 工程化 ​

适合人群：

  • 任务更复杂
  • 需要显式状态管理
  • 需要暂停恢复和复杂流程

优先学习：

  • LangGraph
  • Persistence
  • Human-in-the-loop
  • Observability / evaluation

方案 C：偏开源生态学习 ​

适合人群：

  • 想系统补全 Agent 概念
  • 想接触更广泛的工具生态

优先学习：

  • Hugging Face Agents Course
  • MCP
  • 开源模型 + 工具连接

10. MCP 为什么重要 ​

在当前 Agent 生态里，MCP 已经越来越重要。

根据 2026-07-01 可访问的 MCP 官方文档，MCP 是一个开放标准，用来把 AI 应用连接到外部数据源、工具和工作流。它非常适合作为你理解“Agent 如何接世界”的统一接口模型。

从学习角度，你至少要知道：

  • MCP server 是能力提供方
  • 能提供 resources、tools、prompts
  • Agent 通过统一协议接入外部能力

如果你将来要做企业内部 Agent，MCP 会是非常值得投入的方向。

11. 如何评测 Agent ​

Agent 评测是很多人最容易忽略、但最决定上限的部分。

评测什么 ​

常见评测维度：

  • 任务是否完成
  • 工具调用是否正确
  • 输出是否符合格式
  • 是否引用了正确来源
  • 是否出现幻觉
  • 成本是否可接受
  • 延迟是否可接受
  • 是否触发了危险动作

怎么评测 ​

至少建立以下要素：

  • 测试数据集
  • 目标任务定义
  • 评分方法
  • 失败样本分析
  • 回归测试流程

一个重要的当前状态说明 ​

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

  • OpenAI 仍提供 Agent 评测相关指南，例如 traces、graders、datasets、evaluation runs
  • 但 OpenAI 也已明确说明 Evals platform 正在弃用流程中
  • 现有内容会在 2026-10-31 进入只读
  • 平台计划在 2026-11-30 关闭

这意味着：

  • 你仍然应该学习“如何设计评测”
  • 但不应该把学习路线过度绑定到即将下线的单一平台能力上

12. 学习 Agent 时最常见的误区 ​

误区 1：把工作流和 Agent 混为一谈 ​

很多问题固定流程就能解决，不需要把所有步骤都交给模型动态决定。

误区 2：过早上多 Agent ​

多 Agent 不代表更强，常常只是更难调、更贵、更慢。

误区 3：只关注“会不会调用工具”，不关注“工具设计是否合理” ​

Agent 的大量稳定性问题，其实来自工具接口设计不清晰。

误区 4：没有评测，只凭手感改 Prompt ​

没有数据集和回归测试，系统会越改越不稳定。

误区 5：没有护栏 ​

一旦 Agent 能访问真实系统，没有审批、权限和日志，会非常危险。

13. 推荐项目路线 ​

建议按下面顺序做项目。

项目 1：搜索总结助手 ​

能力目标：

  • 学会工具调用
  • 学会多轮执行
  • 学会结构化结果输出

项目 2：本地文档问答 Agent ​

能力目标：

  • 学会检索
  • 学会上下文拼接
  • 学会引用来源

项目 3：任务分解 Agent ​

能力目标：

  • 学会 Planner-Executor
  • 学会中间状态管理

项目 4：代码或业务自动化 Agent ​

能力目标：

  • 学会多工具协同
  • 学会审批与限制
  • 学会日志与评测

理想作品集标准：

  • 至少 2 个 完整 Agent 项目
  • 每个项目都有 README
  • 每个项目都有 评测说明
  • 至少一个项目有 Web UI 或 API

14. 推荐学习资源 ​

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

OpenAI 官方 ​

Hugging Face ​

LangGraph / LangSmith ​

MCP ​

15. 学习成果验收标准 ​

完成这份学习文档对应路线后，你应该能做到：

概念层 ​

  • 能清楚解释什么是 Agent
  • 能解释工作流与 Agent 的区别
  • 能说清楚工具、状态、记忆、规划、护栏的作用

开发层 ​

  • 能实现单 Agent + 工具调用
  • 能实现一个基础工作流或图式流程
  • 能把状态持久化
  • 能为关键节点增加审批

工程层 ​

  • 能看 trace 排查问题
  • 能建立基本评测集
  • 能做简单回归测试
  • 能控制成本、步数和权限

16. 建议的实践节奏 ​

如果你是上班族，推荐这样学：

工作日 ​

  • 30 分钟 理论文档
  • 45 分钟 写代码
  • 15 分钟 记录问题与笔记

周末 ​

  • 2-4 小时 做项目
  • 1 小时 看 trace 和复盘

每周必须输出 ​

  • 1 份 学习笔记
  • 1 个 可运行 Demo 或功能增量

17. 下一步建议 ​

如果你准备正式开始学 Agent，建议按这个顺序执行：

  1. 先掌握结构化输出和工具调用。
  2. 做一个单 Agent 搜索/检索 Demo。
  3. 再引入状态、路由、审批和日志。
  4. 最后再做多 Agent 或复杂图式编排。

最重要的原则不是“框架学得多”，而是：

  • 先做简单可控的系统
  • 再提升动态性
  • 最后提升可靠性和生产化程度

18. 资源核验说明 ​

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

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

后续维护建议：

  • 每 1-2 个月检查一次 Agent 框架版本变动
  • 每 2-3 个月检查一次课程入口和评测工具状态
  • 对涉及“最新平台状态”的内容，优先以官方文档日期为准