1. 为什么我不建议新手一上来就啃 LangChain1.1 一个真实的学习路径翻车案例去年带过一个转行学 AI 的朋友他之前做前端看到 AI Agent 火第一反应就是去 GitHub 搜 star 最多的框架然后一头扎进 LangChain 的源码里。两周之后他跟我说看懂了 Chain、AgentExecutor、Tool 这些类的关系但完全不知道这些东西能拿来干什么写出来的 demo 跑起来报错都不知道从哪查。这个现象太普遍了。问题不在于 LangChain 不好而在于框架是别人抽象出来的结果不是学习的起点。你直接学结果就像学做菜先背菜谱的排版格式而不是先认识食材和火候。AI Agent 的本质是什么一句话让大模型在循环里调用工具根据工具返回的结果决定下一步做什么直到任务完成。这个循环叫 ReActReasoning Acting核心就三步——想、做、看。你把这个循环用最朴素的 Python 写一遍比看十遍 LangChain 文档都管用。1.2 框架帮你省了什么又藏了什么先搞清楚框架到底做了什么你才知道该不该现在学它。框架能力你手写要处理的事框架帮你做的提示词模板字符串拼接、变量注入PromptTemplate 封装工具调用JSON Schema 定义、参数解析、异常捕获Tool 抽象 自动解析多轮循环while 循环 终止条件判断AgentExecutor 托管记忆管理上下文裁剪、历史压缩Memory 组件模型适配不同厂商 API 格式差异LLM 统一接口框架确实省事但它把控制流藏起来了。新手最需要建立的恰恰是对控制流的直觉什么时候该调工具、工具返回什么格式、模型为什么决定停止。这些直觉没建立起来你用框架就是黑盒调参出了问题只能靠猜。我的建议很直接先用 100 行以内的原生 Python 手写一个能查天气、能算数的 Agent跑通完整循环再去碰框架。这一步花不了三天但能帮你省下三个月的迷茫。1.3 那到底该先学什么按优先级排我给新手的顺序是这样的Python 基础够用就行——函数、字典、列表、异常处理、requests发请求、json解析。不需要会元类、装饰器原理、异步高级用法。大模型 API 的基本调用——知道 messages 结构、system/user/assistant 角色、temperature 和 max_tokens 是什么。手写一个 ReAct 循环——这是核心中的核心。理解工具调用的协议——模型怎么知道有哪些工具、怎么输出调用意图、你怎么把结果喂回去。最后才是框架——LangChain、LangGraph、Spring AI 挑一个深入。这个顺序的道理很简单先有体感再有工具。你手写过循环再看 LangChain 的 AgentExecutor 就知道它在替你干什么你手写过工具定义再看 MCP 就明白它想标准化什么。2. 手写第一个 Agent把黑盒拆开看2.1 最小可运行版本长什么样先别管框架我们用一个最朴素的思路实现 Agent。核心逻辑就一个 while 循环import json def run_agent(user_input, max_steps5): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for step in range(max_steps): # 1. 让模型思考并决定下一步 response call_llm(messages) messages.append({role: assistant, content: response}) # 2. 检查模型是否要调用工具 action parse_action(response) if action is None: # 没有工具调用说明任务结束 return response # 3. 执行工具把结果喂回去 tool_result execute_tool(action[name], action[args]) messages.append({ role: user, content: f工具返回结果{tool_result} }) return 达到最大步数限制这三十行代码就是 Agent 的骨架。max_steps是防止死循环的保险丝parse_action负责从模型输出里提取工具调用意图execute_tool负责真正执行。2.2 提示词怎么写才能让模型乖乖调工具新手最容易翻车的地方在这里。你直接问模型北京天气怎么样它可能凭训练数据瞎编一个温度给你根本不调工具。你得在 system prompt 里把规则说死你是一个可以使用工具的助手。可用工具如下 工具名get_weather 功能查询指定城市的实时天气 参数city (字符串城市名) 当你需要查询天气时必须严格按以下 JSON 格式输出不要输出其他内容 {action: get_weather, args: {city: 北京}} 当你已经获得足够信息可以回答用户时直接输出最终答案不要输出 JSON。关键点有三个明确工具清单、规定输出格式、区分调工具和给答案两种状态。模型不是天生就会这套的你得把规则喂到它嘴边。实操心得格式约束越严格模型越听话。我试过用自然语言描述你可以调用工具模型十次有三次不按格式来改成必须严格按以下 JSON 格式输出成功率直接上到九成以上。2.3 工具函数怎么写才不容易崩工具函数是 Agent 的手脚写不好整个循环就废了。几个硬性要求参数校验必须做。模型可能传个空字符串、传个不存在的城市名你不校验就直接崩。异常要捕获并返回文本。工具抛异常不要往外扔要 catch 住返回一句查询失败城市名无效让模型自己决定重试还是换方案。返回值要简洁。别把整个 API 响应塞回去模型上下文有限返回关键字段就行。def get_weather(city): if not city or not isinstance(city, str): return 错误城市名无效 try: # 这里换成你实际的数据源 data fetch_weather_api(city) return f{city}当前温度{data[temp]}度{data[desc]} except Exception as e: return f查询失败{str(e)}这套写法看起来啰嗦但它决定了你的 Agent 是偶尔能用还是稳定能用。我见过太多 demo 在理想输入下跑得飞起用户随便输点奇怪的东西就整个崩掉。2.4 循环终止条件怎么设计终止条件设计不好要么提前退出要么无限循环烧钱。我的经验是三层保险第一层模型主动结束。模型输出不含 JSON 格式的工具调用就认为它要直接回答退出循环。第二层步数上限。设个max_steps一般 5 到 10 步足够。超过就强制退出返回当前已有信息。第三层重复检测。如果连续两次调用同一个工具、同样的参数说明模型卡住了直接中断。last_action None for step in range(max_steps): action parse_action(response) if action and action last_action: return 检测到重复操作已中断 last_action action这三层加起来你的 Agent 就不会出现跑了二十分钟还在转的尴尬场面。别小看这个线上环境里一次失控的循环可能就是几十块的 API 账单。3. 从手写到框架LangChain 和 Spring AI 该怎么选3.1 什么时候该上框架手写循环能跑通之后你会遇到几个手写很难受的场景工具有二十个每次都要手动拼 JSON Schema烦。需要多轮对话记忆自己管理上下文裁剪逻辑很累。想接入不同的模型厂商每家 API 格式都不一样。需要可视化调试看每一步的输入输出。这时候框架的价值就出来了。框架不是用来学概念的是用来解决工程问题的。你概念清楚了用框架就是提效概念不清楚用框架就是给自己挖坑。3.2 LangChain 和 Spring AI 的定位差异这两个经常被放在一起比但其实面向的人群不太一样。维度LangChainSpring AI语言生态Python 为主Java 为主适合人群数据、算法、快速原型后端工程师、企业应用抽象程度高组件多中贴近 Spring 风格学习曲线组件多容易迷路对 Java 开发者友好典型场景实验、Demo、研究生产系统集成如果你是 Python 背景、想快速试各种玩法LangChain 生态更全。如果你是 Java 后端、要把 Agent 能力嵌进现有系统Spring AI 的接入成本更低注解风格和 Spring 一脉相承。LangGraph 是 LangChain 团队后来推出的专门解决复杂流程编排。普通 Agent 用 LangChain 的 AgentExecutor 就够一旦你的流程有分支、有循环、有多个 Agent 协作LangGraph 的图结构会比链式调用清晰得多。但别一上来就用 LangGraph它是给已经踩过链式调用坑的人准备的。3.3 MCP 到底解决了什么问题MCPModel Context Protocol是这两年被讨论很多的协议。用一句话解释它想让工具这件事标准化让工具的定义和调用跟具体框架解耦。在手写方案里你的工具是写死在代码里的函数。换一个框架工具定义要重写一遍。MCP 的思路是把工具做成独立的服务通过统一协议暴露出去任何支持 MCP 的客户端都能调用。这对新手意味着什么意味着你不需要为了学 MCP 而学 MCP。先把工具调用的本质搞懂——无非是告诉模型有哪些工具、模型输出调用意图、你执行并返回结果——MCP 只是把这套东西标准化了。你理解了本质看 MCP 的文档半小时就能上手。常见误区很多新手以为 MCP 是某种新技术其实它是协议不是框架。它解决的是互操作问题不是能力问题。你的 Agent 不会因为用了 MCP 就变聪明只会因为用了 MCP 而更容易接入别人的工具。3.4 选型决策的实操建议我给的建议是按目标倒推纯学习、想搞懂原理手写循环别用框架。快速做个能演示的 DemoLangChain组件现成。Java 项目要集成Spring AI。复杂多步流程、多 Agent 协作LangGraph。要接入大量第三方工具关注 MCP 生态。别纠结哪个框架最好这个问题没有答案。框架是消耗品能力是资产。你把 Agent 的循环、工具调用、上下文管理这三件事吃透换任何框架都是几天的事。4. 新手最容易踩的五个坑4.1 坑一把提示词工程当成玄学很多人调提示词靠感觉改一版跑一次好了就留着坏了就再改。这是低效的。提示词是有结构的角色定义、任务描述、约束条件、输出格式、示例。缺哪块补哪块比瞎试快得多。我习惯把提示词拆成模板每个部分单独调。比如输出格式不对就只改格式那段其他不动。这样你能定位到底是哪句话在起作用。4.2 坑二工具描述写得太随意工具能不能被正确调用八成取决于描述写得好不好。模型看不到你的函数实现只能看描述。描述里要包含这个工具干什么、什么时候用、参数是什么含义、返回什么。反例查询数据。模型根本不知道查什么数据、什么时候该用。正例根据订单号查询订单状态。当用户询问某个订单的物流、支付或退款状态时使用。参数 order_id 为字符串格式的订单编号。4.3 坑三忽略 token 成本Agent 每循环一次整个对话历史都要重新发给模型。步数一多token 消耗是线性增长的。我见过一个 Agent 单次任务烧掉几万 token就是因为历史没裁剪。处理办法只保留最近几轮对话或者对历史做摘要压缩。LangChain 的 Memory 组件就是干这个的但手写也不难——超过 N 轮就把前面的对话总结成一句话。4.4 坑四不做错误兜底模型会输出格式错误、工具会超时、API 会限流。这些不是异常情况是常态。你的代码必须假设每一步都可能失败然后决定失败后怎么办重试、换工具、还是直接告诉用户。4.5 坑五过早追求多 Agent 协作新手看到多 Agent 系统就兴奋想搞一堆 Agent 互相聊天。实际上大部分任务单 Agent 加几个工具就能解决。多 Agent 带来的通信开销、状态同步、调试难度远超它带来的收益。等你单 Agent 真的遇到瓶颈了再考虑多 Agent。5. 一份可执行的学习路线5.1 第一周打地基Python 基础过一遍重点练函数、字典、异常处理、requests和json。然后注册一个大模型 API写个最简单的对话脚本能发消息、能收回复。这一步的目标是打通调用链路别追求功能。5.2 第二周手写 Agent按第 2 节的思路手写一个带两三个工具的 Agent。工具可以很简单查天气、算数学、查时间。重点是把循环、工具调用、终止条件跑通。跑通之后故意制造错误——传错参数、让工具抛异常——看你的代码怎么反应。5.3 第三周引入框架挑 LangChain 或 Spring AI把你手写的 Agent 用框架重写一遍。对比一下框架帮你省了哪些代码、哪些地方你反而觉得不透明。这个对比过程本身就是最好的学习。5.4 第四周接触 MCP 和进阶理解 MCP 的协议设计试着把一个工具做成 MCP 服务再用客户端调用它。如果还有余力看看 LangGraph 怎么做流程编排。5.5 学习资源的选择原则网上资源鱼龙混杂我的筛选标准是优先看官方文档和能跑通的代码少看纯概念讲解。官方文档更新最快、最准能跑通的代码给你真实反馈。那些三分钟搞懂 AI Agent的文章看完你还是不会写。最后分享一个我自己的习惯每学一个新概念就逼自己用最朴素的方式实现一遍。学 RAG 就手写一遍检索加拼接学 Agent 就手写一遍循环。手写过的知识才是你的看过的只是别人的。这个领域变化快框架半年一换但底层的东西——循环、工具、上下文、错误处理——几年都不会变。把时间花在这些不变的东西上比追框架版本号划算得多。 
长河君 · 2026/10/26 14:29:46 · 阅读 1.2k AI Agent 新手学习路径：从手写 ReAct 循环到 LangChain 与 Spring AI 选型
1. 为什么我不建议新手一上来就啃 LangChain1.1 一个真实的学习路径翻车案例去年带过一个转行学 AI 的朋友他之前做前端看到 AI Agent 火第一反应就是去 GitHub 搜 star 最多的框架然后一头扎进 LangChain 的源码里。两周之后他跟我说看懂了 Chain、AgentExecutor、Tool 这些类的关系但完全不知道这些东西能拿来干什么写出来的 demo 跑起来报错都不知道从哪查。这个现象太普遍了。问题不在于 LangChain 不好而在于框架是别人抽象出来的结果不是学习的起点。你直接学结果就像学做菜先背菜谱的排版格式而不是先认识食材和火候。AI Agent 的本质是什么一句话让大模型在循环里调用工具根据工具返回的结果决定下一步做什么直到任务完成。这个循环叫 ReActReasoning Acting核心就三步——想、做、看。你把这个循环用最朴素的 Python 写一遍比看十遍 LangChain 文档都管用。1.2 框架帮你省了什么又藏了什么先搞清楚框架到底做了什么你才知道该不该现在学它。框架能力你手写要处理的事框架帮你做的提示词模板字符串拼接、变量注入PromptTemplate 封装工具调用JSON Schema 定义、参数解析、异常捕获Tool 抽象 自动解析多轮循环while 循环 终止条件判断AgentExecutor 托管记忆管理上下文裁剪、历史压缩Memory 组件模型适配不同厂商 API 格式差异LLM 统一接口框架确实省事但它把控制流藏起来了。新手最需要建立的恰恰是对控制流的直觉什么时候该调工具、工具返回什么格式、模型为什么决定停止。这些直觉没建立起来你用框架就是黑盒调参出了问题只能靠猜。我的建议很直接先用 100 行以内的原生 Python 手写一个能查天气、能算数的 Agent跑通完整循环再去碰框架。这一步花不了三天但能帮你省下三个月的迷茫。1.3 那到底该先学什么按优先级排我给新手的顺序是这样的Python 基础够用就行——函数、字典、列表、异常处理、requests发请求、json解析。不需要会元类、装饰器原理、异步高级用法。大模型 API 的基本调用——知道 messages 结构、system/user/assistant 角色、temperature 和 max_tokens 是什么。手写一个 ReAct 循环——这是核心中的核心。理解工具调用的协议——模型怎么知道有哪些工具、怎么输出调用意图、你怎么把结果喂回去。最后才是框架——LangChain、LangGraph、Spring AI 挑一个深入。这个顺序的道理很简单先有体感再有工具。你手写过循环再看 LangChain 的 AgentExecutor 就知道它在替你干什么你手写过工具定义再看 MCP 就明白它想标准化什么。2. 手写第一个 Agent把黑盒拆开看2.1 最小可运行版本长什么样先别管框架我们用一个最朴素的思路实现 Agent。核心逻辑就一个 while 循环import json def run_agent(user_input, max_steps5): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for step in range(max_steps): # 1. 让模型思考并决定下一步 response call_llm(messages) messages.append({role: assistant, content: response}) # 2. 检查模型是否要调用工具 action parse_action(response) if action is None: # 没有工具调用说明任务结束 return response # 3. 执行工具把结果喂回去 tool_result execute_tool(action[name], action[args]) messages.append({ role: user, content: f工具返回结果{tool_result} }) return 达到最大步数限制这三十行代码就是 Agent 的骨架。max_steps是防止死循环的保险丝parse_action负责从模型输出里提取工具调用意图execute_tool负责真正执行。2.2 提示词怎么写才能让模型乖乖调工具新手最容易翻车的地方在这里。你直接问模型北京天气怎么样它可能凭训练数据瞎编一个温度给你根本不调工具。你得在 system prompt 里把规则说死你是一个可以使用工具的助手。可用工具如下 工具名get_weather 功能查询指定城市的实时天气 参数city (字符串城市名) 当你需要查询天气时必须严格按以下 JSON 格式输出不要输出其他内容 {action: get_weather, args: {city: 北京}} 当你已经获得足够信息可以回答用户时直接输出最终答案不要输出 JSON。关键点有三个明确工具清单、规定输出格式、区分调工具和给答案两种状态。模型不是天生就会这套的你得把规则喂到它嘴边。实操心得格式约束越严格模型越听话。我试过用自然语言描述你可以调用工具模型十次有三次不按格式来改成必须严格按以下 JSON 格式输出成功率直接上到九成以上。2.3 工具函数怎么写才不容易崩工具函数是 Agent 的手脚写不好整个循环就废了。几个硬性要求参数校验必须做。模型可能传个空字符串、传个不存在的城市名你不校验就直接崩。异常要捕获并返回文本。工具抛异常不要往外扔要 catch 住返回一句查询失败城市名无效让模型自己决定重试还是换方案。返回值要简洁。别把整个 API 响应塞回去模型上下文有限返回关键字段就行。def get_weather(city): if not city or not isinstance(city, str): return 错误城市名无效 try: # 这里换成你实际的数据源 data fetch_weather_api(city) return f{city}当前温度{data[temp]}度{data[desc]} except Exception as e: return f查询失败{str(e)}这套写法看起来啰嗦但它决定了你的 Agent 是偶尔能用还是稳定能用。我见过太多 demo 在理想输入下跑得飞起用户随便输点奇怪的东西就整个崩掉。2.4 循环终止条件怎么设计终止条件设计不好要么提前退出要么无限循环烧钱。我的经验是三层保险第一层模型主动结束。模型输出不含 JSON 格式的工具调用就认为它要直接回答退出循环。第二层步数上限。设个max_steps一般 5 到 10 步足够。超过就强制退出返回当前已有信息。第三层重复检测。如果连续两次调用同一个工具、同样的参数说明模型卡住了直接中断。last_action None for step in range(max_steps): action parse_action(response) if action and action last_action: return 检测到重复操作已中断 last_action action这三层加起来你的 Agent 就不会出现跑了二十分钟还在转的尴尬场面。别小看这个线上环境里一次失控的循环可能就是几十块的 API 账单。3. 从手写到框架LangChain 和 Spring AI 该怎么选3.1 什么时候该上框架手写循环能跑通之后你会遇到几个手写很难受的场景工具有二十个每次都要手动拼 JSON Schema烦。需要多轮对话记忆自己管理上下文裁剪逻辑很累。想接入不同的模型厂商每家 API 格式都不一样。需要可视化调试看每一步的输入输出。这时候框架的价值就出来了。框架不是用来学概念的是用来解决工程问题的。你概念清楚了用框架就是提效概念不清楚用框架就是给自己挖坑。3.2 LangChain 和 Spring AI 的定位差异这两个经常被放在一起比但其实面向的人群不太一样。维度LangChainSpring AI语言生态Python 为主Java 为主适合人群数据、算法、快速原型后端工程师、企业应用抽象程度高组件多中贴近 Spring 风格学习曲线组件多容易迷路对 Java 开发者友好典型场景实验、Demo、研究生产系统集成如果你是 Python 背景、想快速试各种玩法LangChain 生态更全。如果你是 Java 后端、要把 Agent 能力嵌进现有系统Spring AI 的接入成本更低注解风格和 Spring 一脉相承。LangGraph 是 LangChain 团队后来推出的专门解决复杂流程编排。普通 Agent 用 LangChain 的 AgentExecutor 就够一旦你的流程有分支、有循环、有多个 Agent 协作LangGraph 的图结构会比链式调用清晰得多。但别一上来就用 LangGraph它是给已经踩过链式调用坑的人准备的。3.3 MCP 到底解决了什么问题MCPModel Context Protocol是这两年被讨论很多的协议。用一句话解释它想让工具这件事标准化让工具的定义和调用跟具体框架解耦。在手写方案里你的工具是写死在代码里的函数。换一个框架工具定义要重写一遍。MCP 的思路是把工具做成独立的服务通过统一协议暴露出去任何支持 MCP 的客户端都能调用。这对新手意味着什么意味着你不需要为了学 MCP 而学 MCP。先把工具调用的本质搞懂——无非是告诉模型有哪些工具、模型输出调用意图、你执行并返回结果——MCP 只是把这套东西标准化了。你理解了本质看 MCP 的文档半小时就能上手。常见误区很多新手以为 MCP 是某种新技术其实它是协议不是框架。它解决的是互操作问题不是能力问题。你的 Agent 不会因为用了 MCP 就变聪明只会因为用了 MCP 而更容易接入别人的工具。3.4 选型决策的实操建议我给的建议是按目标倒推纯学习、想搞懂原理手写循环别用框架。快速做个能演示的 DemoLangChain组件现成。Java 项目要集成Spring AI。复杂多步流程、多 Agent 协作LangGraph。要接入大量第三方工具关注 MCP 生态。别纠结哪个框架最好这个问题没有答案。框架是消耗品能力是资产。你把 Agent 的循环、工具调用、上下文管理这三件事吃透换任何框架都是几天的事。4. 新手最容易踩的五个坑4.1 坑一把提示词工程当成玄学很多人调提示词靠感觉改一版跑一次好了就留着坏了就再改。这是低效的。提示词是有结构的角色定义、任务描述、约束条件、输出格式、示例。缺哪块补哪块比瞎试快得多。我习惯把提示词拆成模板每个部分单独调。比如输出格式不对就只改格式那段其他不动。这样你能定位到底是哪句话在起作用。4.2 坑二工具描述写得太随意工具能不能被正确调用八成取决于描述写得好不好。模型看不到你的函数实现只能看描述。描述里要包含这个工具干什么、什么时候用、参数是什么含义、返回什么。反例查询数据。模型根本不知道查什么数据、什么时候该用。正例根据订单号查询订单状态。当用户询问某个订单的物流、支付或退款状态时使用。参数 order_id 为字符串格式的订单编号。4.3 坑三忽略 token 成本Agent 每循环一次整个对话历史都要重新发给模型。步数一多token 消耗是线性增长的。我见过一个 Agent 单次任务烧掉几万 token就是因为历史没裁剪。处理办法只保留最近几轮对话或者对历史做摘要压缩。LangChain 的 Memory 组件就是干这个的但手写也不难——超过 N 轮就把前面的对话总结成一句话。4.4 坑四不做错误兜底模型会输出格式错误、工具会超时、API 会限流。这些不是异常情况是常态。你的代码必须假设每一步都可能失败然后决定失败后怎么办重试、换工具、还是直接告诉用户。4.5 坑五过早追求多 Agent 协作新手看到多 Agent 系统就兴奋想搞一堆 Agent 互相聊天。实际上大部分任务单 Agent 加几个工具就能解决。多 Agent 带来的通信开销、状态同步、调试难度远超它带来的收益。等你单 Agent 真的遇到瓶颈了再考虑多 Agent。5. 一份可执行的学习路线5.1 第一周打地基Python 基础过一遍重点练函数、字典、异常处理、requests和json。然后注册一个大模型 API写个最简单的对话脚本能发消息、能收回复。这一步的目标是打通调用链路别追求功能。5.2 第二周手写 Agent按第 2 节的思路手写一个带两三个工具的 Agent。工具可以很简单查天气、算数学、查时间。重点是把循环、工具调用、终止条件跑通。跑通之后故意制造错误——传错参数、让工具抛异常——看你的代码怎么反应。5.3 第三周引入框架挑 LangChain 或 Spring AI把你手写的 Agent 用框架重写一遍。对比一下框架帮你省了哪些代码、哪些地方你反而觉得不透明。这个对比过程本身就是最好的学习。5.4 第四周接触 MCP 和进阶理解 MCP 的协议设计试着把一个工具做成 MCP 服务再用客户端调用它。如果还有余力看看 LangGraph 怎么做流程编排。5.5 学习资源的选择原则网上资源鱼龙混杂我的筛选标准是优先看官方文档和能跑通的代码少看纯概念讲解。官方文档更新最快、最准能跑通的代码给你真实反馈。那些三分钟搞懂 AI Agent的文章看完你还是不会写。最后分享一个我自己的习惯每学一个新概念就逼自己用最朴素的方式实现一遍。学 RAG 就手写一遍检索加拼接学 Agent 就手写一遍循环。手写过的知识才是你的看过的只是别人的。这个领域变化快框架半年一换但底层的东西——循环、工具、上下文、错误处理——几年都不会变。把时间花在这些不变的东西上比追框架版本号划算得多。