1. 为什么我要写这个从零开始的Agent开发系列过去大半年我几乎每周都会被问到同一个问题想学Agent开发该从哪下手问的人里有刚毕业的应届生有做了三年前端想转方向的工程师也有已经在做传统后端、想往大模型方向靠的资深开发。他们的共同困惑是网上资料太多太碎官方文档偏概念实战教程又往往默认你已经懂了某个框架结果就是东看一点西看一点始终拼不出一张完整的地图。这个系列就是来解决这件事的。我打算用一条完整的主线把Agent开发从最基础的概念一路讲到能自己搭出一个可用的项目。它不是某个框架的官方文档翻译也不是把别人的Demo抄一遍而是我这些年在大模型应用落地过程中踩过的坑、做过的取舍、验证过的方案的一次系统整理。你可以把它当成一份学习路线图也可以当成一本随时翻查的实战手册。先明确一下这个系列适合谁。如果你完全没接触过大模型只知道ChatGPT能聊天那也没关系我会从最基础的概念讲起用生活化的例子把LLM、Agent、工具调用这些词讲清楚。如果你已经会调用API、写过一些简单的对话程序那这个系列能帮你把零散的知识串成体系尤其是工程化落地那部分是很多教程里不会细讲的。如果你已经在做Agent项目遇到了并发、稳定性、工具编排这些实际问题那后面的进阶章节应该能给你一些参考。整个系列的关键词会围绕几个核心概念展开Agent、LLM、MCP、工具调用、记忆机制、任务规划、多Agent协作。这些词你会在后面的每一篇里反复见到我会在第一次出现时讲透之后就直接用。目录我会放在这一篇的末尾方便你按需跳转但我建议第一次读的时候还是按顺序来因为后面的内容会依赖前面的基础。2. 先把几个绕不开的核心概念讲明白2.1 LLM到底是什么别被名字吓到LLM全称是Large Language Model中文叫大语言模型。很多人一听“大”和“模型”就觉得高深其实你可以把它理解成一个超级能接话的文本补全器。你给它一段文字它根据训练时见过的大量文本预测接下来最可能出现的文字是什么。就这么简单。但就是这么一个“接话”的能力在参数量足够大、训练数据足够多之后涌现出了很多意想不到的本事它能理解你的意图能总结长文能写代码能根据你的描述推理出答案。这些能力不是被专门编程进去的而是从海量数据里自己学出来的。这也是为什么同一个模型你换个问法它的表现可能天差地别——它的输出高度依赖你给的输入也就是提示词。这里有个新手常犯的误区把LLM当成数据库或者搜索引擎。它不是。它不知道今天天气怎么样也不知道你公司内部的文档写了什么除非你把这些信息在提问时一起给它。它的知识截止到训练数据的时间点之后的事情它一概不知。理解这一点你才能理解为什么Agent需要工具、需要检索、需要记忆——因为光靠模型本身它能做的事情是有边界的。2.2 Agent不是新物种它是给LLM装上了手脚Agent这个词翻译过来叫“智能体”听起来很玄。但如果你把LLM看成一个只会动嘴的军师那Agent就是给这个军师配了一双手、一双脚还给了它一个可以记事的小本本。军师负责出主意手脚负责去执行小本本负责记住做过什么、还需要做什么。具体来说一个Agent通常包含几个部分一个LLM作为大脑负责理解和决策一组工具作为手脚比如搜索、计算、读写文件、调用API一套记忆机制用来保存对话历史和中间结果还有一个执行循环让Agent能根据当前状态决定下一步做什么做完之后看结果再决定下一步直到任务完成。这个循环是Agent和普通对话程序最本质的区别。普通对话是你问一句它答一句一问一答就结束了。Agent是你给它一个目标它会自己拆解成若干步骤一步步去执行中间遇到问题还会调整策略。比如你让它“帮我查一下明天北京的天气如果下雨就提醒我带伞”它会先调用天气查询工具拿到结果后判断是否下雨如果下雨就生成提醒。这一连串动作都是它自己规划并执行的。2.3 MCP解决的是“工具怎么接”这个老大难问题MCP全称是Model Context Protocol你可以把它理解成一套标准化的插头规范。在没有MCP之前每接一个工具你都要为这个工具写一套专门的适配代码工具多了之后代码会变得非常臃肿而且换个模型或者换个框架这些适配代码可能就要重写。MCP的思路是把工具的提供方和使用方解耦。工具提供方按照MCP的规范暴露自己的能力模型或Agent框架也按照MCP的规范去调用。这样一来任何一个遵循MCP的工具都能被任何支持MCP的Agent直接使用不需要为每个组合单独写适配。这就像USB接口统一了各种外设的连接方式你不需要为每个U盘、鼠标、键盘都准备一个专门的插口。在实际项目里MCP能大幅降低工具集成的成本。你团队里有人写了一个查数据库的工具有人写了一个发邮件的工具只要它们都按MCP规范暴露主Agent就能直接挂载使用。后面我会专门用一篇来讲MCP的协议细节和实战接入这里你先有个印象就行。3. 这个系列的学习路线是怎么设计的3.1 从概念到跑通第一个Demo再到工程化整个系列我分成了四个阶段。第一阶段是打地基把LLM、Agent、提示词、工具调用这些基础概念讲清楚让你知道每个词到底指什么不然后面看代码会一头雾水。这个阶段不要求你写多少代码但要求你能用自己的话把这些概念解释给别人听。第二阶段是动手跑通。我会带你从最简单的对话程序开始一步步加上工具调用、加上记忆、加上任务规划最终做出一个能完成实际任务的Agent。这个阶段会有大量代码但我不会只丢代码给你每一段关键代码我都会解释为什么这么写换一种写法会有什么问题。第三阶段是工程化。很多人Demo跑通了一上生产就各种问题并发一高就崩工具调用失败不知道怎么处理成本控制不住日志一团糟。这个阶段我会讲架构设计、错误处理、性能优化、成本控制这些实战中真正要命的东西。第四阶段是进阶专题。包括多Agent协作、Agent安全、评估与测试、以及一些特定场景的落地方案。这部分内容会根据实际项目经验持续更新因为Agent这个领域变化太快今天的最佳实践明天可能就被推翻了。3.2 为什么我不建议你一上来就学框架市面上主流的Agent框架有不少LangChain、LlamaIndex、AutoGen、CrewAI等等每个都有自己的拥趸。但我强烈建议你先别急着学框架先用最原始的方式直接调用模型API手写一个最简单的Agent循环。为什么因为框架帮你封装了太多东西你如果不知道底层发生了什么一旦出问题就完全无从下手。我见过太多人用框架搭了个Demo觉得很厉害结果工具调用返回了预期之外的结果他连去哪里查日志、怎么打断点都不知道。手写一遍之后你会清楚地知道哦原来所谓的Agent循环就是一个while循环每次把历史消息和工具定义发给模型模型返回要调用的工具我执行完再把结果塞回去。这个认知一旦建立再看任何框架的源码都会觉得亲切。等你手写过一个能用的Agent之后再去学框架你的关注点就会变成“这个框架帮我解决了什么重复劳动”“它的抽象是否合理”“它的性能瓶颈在哪里”而不是被框架牵着鼻子走。3.3 每篇的节奏和你的预期管理这个系列不会追求大而全不会把每个框架的每个API都讲一遍。我的目标是让你在读完一个阶段后能独立完成对应难度的任务。所以每篇的节奏是先讲清楚要解决的问题和背后的原理再给可运行的代码最后补充实战中的注意事项和常见坑。你需要付出的时间我大致估一下如果每天能投入一到两小时第一阶段大概一周能过完第二阶段两周左右能跑通一个像样的Agent第三阶段需要结合你自己的项目来实践时间因人而异。不要指望看完就会Agent开发是一门手艺必须自己动手写、动手调、动手踩坑才能真正掌握。4. 开始之前你需要准备些什么4.1 编程基础和环境要求这个系列默认你会一门编程语言Python优先因为生态最成熟。如果你只会JavaScript或者Java也能跟上核心逻辑是通的只是代码示例你需要自己转译一下。完全零编程基础的话建议先补一下Python基础至少要知道函数、类、字典、列表、异常处理这些概念怎么用。环境方面你需要一台能联网的电脑能访问大模型的API。Python版本建议3.10以上因为很多新库已经不支持更老的版本了。包管理用pip或者conda都行我个人习惯用conda建虚拟环境避免依赖冲突。编辑器用VS Code或者PyCharm都可以看你顺手。API Key这块我要多说一句不要把它硬编码在代码里也不要把带Key的代码传到公开仓库。用环境变量或者配置文件来管理这是最基本的工程习惯。我见过有人把Key直接写在代码里然后推到GitHub结果被人扫到一夜之间跑掉几百块。这种坑没必要踩。4.2 心态上的准备接受不确定性Agent开发和传统软件开发有一个很大的不同传统软件的行为是确定的你输入A经过逻辑B一定得到C。但Agent的行为是不确定的同样的输入模型可能给出不同的输出工具调用可能失败网络可能超时。你必须接受这种不确定性并学会在这种不确定性之上构建可靠的系统。这意味着你的代码里会有大量的异常处理、重试逻辑、降级方案。这不是代码写得丑而是这个领域的常态。我刚开始做的时候也很不适应总觉得为什么不能像写普通后端那样干净利落。后来想明白了你是在和一个概率系统打交道你的工程手段就是用来驯服这种概率性的。4.3 关于成本和调试的实用建议大模型API是按Token计费的Token你可以粗略理解成文字的长度单位一个中文字大概对应一到两个Token。Agent因为要反复调用模型、要带上工具定义和历史消息Token消耗会比普通对话大很多。调试阶段一定要关注成本几个实用做法把日志打全每次调用的输入输出都记下来方便复盘设置预算上限很多平台支持设置每日或每月限额防止意外跑飞调试时用便宜的小模型逻辑跑通了再换大模型验证效果。调试Agent比调试普通程序要难因为它的执行路径不是固定的。我的经验是把每一步的中间状态都打印出来包括发给模型的完整消息、模型返回的原始内容、工具调用的参数和结果。这样出问题的时候你能清楚地看到是哪一步偏了。不要嫌日志多Agent调试阶段日志越多越好。5. 系列目录与各篇要解决的问题下面是这个系列的目录我会按这个顺序更新但具体篇目可能会根据读者反馈调整。每一篇我都会尽量做到独立可读但强烈建议按顺序来。篇号标题核心解决的问题01前言与目录建立整体认知明确学习路径02LLM基础与API调用搞懂模型怎么用Token、温度、上下文窗口是什么03提示词工程实战怎么写出稳定可控的提示词而不是靠运气04手写第一个Agent循环不依赖框架理解Agent的底层执行逻辑05工具调用与函数定义怎么让模型调用外部工具参数怎么设计06MCP协议详解与接入标准化工具接入打通工具生态07记忆机制设计短期记忆、长期记忆、向量检索怎么配合08任务规划与拆解让Agent能处理多步骤复杂任务09多Agent协作模式什么时候需要多个Agent怎么分工10工程化并发、错误处理与成本控制从Demo到生产要跨过的坎11Agent评估与测试怎么衡量一个Agent好不好用12安全与权限控制防止Agent做出危险操作13实战项目从零搭建一个完整Agent应用综合运用前面所有知识这个目录不是死的如果中间发现某个话题需要单独展开我会加篇。如果某个话题大家普遍觉得不需要我也会合并。你可以把这份目录当成一张地图知道自己走到哪了下一步要去哪。6. 写在正式开始之前的一些心里话Agent开发这个方向现在确实很热热到有点浮躁。各种框架层出不穷各种概念满天飞今天有人说这个框架要统一江湖明天有人说那个范式要颠覆一切。但如果你把噪音过滤掉会发现核心的东西其实没怎么变模型负责理解和生成工具负责执行记忆负责保存状态循环负责驱动流程。把这些基础打牢不管上层怎么变你都能快速适应。我在这个系列里会尽量少用那些听起来很厉害的词多用大白话和实际例子。遇到必须用专业术语的地方我会解释清楚。遇到有争议的方案我会说明我的选择和理由但不会说别的方案就是错的。技术选型没有绝对的对错只有适不适合你的场景。最后说一句学Agent开发动手比看书重要一百倍。你看十篇教程不如自己写一个能跑起来的Demo。你调一百次API不如自己踩一次工具调用失败的坑然后把它解决掉。这个系列会给你地图和工具但路要你自己走。准备好了的话下一篇我们就从LLM的基础和API调用开始。
从零开始学Agent开发：LLM、MCP与工具调用实战指南
1. 为什么我要写这个从零开始的Agent开发系列过去大半年我几乎每周都会被问到同一个问题想学Agent开发该从哪下手问的人里有刚毕业的应届生有做了三年前端想转方向的工程师也有已经在做传统后端、想往大模型方向靠的资深开发。他们的共同困惑是网上资料太多太碎官方文档偏概念实战教程又往往默认你已经懂了某个框架结果就是东看一点西看一点始终拼不出一张完整的地图。这个系列就是来解决这件事的。我打算用一条完整的主线把Agent开发从最基础的概念一路讲到能自己搭出一个可用的项目。它不是某个框架的官方文档翻译也不是把别人的Demo抄一遍而是我这些年在大模型应用落地过程中踩过的坑、做过的取舍、验证过的方案的一次系统整理。你可以把它当成一份学习路线图也可以当成一本随时翻查的实战手册。先明确一下这个系列适合谁。如果你完全没接触过大模型只知道ChatGPT能聊天那也没关系我会从最基础的概念讲起用生活化的例子把LLM、Agent、工具调用这些词讲清楚。如果你已经会调用API、写过一些简单的对话程序那这个系列能帮你把零散的知识串成体系尤其是工程化落地那部分是很多教程里不会细讲的。如果你已经在做Agent项目遇到了并发、稳定性、工具编排这些实际问题那后面的进阶章节应该能给你一些参考。整个系列的关键词会围绕几个核心概念展开Agent、LLM、MCP、工具调用、记忆机制、任务规划、多Agent协作。这些词你会在后面的每一篇里反复见到我会在第一次出现时讲透之后就直接用。目录我会放在这一篇的末尾方便你按需跳转但我建议第一次读的时候还是按顺序来因为后面的内容会依赖前面的基础。2. 先把几个绕不开的核心概念讲明白2.1 LLM到底是什么别被名字吓到LLM全称是Large Language Model中文叫大语言模型。很多人一听“大”和“模型”就觉得高深其实你可以把它理解成一个超级能接话的文本补全器。你给它一段文字它根据训练时见过的大量文本预测接下来最可能出现的文字是什么。就这么简单。但就是这么一个“接话”的能力在参数量足够大、训练数据足够多之后涌现出了很多意想不到的本事它能理解你的意图能总结长文能写代码能根据你的描述推理出答案。这些能力不是被专门编程进去的而是从海量数据里自己学出来的。这也是为什么同一个模型你换个问法它的表现可能天差地别——它的输出高度依赖你给的输入也就是提示词。这里有个新手常犯的误区把LLM当成数据库或者搜索引擎。它不是。它不知道今天天气怎么样也不知道你公司内部的文档写了什么除非你把这些信息在提问时一起给它。它的知识截止到训练数据的时间点之后的事情它一概不知。理解这一点你才能理解为什么Agent需要工具、需要检索、需要记忆——因为光靠模型本身它能做的事情是有边界的。2.2 Agent不是新物种它是给LLM装上了手脚Agent这个词翻译过来叫“智能体”听起来很玄。但如果你把LLM看成一个只会动嘴的军师那Agent就是给这个军师配了一双手、一双脚还给了它一个可以记事的小本本。军师负责出主意手脚负责去执行小本本负责记住做过什么、还需要做什么。具体来说一个Agent通常包含几个部分一个LLM作为大脑负责理解和决策一组工具作为手脚比如搜索、计算、读写文件、调用API一套记忆机制用来保存对话历史和中间结果还有一个执行循环让Agent能根据当前状态决定下一步做什么做完之后看结果再决定下一步直到任务完成。这个循环是Agent和普通对话程序最本质的区别。普通对话是你问一句它答一句一问一答就结束了。Agent是你给它一个目标它会自己拆解成若干步骤一步步去执行中间遇到问题还会调整策略。比如你让它“帮我查一下明天北京的天气如果下雨就提醒我带伞”它会先调用天气查询工具拿到结果后判断是否下雨如果下雨就生成提醒。这一连串动作都是它自己规划并执行的。2.3 MCP解决的是“工具怎么接”这个老大难问题MCP全称是Model Context Protocol你可以把它理解成一套标准化的插头规范。在没有MCP之前每接一个工具你都要为这个工具写一套专门的适配代码工具多了之后代码会变得非常臃肿而且换个模型或者换个框架这些适配代码可能就要重写。MCP的思路是把工具的提供方和使用方解耦。工具提供方按照MCP的规范暴露自己的能力模型或Agent框架也按照MCP的规范去调用。这样一来任何一个遵循MCP的工具都能被任何支持MCP的Agent直接使用不需要为每个组合单独写适配。这就像USB接口统一了各种外设的连接方式你不需要为每个U盘、鼠标、键盘都准备一个专门的插口。在实际项目里MCP能大幅降低工具集成的成本。你团队里有人写了一个查数据库的工具有人写了一个发邮件的工具只要它们都按MCP规范暴露主Agent就能直接挂载使用。后面我会专门用一篇来讲MCP的协议细节和实战接入这里你先有个印象就行。3. 这个系列的学习路线是怎么设计的3.1 从概念到跑通第一个Demo再到工程化整个系列我分成了四个阶段。第一阶段是打地基把LLM、Agent、提示词、工具调用这些基础概念讲清楚让你知道每个词到底指什么不然后面看代码会一头雾水。这个阶段不要求你写多少代码但要求你能用自己的话把这些概念解释给别人听。第二阶段是动手跑通。我会带你从最简单的对话程序开始一步步加上工具调用、加上记忆、加上任务规划最终做出一个能完成实际任务的Agent。这个阶段会有大量代码但我不会只丢代码给你每一段关键代码我都会解释为什么这么写换一种写法会有什么问题。第三阶段是工程化。很多人Demo跑通了一上生产就各种问题并发一高就崩工具调用失败不知道怎么处理成本控制不住日志一团糟。这个阶段我会讲架构设计、错误处理、性能优化、成本控制这些实战中真正要命的东西。第四阶段是进阶专题。包括多Agent协作、Agent安全、评估与测试、以及一些特定场景的落地方案。这部分内容会根据实际项目经验持续更新因为Agent这个领域变化太快今天的最佳实践明天可能就被推翻了。3.2 为什么我不建议你一上来就学框架市面上主流的Agent框架有不少LangChain、LlamaIndex、AutoGen、CrewAI等等每个都有自己的拥趸。但我强烈建议你先别急着学框架先用最原始的方式直接调用模型API手写一个最简单的Agent循环。为什么因为框架帮你封装了太多东西你如果不知道底层发生了什么一旦出问题就完全无从下手。我见过太多人用框架搭了个Demo觉得很厉害结果工具调用返回了预期之外的结果他连去哪里查日志、怎么打断点都不知道。手写一遍之后你会清楚地知道哦原来所谓的Agent循环就是一个while循环每次把历史消息和工具定义发给模型模型返回要调用的工具我执行完再把结果塞回去。这个认知一旦建立再看任何框架的源码都会觉得亲切。等你手写过一个能用的Agent之后再去学框架你的关注点就会变成“这个框架帮我解决了什么重复劳动”“它的抽象是否合理”“它的性能瓶颈在哪里”而不是被框架牵着鼻子走。3.3 每篇的节奏和你的预期管理这个系列不会追求大而全不会把每个框架的每个API都讲一遍。我的目标是让你在读完一个阶段后能独立完成对应难度的任务。所以每篇的节奏是先讲清楚要解决的问题和背后的原理再给可运行的代码最后补充实战中的注意事项和常见坑。你需要付出的时间我大致估一下如果每天能投入一到两小时第一阶段大概一周能过完第二阶段两周左右能跑通一个像样的Agent第三阶段需要结合你自己的项目来实践时间因人而异。不要指望看完就会Agent开发是一门手艺必须自己动手写、动手调、动手踩坑才能真正掌握。4. 开始之前你需要准备些什么4.1 编程基础和环境要求这个系列默认你会一门编程语言Python优先因为生态最成熟。如果你只会JavaScript或者Java也能跟上核心逻辑是通的只是代码示例你需要自己转译一下。完全零编程基础的话建议先补一下Python基础至少要知道函数、类、字典、列表、异常处理这些概念怎么用。环境方面你需要一台能联网的电脑能访问大模型的API。Python版本建议3.10以上因为很多新库已经不支持更老的版本了。包管理用pip或者conda都行我个人习惯用conda建虚拟环境避免依赖冲突。编辑器用VS Code或者PyCharm都可以看你顺手。API Key这块我要多说一句不要把它硬编码在代码里也不要把带Key的代码传到公开仓库。用环境变量或者配置文件来管理这是最基本的工程习惯。我见过有人把Key直接写在代码里然后推到GitHub结果被人扫到一夜之间跑掉几百块。这种坑没必要踩。4.2 心态上的准备接受不确定性Agent开发和传统软件开发有一个很大的不同传统软件的行为是确定的你输入A经过逻辑B一定得到C。但Agent的行为是不确定的同样的输入模型可能给出不同的输出工具调用可能失败网络可能超时。你必须接受这种不确定性并学会在这种不确定性之上构建可靠的系统。这意味着你的代码里会有大量的异常处理、重试逻辑、降级方案。这不是代码写得丑而是这个领域的常态。我刚开始做的时候也很不适应总觉得为什么不能像写普通后端那样干净利落。后来想明白了你是在和一个概率系统打交道你的工程手段就是用来驯服这种概率性的。4.3 关于成本和调试的实用建议大模型API是按Token计费的Token你可以粗略理解成文字的长度单位一个中文字大概对应一到两个Token。Agent因为要反复调用模型、要带上工具定义和历史消息Token消耗会比普通对话大很多。调试阶段一定要关注成本几个实用做法把日志打全每次调用的输入输出都记下来方便复盘设置预算上限很多平台支持设置每日或每月限额防止意外跑飞调试时用便宜的小模型逻辑跑通了再换大模型验证效果。调试Agent比调试普通程序要难因为它的执行路径不是固定的。我的经验是把每一步的中间状态都打印出来包括发给模型的完整消息、模型返回的原始内容、工具调用的参数和结果。这样出问题的时候你能清楚地看到是哪一步偏了。不要嫌日志多Agent调试阶段日志越多越好。5. 系列目录与各篇要解决的问题下面是这个系列的目录我会按这个顺序更新但具体篇目可能会根据读者反馈调整。每一篇我都会尽量做到独立可读但强烈建议按顺序来。篇号标题核心解决的问题01前言与目录建立整体认知明确学习路径02LLM基础与API调用搞懂模型怎么用Token、温度、上下文窗口是什么03提示词工程实战怎么写出稳定可控的提示词而不是靠运气04手写第一个Agent循环不依赖框架理解Agent的底层执行逻辑05工具调用与函数定义怎么让模型调用外部工具参数怎么设计06MCP协议详解与接入标准化工具接入打通工具生态07记忆机制设计短期记忆、长期记忆、向量检索怎么配合08任务规划与拆解让Agent能处理多步骤复杂任务09多Agent协作模式什么时候需要多个Agent怎么分工10工程化并发、错误处理与成本控制从Demo到生产要跨过的坎11Agent评估与测试怎么衡量一个Agent好不好用12安全与权限控制防止Agent做出危险操作13实战项目从零搭建一个完整Agent应用综合运用前面所有知识这个目录不是死的如果中间发现某个话题需要单独展开我会加篇。如果某个话题大家普遍觉得不需要我也会合并。你可以把这份目录当成一张地图知道自己走到哪了下一步要去哪。6. 写在正式开始之前的一些心里话Agent开发这个方向现在确实很热热到有点浮躁。各种框架层出不穷各种概念满天飞今天有人说这个框架要统一江湖明天有人说那个范式要颠覆一切。但如果你把噪音过滤掉会发现核心的东西其实没怎么变模型负责理解和生成工具负责执行记忆负责保存状态循环负责驱动流程。把这些基础打牢不管上层怎么变你都能快速适应。我在这个系列里会尽量少用那些听起来很厉害的词多用大白话和实际例子。遇到必须用专业术语的地方我会解释清楚。遇到有争议的方案我会说明我的选择和理由但不会说别的方案就是错的。技术选型没有绝对的对错只有适不适合你的场景。最后说一句学Agent开发动手比看书重要一百倍。你看十篇教程不如自己写一个能跑起来的Demo。你调一百次API不如自己踩一次工具调用失败的坑然后把它解决掉。这个系列会给你地图和工具但路要你自己走。准备好了的话下一篇我们就从LLM的基础和API调用开始。
