AI Agent 这个词在过去一年里被反复提起但真正动手做过一个能跑起来的 Agent 的人其实没那么多。我见过太多新手和转行者一上来就打开 LangChain 的官方文档照着 QuickStart 敲了三十行代码跑出来一个只会复读的聊天机器人然后就卡住了——不知道该往哪走也不知道自己缺的到底是什么。问题不在于框架难而在于顺序错了。这篇内容就是想把先学什么、后学什么、什么阶段再碰框架这条路径讲清楚适合完全没接触过 AI Agent 的新手、想从传统开发转过来的工程师以及被各种框架名词绕晕的观望者。我会结合 Python 基础、LangChain、Spring AI、MCP 这些高频关键词把每一步该做什么、为什么这么做、容易踩什么坑都摊开讲。1. 先搞清楚 AI Agent 到底在解决什么问题1.1 从会聊天到会干活的那条分界线很多人对 AI Agent 的第一印象来自各种演示视频你说一句话它自己打开浏览器、查资料、写文件、发消息全程不用你插手。这种自主完成任务的能力才是 Agent 和普通聊天机器人的本质区别。普通的大模型对话本质是输入一段文字输出一段文字它没有记忆之外的行动能力也不会主动去调用外部工具。而 Agent 的核心在于它有一个循环决策机制观察当前状态、决定下一步动作、执行动作、再观察结果直到任务完成。这个循环听起来简单但它是整个 Agent 领域的地基。你后面接触到的 LangChain、LangGraph、CrewAI、Dify不管包装得多花哨底层都是这个思考-行动-观察的循环在转。所以新手第一步不是去学某个框架的 API而是先在脑子里把这个循环跑通。你可以用最朴素的方式理解它Agent 就是一个不断问自己我现在该干什么的程序而大模型负责回答这个问题。为什么这一点这么重要因为一旦你理解了循环你就能看懂所有框架在做什么。LangChain 的 AgentExecutor 是在帮你管理这个循环LangGraph 是把循环画成图让你能控制分支MCP 是给这个循环提供标准化的工具接口。如果你不理解循环本身看这些框架就像看天书只能照抄示例一旦需求变了就完全不会改。1.2 一个 Agent 最少需要哪几个零件抛开框架一个能干活的最小 Agent 其实只有四个部分大模型、提示词、工具、循环控制。大模型是大脑负责推理和决策提示词是说明书告诉它有哪些工具可用、当前任务是什么工具是手脚让它能真正对外部世界产生影响循环控制是调度员决定什么时候继续、什么时候停。我建议每个新手都先用纯 Python 手写一遍这个最小结构不借助任何框架。比如你要做一个查天气并提醒带伞的 Agent可以这样设计给模型一个工具叫get_weather(city)提示词里写清楚如果用户问天气先调用 get_weather再根据结果判断是否需要带伞。然后写一个 while 循环让模型输出它想调用的工具你解析出来执行把结果塞回对话历史再让模型继续。这个过程可能只有五六十行代码但它能让你彻底明白 Agent 是怎么运转的。手写一遍之后你再去看 LangChain 的文档会有一种原来它只是帮我封装了这些的感觉。这种掌控感是直接啃框架永远给不了的。而且手写过程中你会自然遇到很多真实问题模型输出的工具调用格式不稳定怎么办、工具报错了怎么让模型知道、循环什么时候该强制终止。这些问题在框架里都被隐藏了但它们是 Agent 开发的核心难点早遇到早受益。1.3 为什么先啃框架是新手最容易走的弯路我见过最典型的失败路径是这样的新手听说 LangChain 很火直接 clone 官方仓库跑通了一个 ReAct 示例觉得自己入门了。然后想改一改比如换一个工具、加一个判断逻辑结果发现完全不知道从哪下手因为他不理解 AgentExecutor 内部发生了什么。于是他开始翻源码但源码里又牵扯到 Chain、Runnable、Callback 一大堆抽象越看越晕最后放弃。这条弯路的核心问题是抽象泄漏。框架为了通用性把很多细节封装成了抽象层但这些抽象层是建立在你已经理解底层的前提上的。就像学开车你可以直接上路但如果你连油门刹车的作用都不知道遇到紧急情况就会慌。Agent 框架也是一样它假设你知道什么是工具调用、什么是对话历史、什么是停止条件然后帮你把这些组织起来。如果你不知道框架就成了黑箱。所以我的建议很明确先用纯代码手写一个能跑的最小 Agent再带着问题去学框架。这时候你学 LangChain 不是从零学一个陌生东西而是看看别人是怎么把我手写的那套东西做得更优雅的。心态和效率完全不一样。2. Python 基础要打到什么程度才算够用2.1 不需要成为 Python 高手但这几样必须熟转行者最容易犯的错是觉得我要先把 Python 学完再碰 Agent。这个想法听起来稳妥实际上会让你在基础语法上耗掉几个月等真正开始做 Agent 时前面学的东西又忘得差不多了。我的经验是Python 只需要学到能读写文件、能发网络请求、能处理 JSON 的程度就可以开始做 Agent 了。具体来说你需要熟练掌握这几样函数的定义和调用、字典和列表的嵌套操作、for和while循环、异常处理try/except、以及import机制。这些是 Agent 代码里出现频率最高的语法。至于类、继承、装饰器、生成器这些进阶特性可以在做的过程中遇到再学不需要提前啃完。我特别想强调字典操作的重要性。Agent 和大模型交互的数据格式几乎全是 JSON而 JSON 在 Python 里就是字典。你要能熟练地从嵌套字典里取值、构造请求体、解析响应。比如模型返回的{tool: get_weather, args: {city: 北京}}你要能一眼看出怎么取出city的值。这个能力不过关后面写工具调用会非常痛苦。2.2 环境搭建python 安装和依赖管理那些事环境这块新手最常卡在三个地方Python 版本、包管理、虚拟环境。先说版本建议直接用 Python 3.10 或 3.11。3.8 虽然还能用但很多新库已经不支持了3.12 有些库的兼容性还在磨合。3.10 是目前生态最稳的选择LangChain、各种 SDK 都支持得很好。安装 Python 本身Windows 用户去 python 官网下载安装包时一定要勾选Add Python to PATH这个选项不勾后面在命令行里敲python会提示找不到命令很多人卡在这里半天。macOS 用户可以用 Homebrew 装Linux 用户注意系统自带的 Python 可能被系统工具依赖不要随便替换建议单独装一个版本。依赖管理我强烈建议用虚拟环境别把包装到全局。最省事的方式是用venvpython -m venv agent-env source agent-env/bin/activate # Windows 用 agent-env\Scripts\activate pip install requests openai虚拟环境的好处是每个项目独立不会出现 A 项目要 langchain 0.1、B 项目要 0.2 的冲突。我见过太多人因为全局装了一堆包最后依赖冲突到只能重装系统这个坑完全可以避免。2.3 网络请求和 JSON 处理Agent 开发的两条腿Agent 和大模型通信本质就是发 HTTP 请求。所以requests库或者httpx库你必须会用。至少要能写出这样的代码构造一个带 headers 和 body 的 POST 请求拿到响应后解析 JSON。这个能力是后面所有工作的基础因为不管用什么框架底层都是这个。JSON 处理方面json.dumps()和json.loads()要烂熟于心。dumps是把 Python 字典转成字符串loads是把字符串转回字典。Agent 开发里你会频繁在这两种格式之间转换比如把工具的定义转成 JSON 塞进提示词再把模型返回的 JSON 字符串解析成字典去执行。这里有个常见坑模型返回的 JSON 有时候会带 markdown 代码块标记比如json ...直接loads会报错你需要先做字符串清洗。这个坑我在第 4 节会详细讲。另外处理中文时注意编码问题。json.dumps()默认会把中文转成\uXXXX的形式加个ensure_asciiFalse就能保留中文调试的时候看着舒服很多。3. 提示词工程Agent 的操作系统3.1 为什么提示词在 Agent 里比在聊天里更重要普通聊天场景下提示词写得好不好影响的是回答质量。但在 Agent 场景下提示词直接决定了Agent 能不能正确调用工具、能不能在合适的时机停下来。它更像是 Agent 的操作系统规定了行为边界和决策逻辑。一个 Agent 的系统提示词通常要包含这几块内容角色定义你是谁、可用工具列表你能用什么、工具调用格式怎么调用、决策规则什么情况用什么工具、停止条件什么时候算完成。这五块缺一不可。我见过很多新手写的提示词只有角色定义结果模型根本不知道有哪些工具可用自然也就不会调用。写 Agent 提示词有个核心原则把模型当成一个聪明但没常识的新员工。你要把规则写得足够明确不能假设它应该知道。比如你不能只写帮用户查天气而要写当用户询问天气时调用 get_weather 工具参数为城市名如果用户没提供城市先询问城市。规则越具体Agent 的行为越稳定。3.2 工具描述怎么写模型才看得懂工具描述是提示词里最容易被忽视、但影响最大的部分。模型决定调用哪个工具完全依赖你给的描述。描述写得含糊模型就会乱调或者不调。一个好的工具描述要回答三个问题这个工具做什么、什么时候用、参数是什么。举个例子同样是查天气的工具差的描述是查询天气好的描述是查询指定城市的当前天气状况返回温度和天气描述。当用户询问某地天气、是否需要带伞、适合穿什么衣服时使用此工具。参数 city 为城市名称如北京。你会发现好的描述里包含了使用场景的提示。这一点很关键因为模型在决策时是靠语义匹配来判断当前任务和工具用途是否吻合的。你把使用场景写进去相当于给了模型更多的匹配线索。我实测下来光是优化工具描述就能让工具调用的准确率提升一大截。还有一个细节参数的类型和是否必填要写清楚。如果某个参数是可选的明确标注可选否则模型可能会为了凑参数而瞎编一个值。这种模型幻觉出参数的问题在参数描述不清时特别常见。3.3 少样本示例让 Agent 学会照着做光靠文字描述规则模型有时候还是拿不准。这时候**少样本示例few-shot**就派上用场了。你可以在提示词里放几个用户问什么、Agent 应该怎么调工具的例子模型会模仿这个模式。比如用户北京今天天气怎么样 助手调用 get_weather(city北京) 用户我想去上海玩要带伞吗 助手调用 get_weather(city上海)然后根据结果判断这两个例子一个直接问天气一个间接问带伞覆盖了两种典型场景。模型看到之后遇到类似问题就知道该怎么处理了。示例不用多两到三个高质量的就行太多反而会占满上下文、增加成本。选示例有个技巧优先选那些容易出错的边界情况。比如用户没提供城市、用户一次问了两个城市、用户问的是未来天气但工具只支持当前天气。把这些难处理的场景做成示例比放一堆简单例子有用得多。4. 手写第一个 Agent不碰框架的完整实战4.1 用最朴素的循环实现思考-行动现在到了最关键的一步手写一个 Agent。我以查天气并给建议为例把完整思路拆开讲。首先你需要一个能调用的大模型接口这里假设你已经有了 API key。核心代码结构是这样的import json import requests def call_llm(messages): # 调用大模型返回文本 response requests.post( 你的模型接口地址, headers{Authorization: Bearer 你的key}, json{messages: messages} ) return response.json()[choices][0][message][content] def get_weather(city): # 模拟天气查询 return f{city}今天晴25度 tools {get_weather: get_weather} messages [ {role: system, content: 你是一个天气助手。当用户问天气时输出 JSON 格式的工具调用{\tool\: \get_weather\, \args\: {\city\: \城市名\}}}, {role: user, content: 北京今天天气怎么样} ] for i in range(5): # 最多循环5次防止死循环 reply call_llm(messages) messages.append({role: assistant, content: reply}) if tool in reply: # 解析工具调用 call_info json.loads(reply) result tools[call_info[tool]](**call_info[args]) messages.append({role: user, content: f工具返回{result}}) else: print(reply) break这段代码虽然简陋但它包含了 Agent 的所有核心要素系统提示词、工具定义、循环控制、结果回填。你把它跑通就真正理解了 Agent 是怎么工作的。4.2 解析模型输出时那些让人抓狂的格式问题上面那段代码跑起来你大概率会遇到第一个坑模型返回的不是纯 JSON。它可能返回好的我来帮你查询{tool: get_weather, ...}也可能用 markdown 代码块包起来。直接json.loads必然报错。处理这个问题有几种思路。最简单的是用正则把 JSON 部分抠出来import re def extract_json(text): match re.search(r\{.*\}, text, re.DOTALL) if match: return json.loads(match.group()) return None但正则也不是万能的如果模型返回的文本里有多个花括号就可能匹配错。更稳的做法是在提示词里强制要求只输出 JSON不要有任何其他文字并且在解析失败时把错误信息回传给模型让它重新输出。这种失败重试机制在 Agent 里非常常见因为模型的输出天然有不确定性你必须做好容错。我个人的经验是提示词约束 正则提取 失败重试三管齐下能覆盖 95% 以上的情况。剩下那 5% 的极端情况可以在解析失败几次后直接给用户报错而不是无限重试。4.3 循环终止Agent 最容易失控的地方Agent 最危险的地方就是循环。如果模型一直觉得任务没完成它就会一直调用工具烧掉你的 token 额度。所以必须设置硬性的终止条件。常见的终止策略有三种最大循环次数比如 10 次、最大 token 消耗、以及检测到重复动作。最大循环次数是最简单可靠的我建议新手先用这个。检测重复动作稍微复杂一点就是记录最近几次的工具调用如果发现完全一样就强制停止因为这说明模型卡住了。还有一个容易被忽视的点模型有时候会假装完成。它可能输出一段我已经帮你查到了天气但实际上根本没调用工具。这种情况在提示词不够明确时特别常见。解决办法是在提示词里强调必须通过工具获取信息不能凭记忆回答并且在代码里检查——如果模型声称完成了但没有任何工具调用记录就提示它重新执行。5. 什么时候该引入框架选哪个5.1 手写方案的瓶颈在哪里手写 Agent 能帮你理解原理但真要做复杂项目很快就会遇到瓶颈。第一个瓶颈是多工具管理当你有十几个工具时手写提示词和解析逻辑会变得非常臃肿。第二个瓶颈是多步推理有些任务需要先查 A根据 A 的结果决定查 B 还是 C这种分支逻辑手写起来很痛苦。第三个瓶颈是状态管理长对话、多轮任务的状态维护手写容易出错。这些瓶颈正是框架要解决的问题。所以引入框架的时机应该是你已经手写过、并且感受到了这些痛点之后。这时候你学框架是带着明确目的的知道每个抽象是为了解决什么问题学起来事半功倍。5.2 LangChain、Spring AI、CrewAI 各自适合谁市面上框架很多新手最容易纠结选哪个。我的看法是没有最好的框架只有最适合你当前场景的。下面这张表可以帮你快速定位框架语言适合场景上手难度LangChainPython/JS快速原型、工具调用、RAG中LangGraphPython/JS复杂分支、多步流程控制中高Spring AIJavaJava 技术栈、企业级集成中CrewAIPython多 Agent 协作中Dify低代码非程序员、快速搭建低如果你是 Python 背景、想做通用 Agent从 LangChain 入手最自然生态最全遇到问题搜得到答案。如果你是 Java 工程师团队技术栈都是 Spring那 Spring AI 更合适它能和你现有的 Spring Boot 项目无缝集成。如果你要做的是一群 Agent 分工协作比如一个负责调研、一个负责写作、一个负责审核CrewAI 的角色定义模型会更顺手。如果你完全不想写代码Dify 这种可视化平台能让你拖拽出可用的 Agent。5.3 从手写到框架的平滑过渡方法从手写切到框架我建议用**重写已有项目**的方式而不是从零学新项目。把你之前手写的那个天气 Agent用 LangChain 重写一遍。你会发现 LangChain 的tool装饰器帮你省掉了工具描述和解析的代码AgentExecutor帮你管好了循环。这时候你对每个抽象的理解都是具体的而不是空洞的。重写过程中重点观察框架帮你做了什么、隐藏了什么。比如 LangChain 的 AgentExecutor 内部其实也是那个 while 循环只是它加了更多的错误处理和回调机制。理解了这一层你就从会用框架进阶到懂框架了遇到框架解决不了的问题你也能自己绕过它。6. MCP 是什么为什么它值得关注6.1 用一句话说清 MCP 的价值MCP 全称 Model Context Protocol翻译过来是模型上下文协议。它的核心价值可以用一句话概括让工具的定义和调用标准化一次编写到处复用。在没有 MCP 之前你给 LangChain 写的工具换到 Spring AI 就得重写一遍因为两个框架的工具接口不一样。MCP 想解决的就是这个问题——它定义了一套标准的工具描述和调用协议任何支持 MCP 的客户端都能调用任何 MCP 服务。这就像 USB 接口统一了各种外设的连接方式一样。对新手来说MCP 的意义在于你写的工具不再绑定某个框架。今天用 LangChain明天换别的工具还能用。而且社区里已经有很多现成的 MCP 服务比如文件操作、数据库查询、浏览器自动化你可以直接拿来用不用自己从头写。6.2 MCP 和传统工具调用的区别在哪传统工具调用是框架私有的。你在 LangChain 里定义工具用的是 LangChain 的格式在别的框架里格式就变了。MCP 把这一层抽出来变成独立的服务。工具不再写在你的 Agent 代码里而是跑在一个独立的 MCP Server 上Agent 通过标准协议去调用它。这个架构带来的好处是解耦。工具的开发者和 Agent 的开发者可以是不同的人甚至不同的团队。工具更新了Agent 不用改代码。这种解耦在大型项目里价值巨大因为工具往往需要维护、需要权限控制、需要独立部署塞在 Agent 代码里会越来越乱。当然MCP 也不是银弹。它引入了额外的网络通信开销对于简单的本地工具直接用框架自带的工具机制可能更轻量。所以我的建议是小项目、本地工具先用框架自带的需要跨框架复用、或者工具需要独立部署时再上 MCP。6.3 新手要不要现在就学 MCP我的答案是理解概念即可不必急着上手。MCP 是趋势但它建立在你已经会写工具、会做 Agent的基础上。如果你连手写 Agent 都还没跑通直接去研究 MCP 协议会陷入不知道它解决什么问题的困惑。正确的顺序是先手写 Agent 理解工具调用再用框架熟练工具开发最后在遇到工具需要跨框架复用的真实需求时自然过渡到 MCP。这时候你学 MCP 是带着问题的效率最高。现在你只需要知道MCP 是工具标准化的协议未来会越来越重要就够了不用现在就啃它的规范文档。7. 转行者的学习节奏和常见心态陷阱7.1 每天两小时四周能到什么程度我给转行者一个具体的时间预期帮你判断自己是不是走在正轨上。假设你每天能投入两小时第一周搞定 Python 环境和基础语法能写出调用 API、处理 JSON 的脚本。第二周手写一个最小 Agent理解循环和工具调用能处理模型输出的格式问题。第三周学 LangChain 基础用框架重写之前的 Agent理解工具、Chain、AgentExecutor 的关系。第四周做一个完整的小项目比如自动整理文件夹或根据关键词查资料并总结把前面学的串起来。四周之后你算不上专家但已经能独立做出可用的 Agent 了。剩下的就是靠项目积累经验。这个节奏不算快但胜在扎实不会出现学完就忘的情况。7.2 学不完的焦虑怎么破AI 领域更新太快今天出个新框架明天出个新协议很容易让人产生我永远学不完的焦虑。我的应对方法是只学能立刻用上的其余的先记个名字。比如你看到一个新框架先问自己我现在的项目需要它吗不需要就记下名字等真遇到了再学。技术是学不完的但底层原理是有限的。Agent 的核心就是那个思考-行动-观察的循环工具调用、提示词、循环控制这些底层能力换个框架还是这些。把底层打牢上层的东西学起来都很快。7.3 别陷入收藏即学会的陷阱最后一个坑也是我自己踩过的收藏了一堆教程、文档、视频但真正动手的时间很少。看教程的时候觉得懂了一写代码就卡壳。这是因为看和做调用的是不同的大脑区域看懂不等于会做。我的建议是每学一个概念立刻写代码验证。学工具调用就手写一个学提示词就改一改看效果学框架就用它重写一个旧项目。动手过程中遇到的每一个报错都是真正让你进步的机会。收藏夹里的东西不会变成你的能力只有敲过的代码才会。我在实际带新人的过程中发现那些进步快的往往不是基础最好的而是动手最勤的。他们不怕报错遇到问题就查、就问、就试几周下来就能独立做项目。而那些一直在准备学习的人几个月过去还在纠结该先学哪个框架。Agent 这个领域动手永远比观望有用。