如果你最近关注大模型相关的内容估计也和我一样被各种 AI Agent 的讨论刷屏了。但刷了三个月、收藏了几十个视频之后我发现一个问题大多数人和我一样聊 Agent 的时候头头是道真让自己动手写一个能稳定完成多步任务的智能体却不知道从哪下手。市面上不缺三分钟学会 AI Agent的短视频缺的是能让人从头到尾跑通、并且真的理解背后原理的完整教程。我打算写一套这样的东西这一篇就是开头聊聊这套教程要解决什么问题、包含哪些内容、你在开始之前需要准备什么。1. 为什么我要写这套 AI Agent 教程从刷到吐到做成型先说个我最近遇到的场景。一个朋友拿着他写的Agent脚本给我看说是用某个框架跑起来的效果却一言难尽让他整理一份行业资料他查了两个网页就自己开始编引用的链接里有一半打不开。我打开他那份代码发现问题很明显——他把所有东西都堆在 prompt 里模型看起来在用工具实际上只是把一段拼好的文字发出去根本没走工具调用的闭环。这不是个例。我在这行摸爬滚打这几年最大的感受是AI Agent 的概念被讲得太玄被实现得太糙。很多教程把调用一个大模型 API 拼接几段 Prompt就叫做智能体这在 demo 里没问题可一旦面对真实需求——比如连续查资料、跨步骤推理、记住前面聊过的内容——就立刻崩溃。你体验到的感觉就是好像什么都能干但又什么都干不稳。所以我决定自己写一套教程原则很简单每个概念都配能跑的代码每个环节都解释为什么这么做每个坑都告诉你我怎么踩的。这套教程的目标不是让你背会几个框架的类名而是让你亲手把一个能思考、能调用工具、能记住上下文的智能体从零搭起来。适合看这套教程的人也很明确你至少会写 Python自己调过一次大模型 API不管是 OpenAI 还是国内厂商的兼容接口但你还没搞明白 Agent 和普通 ChatBot 程序之间的那道分界线在哪里。如果你只会写 prompt、不会写代码那这套教程对你来说门槛有点高建议先补一下 Python 基础再回来。我不准备再写那种Agent 是未来、Agent 将改变一切的宏大开篇。技术最终是要跑在代码里的与其讨论 Agent 能做什么不如直接动手做一遍。这也是这个系列最核心的基调少聊概念多写代码。2. 先把智能体这个词说清楚它不是一个 Chatbot 换了个名字我知道AI Agent这个词已经被用滥了但正因为用滥了我们更需要在开课前把定义对齐。如果你脑子里对 Agent 的画像还是一个能聊天的对话框那后面所有教程你都会看得云里雾里。2.1 Agent 的运行闭环感知、决策、执行、反馈我习惯用一个句子概括 Agent它是一个能感知环境、做出决策、执行动作、再根据反馈修正自己的程序循环。拆开看它有四个核心环节感知拿到用户指令或者是外部环境返回的结果比如数据库查询结果、网页内容、API 返回值。决策让大模型根据当前的输入、历史上下文和可用工具决定下一步做什么。执行调用具体工具比如搜索网页、执行 Python 代码、读写文件。反馈把工具执行的结果再送回给模型让它判断任务是否完成没完成就继续循环完成了就整理最终回答。这四个环节听起来简单但它和普通 API 调用有本质区别。普通调用是你问一句、模型答一句问答之间没有任何自主性Agent 则是在一个大循环里自行决定调用什么工具、调用几次、什么时候停下来。我用个生活化的类比帮你理解。普通大模型 API 就像一台高级计算器你给它一个算式它给你一个答案而 Agent 更像一个助理你告诉他帮我安排下周的出差行程他需要自己去查航班、看酒店、查天气、对比时间过程中还会遇到航班取消、参会时间调整这类突发情况他得自己想办法调整方案。区别不在于知不知道答案而在于有没有能力为了完成一个目标去主动执行一系列动作。2.2 Agent 的三大核心能力既然要写教程就得把 Agent 的能力拆成可以逐个训练的技术点。我把它归纳成三个部分后边的教程也基本围绕这三条线展开首先是工具调用Tool Calling。这是 Agent 区别于 ChatBot 最关键的能力——模型在推理时输出一个结构化的工具调用请求而不是直接生成文字答复程序负责执行这个请求把结果返回给模型。没有工具调用模型就只能凭自己脑子里的知识回答永远碰不到实时数据。其次是记忆Memory。这里分两层短期记忆负责维护多轮对话上下文长期记忆负责跨会话保存用户偏好或历史知识。一个没有记忆的 Agent每次对话都像失忆了一样这是很多初学者最容易忽略的问题。最后是规划与反思Planning Reflection。模型需要把复杂任务拆成多步子任务并在每步执行后评估结果是否正确、是否需要回头修正。这是 Agent 从能跑走向好用的关键也是评测里最容易拉开差距的部分。这三个能力不是割裂的它们挤在同一个循环里协同工作。我们后面会分别深入讲但你在心里要有这根主线——所有 Agent 架构本质上都是为这个循环服务的。2.3 常见误区别把套框架当会 Agent写到这里我必须泼几盆冷水。很多人看着 GitHub 上星星最多的几个 Agent 框架觉得跑通了 demo 就算是入门了其实离能干活还差得远。典型的误区有三个第一用了 LangChain 不等于做了 Agent。很多框架里最简单的 Chain 模式本质还是 prompt 拼接只是换了层皮第二把工具列表写进 system prompt 也不等于有工具能力模型可能只是在模仿调用工具的文本格式并没有真正执行外部函数你得看程序层是否真的发起了调用第三跑通一次 demo 不等于系统稳定Agent 是概率系统同样的输入在不同时间可能给出不同过程你需要构建评测和兜底逻辑而不是跑通一次就宣布成功。这些误区我在每一篇教程里都会回头强调。现在定义对齐了我们在同一套语境下了再往后看就顺了。3. 系列教程的地图与学习路径每个阶段解决什么问题既然是前言与导读我最该做的事情之一就是把整套教程的路线图摊开给你看。我自己学习 Agent 的时候最大的痛苦就是东一榔头西一棒子今天看个 LangGraph 的 demo明天看篇 RAG 的文章知识点全认识就是拼不成一个完整的系统。所以这套教程我会刻意按照依赖关系排序每一章都建立在前一章的基础上。3.1 三个阶段从能聊到能干活再到能上线我把整个系列分成三个大的阶段方便你对号入座。第一阶段叫把地基打牢。这一阶段不碰花哨的智能体概念只做两件事一是把大模型 API 的调用、流式输出、参数调优讲透二是把 Prompt 工程的写作方法论系统过一遍。没有这个地基后面 Agent 出现问题时你会分不清到底是模型不行、还是 Prompt 引导不够、还是代码逻辑有 bug。第二阶段叫让模型长出手脚。这是整套教程的核心区会完整实现一个 Agent 主循环从设计工具协议、解析模型的 Function Calling 请求到执行工具、把结果写回上下文再到多轮规划与自我反思。这个阶段结束的时候你已经拥有一个能查资料、能算数据、能自我纠错的最小可用 Agent。第三阶段叫把原型变成产品。这一阶段解决的是跑通 demo和能上线用之间的巨大鸿沟怎样给 Agent 加短期和长期记忆怎样用向量检索扩展知识边界怎样做评测集来度量每次改动是好是坏怎样把服务部署成可访问的 API以及怎样观测 Agent 在真实用户下的行为。3.2 具体章节规划的说明我按上面三个阶段拆成了大约二十讲我自己心里先排了个序大概是这样的思路环境准备与大模型 API 基础调用Prompt 工程实践写指令、给示例、设角色流式输出与对话状态管理模型如何面向过程编程Function Calling 原理用一个最小循环实现你的第一个 Agent用 ReAct 模式增强推理过程的可控性工具设计规范参数定义、错误处理、返回结构Agent 的短期记忆上下文窗口的取舍策略长期记忆外置存储与用户画像向量数据库与语义检索入门基于 RAG 的外接知识库多 Agent 协作与任务分发评测集构建让 Agent 的改进可以被度量端到端实战项目从需求分析到功能拆解部署、日志、可观测性与成本控制这不是一个死板的课表写的过程中我会根据实际反馈调整顺序。但大方向不会变每个章节结束你都应该有一个可以跑、可以玩的成果。我不太赞同先学完所有理论再动手的学习方式Agent 这种东西必须边做边理解一个能跑的半成品比十集纯理论干货都有用。3.3 每一章的交付物我在规划教程的时候特别在意学完这一篇之后你手里多了什么。所以每一篇我都会明确写出交付物。比如前面第二阶段的最小 Agent 循环那一篇交付物就是一个大概两三百行的 Python 脚本它能读懂你的指令、自动调用搜索或计算工具、并把最终答案整理给你。到后面部署篇的交付物就是一个能承受并发请求的 Agent 服务。你甚至可以拿这套教程当对照清单用学完一章就去仓库里找对应代码自己跑一遍、改一遍然后再继续。这套教程不是用来收藏的是用来动手的。4. 开课前的自检清单用什么基础能跟上这套课我见过太多人报名一个课程之后发现自己跟不上不是课程讲得不好是前置技能没准备够。为了让你不至于中途崩溃我把这个系列真正需要的基础列一个清单你对照着自己评估一下。4.1 技术基础其实没那么吓人硬性要求只有一个半Python 基础是必须的另外半个是对大模型 API 的上手经验。Python 这块你需要有能力读懂函数定义、类和装饰器能处理简单的异步代码——因为 Agent 的工具调用往往是 I/O 密集型我们会用到 asyncio。如果你之前只写过排序算法、没碰过异步编程也不用慌后面我会专门花一小节把 asyncio 在 Agent 场景下的用法讲清楚你不需要成为异步专家只要看得懂await和并发任务的写法就行。大模型 API 经验是什么呢就是你至少亲手调用过一次模型接口知道messages列表里system、user、assistant这几个角色大致是怎么回事。不要求你做过复杂的 Prompt 工程但你不能连上下文是什么概念都没听说过。如果你暂时还没试过我建议你在开课之前花一个小时先把最简单的对话补上这是成本最低的准备。4.2 开发环境准备不用烧钱但也不能太省很多初学者每次开新课都在担心我这台电脑能不能跑。好消息是本系列绝大多数代码在普通笔记本上就能完成——因为重活都交给模型 API 了你的电脑主要负责调度和工具执行。你需要的只是 Python 3.10 以上版本、一个趁手的代码编辑器以及一个能访问大模型 API 的账号。说到账号我多说两句预算问题。Agent 和普通调用不一样它一次任务可能会在循环里调用很多次模型token 消耗比单轮问答高一个数量级。我的个人经验是如果你只是跟着教程做练习一个月一百元人民币左右的预算基本够用但你要是频繁跑大型评测这点钱撑不住。建议尽早养成看 token 消耗的习惯我会在教程里专门教你怎么统计单次任务的成本——这不是抠门这是做 Agent 的基本职业素养。4.3 心态准备Agent 是概率系统不是传统程序我想单独把这条拎出来说因为它的重要性远超技术准备。我们在传统编程里习惯了确定性同一个输入永远得到同一个输出程序不对就是有 bug改掉就稳定。但 Agent 不是这样的——它是概率系统同样的输入、同样的代码这次它选择先查资料再回答下次它可能直接就凭记忆开编了。这意味着你的调试思维要转变你不是在找一次性的 bug而是在提升系统的成功率。你写的那套主循环越完善、工具的返回结构设计得越合理、评测集覆盖的场景越全面Agent 的整体表现就越好但这不意味着它能做到 100% 正确。想明白这一点你在后面遇到 Agent突然抽风的时候就不会崩溃而是会平静地掏出日志看看这次是哪个环节出了偏差。我把这些前置条件摆在前面不是想劝退谁而是想让你带着正确的期待开始。工具和底子不够我们边学边补心态没摆正那后面每一步都会觉得这玩意儿不靠谱。5. 技术选型为什么从 Function Calling 和状态管理入手而不是上来就套框架在正式开始之前还有一个绕不开的决策用哪个框架、什么技术栈来写这套教程。我看了一下市面上主流的方案各有各的道理但结合教学和实用两个目标我做了个我认为最适合大多数人的选择。5.1 当前主流技术栈的横向对比我把折腾过的主流方案放在一起对比一下给大家一个直观的印象方案核心思路优点缺点纯手写主循环自己用代码实现感知-决策-执行-反馈循环可控性强、原理清晰、依赖少需要自己处理和模型交互的细节LangChain / LangGraph提供封装好的 Agent 组件与状态图编排组件丰富、上手写业务快抽象层厚出问题时调试链路长Semantic Kernel微软出品的插件化 Agent 框架在 .NET 生态和微软云整合好Python 社区相对没那么主流AutoGen / CrewAI面向多 Agent 协作场景多智能体分工演示很惊艳生产环境稳定性与细节打磨参差看这个表你可能已经感觉到没有绝对最好的框架只看你处于什么阶段、要解决什么问题。5.2 我的选择先手写循环再引入框架我在这个系列里采用了一个比较笨但特别有效的策略前几讲完全不使用任何重量级框架用几十行代码手写一个 Agent 主循环等你想明白每一步发生了什么再渐进式地引入框架能力。为什么这么做我踩过一次很典型的坑。早先我图省事直接用框架封装好的 AgentExecutordemo 半天就写完了结果一到线上就抓瞎Agent 在某个分支里反复调用同一个工具停不下来我打开日志想排查发现框架自己包了一层又一层抽象根本看不清数据流走到哪一步出了问题。最后我不得不把框架代码扒出来一层层读才找到是问题。那之后我就明白了任何框架都是对你工程能力的封装如果你不具备读懂封装背后的基础能力出了问题就只能干瞪眼。所以这个系列在早期会故意反框架一点带着你把主循环一步步写出来while not task_done: # 1. 把当前的对话历史和工具结果组装好发给模型 response llm.chat(messages tool_results) # 2. 看模型的输出是最终回复还是想调用某个工具 if response.content: return response.content # 模型觉得任务完成了 # 3. 如果模型发来工具调用请求就执行它 tool_name response.tool_calls[0].name tool_args response.tool_calls[0].arguments result execute_tool(tool_name, tool_args) # 4. 把工具执行结果作为一条新消息追加到上下文继续循环 messages.append(tool_result_message(result))这段代码是一个极其朴素的 Agent 主循环骨架。你别觉得它简陋它包含了我们前面说的全部核心环节决策模型选择回复内容还是调用工具、执行运行具体函数、反馈结果回填上下文。等你亲手把它扩展到能处理错误、能截断上下文、能记录完整日志之后你再去看 LangGraph 那张状态图会发现一切都是那么熟悉。5.3 模型选型的建议再简单聊一下模型选型。不同厂商的模型对 Function Calling 的支持成熟度差别挺大这直接决定了你的 Agent 体验。我的建议是初学阶段选一个工具调用能力成熟、文档清晰的主流模型没必要在冷门模型上省那点 token 钱。等你的 Agent 主循环稳定之后可以再抽一层模型适配器把模型切换的成本降下来。尤其要提醒的是Function Calling 的稳定度和模型的版本强相关同一个模型供应商的两个版本可能一个对参数解析很准、另一个经常丢参数。这部分没有捷径只能靠自己的评测集来验证。评测怎么做我也会在后面专门安排一章来展开。6. 动手写第一个 Agent 之前先建立三个工程习惯在正式进入代码之前我还想跟你分享三个工程习惯。它们不是某个具体的知识点却会贯穿这套教程的每一个项目。我自己吃过亏才知道这些习惯有多重要。6.1 习惯一把过程完整地记录下来很多初学者调试 Agent 的时候喜欢直接看最终回答回答不对就开始瞎猜。但 Agent 的实际执行过程是一连串步骤它先看到了什么、调用了一个什么工具、工具返回了什么、它又生成了什么新的想法。如果你看不到这个过程你根本无法定位问题出在决策层、执行层还是上下文组装层。我的做法非常朴素给主循环加一个详细的日志记录函数每一步都打一行带时间戳的日志。日志内容至少包括模型角色、当前消息摘要、触发的工具名称、工具参数、工具返回值的前 N 个字符、本轮循环耗时和 token 消耗。不用上什么高大上的可视化平台刚开始一个 print 函数就够了关键是养成每一步都有迹可循的习惯。6.2 习惯二给每一次对话记账前面提到过 API 成本的问题这里我想展开。Agent 一个循环调用十几轮模型很正常如果你对成本没概念月底账单会教你做人。我自己第一次跑一个稍微复杂的 Agent 任务一个晚上烧掉了差不多五十块的 token 费用当时就愣住了。从那以后我给所有 Agent 项目都加了一层记账逻辑在每次模型调用返回后解析它的 usage 字段累加进一个计数对象并在日志里打印本任务累计消耗 tokens: X约合人民币 Y 元。顺手做这件事只需要二十行代码但它会让你对每一条 prompt 的长短都变得敏感——你会发现很多看似聪明的把整个网页内容塞进上下文的操作其实是在花大价钱买一个残缺的信息源。6.3 习惯三准备一份最怕跑崩的测试清单Agent 是概率系统意味着你每一次改动 Prompt、调整工具定义、换模型版本都可能让之前正常的行为悄悄退化。防止这种退化的唯一办法就是有一份固定的测试集。请你开课之前就先花时间准备二十到三十个典型任务比如总结这篇文章并给出三个可执行的建议查询某只股票的最近三个交易日收盘价根据我的历史偏好推荐一部电影等等。每个任务写清楚期望的行为标准——不只是看最终答案对不对还要看是否用了正确的工具、是否问了澄清问题、是否在信息不足时诚实承认。这样每一次代码改动之后你都能用同一份清单快速回归一遍而不是凭感觉说好像比之前好用了一点。我见过太多人把时间花在优化某一个案例上结果 A 案例变好了、B 案例变差了还浑然不知。有了测试清单你的 Agent 迭代才真正从玄学变成工程。这套教程后面会教你如何设计更科学的评测指标和自动化评测流程但你现在就可以从这份手工清单开始。二十多讲的内容已经在我脑子里过了一遍从怎么接 API、怎么写第一个循环到怎么设计工具协议、怎么搭记忆、怎么建评测再到最后怎么部署上线每一步我都打算用能跑的代码陪着你走完。这不是一条轻松的路尤其当你发现 Agent 经常在某一步突然犯傻的时候你可能会怀疑自己是不是理解错了什么。我最早开始做 Agent 时也是这么怀疑过来的后来才明白那些犯傻的时刻恰恰是最有价值的学习材料——因为每一次异常背后都藏着一个你对系统运行机制的新理解。这套教程不打算给你看一个完美无缺的智能体而是想带着你经历从粗糙到可用的完整过程包括过程中所有的不完美。准备好了的话我们下一讲直接开始配环境、写第一行代码。