我见过太多人学 AI Agent，三个月后回到原点。
不是因为不够努力。他们很努力------GitHub 收藏夹里躺着十几个教程，掘金热榜上的文章一篇不落，LangChain 的 @tool 装饰器用得比谁都熟。但一到真实场景，Agent 要么不调工具，要么调错了工具，要么在死循环里反复调用同一个函数直到 token 烧光。
这不是能力问题。是学的顺序错了。
国内的 Agent 教程，十个有八个让你直接上手 LangChain。装包、写 chain、搭 demo，看起来很爽------一个下午就做出了"能对话的 Agent"。但这就好比教你开车先教自动挡，等哪天车在高速上挂了，你连离合器在哪都不知道。
2026 年的 Agent 开发已经是另一回事了。框架生态在你还没反应过来的时候就变了天------MCP 协议成了工具集成的默认标准，OpenAI 和 Google 都把自己的 Agent SDK 推到了前台，LangChain 从"唯一选择"变成了"学习阶段的好老师，但生产环境大家在跑路"。你要是只学过 LangChain 的 @tool，面试官随口问一句"finish_reason 和 tool_choice 是什么关系"，你就只能干瞪眼。
这不是危言耸听。腾讯和字节跳动 2026 年最新的 Agent 工程师 JD，技能要求第一条就是"深入理解 LLM Function Calling、Tool Use、MCP 协议"。注意，是"深入理解"，不是"熟练使用 LangChain"。
这个系列要解决的，就是这个"理解"的问题。
先看一个翻车现场
你用 LangChain 写了一个 Agent，给它配了个天气查询工具。代码大概长这样：
python
@tool
def get_weather(city: str) -> str:
"""查询指定城市的天气"""
return f"{city}今天晴天，25度"
agent = create_agent(llm, [get_weather])
agent.invoke("北京今天热不热？")看起来没问题。但你跑了几次之后发现，Agent 有时候回复"北京今天晴，25 度"，有时候回复"抱歉，我没有查询天气的能力"。
同一个工具、同一条消息、同一个模型。为什么有时调工具有时不调？
答案藏在你没看到的两个参数里：finish_reason 和 tool_choice。
finish_reason 告诉你 LLM 为什么停下了------是觉得该回复了（stop），还是觉得该调个工具（tool_calls）。tool_choice 控制的是 LLM 的"调用意愿"------设为 auto，模型自己判断要不要调；设为 required，模型必须调一个。
问题出在 auto。LLM 是个概率系统，同样的输入不保证同样的输出。你写 tool_choice="auto"，模型有时候觉得自己能回答（finish_reason=stop），有时候觉得该调你的函数（finish_reason=tool_calls）。你的 Agent 就这样变成了薛定谔的猫------在你最需要它调工具的时候，它装死。
LangChain 的 @tool 装饰器帮你省了 5 行代码，但把 finish_reason 和 tool_choice 藏在了黑盒里。你连这两个参数的存在都不知道，怎么 debug？
这就是我为什么坚持一个反主流的学习顺序：先搞懂原理，再学框架。 不是装逼，是省命。你花两天理解原生 Function Calling 的完整流转，比你花两周在 LangChain 黑盒里撞墙高效得多。
那到底该按什么顺序学？我翻了中文社区所有主流的 Agent 教程，找到了一条被几千人验证过的路径。
一条被验证过的路径
Datawhale 的 Hello-Agents（5.9 万星）、ai-agents-from-zero（1900 星）、agent-craft（340 星）------这三个教程加起来几十万人在学（别问翻完花了多久）。有意思的是，它们虽然章节结构各不相同，但底层的学习路径惊人地一致：
LLM 基础 → RAG + LangChain → LangGraph + MCP → 实战项目
这不是巧合。这是几千个踩坑的人用时间换来的共识。我把这个共识压缩成了四个阶段：
地基 → 手脚 → 协作 → 实战每个阶段一篇深扎教程，不教你怎么 import，教你 Agent 在哪个环节会死、为什么死、怎么让它别死。
阶段一：理解 Agent 的运行时心脏
为什么不能跳过
你调用一个 LLM，它回了你一段话。你给它配了一堆工具，它有时代你调用、有时装死。这中间的决策链条------LLM 怎么判断要不要调工具、调哪个、调完怎么把结果用起来------就是 Agent Loop。不理解这个过程，你怎么看 LangChain 的源码都像是在看天书。
这篇会讲什么
四个模块。LLM 为什么输出不可靠------最少的时间，不讲 Transformer 矩阵运算。接着是上下文工程：从"写 Prompt"变成"设计整个上下文窗口"。然后是正餐，Function Calling 的完整机制和 Agent Loop 的"观察→规划→执行→观察"循环------用 OpenAI SDK 原生代码讲，不藏任何细节。收尾是 Harness Engineering，一个新概念，说白了就是给 Agent 上缰绳------怎么设安全边界，什么时候让人类接管。
阶段二：搭好手脚（RAG + LangChain + 第一个单 Agent）
LLM 的知识是你训练它的时候喂的，训练完之后世界发生了什么它一概不知。不信你试试------随便找个模型问"上周 GitHub trending 第一是什么项目"，它会编一个看起来很真的答案。这不是幻觉，是它真的不知道。RAG 就是给 Agent 装上外部记忆------让它能去查、去搜、去读它没见过的东西。
这篇从零搭一个文档问答系统：Chunking 策略怎么选、向量检索和关键词检索什么时候混用、Rerank 模型什么时候值得加。然后拆开 LangChain 的六大模块------讲每个模块帮你省了什么，又藏了什么（你现在已经知道 Function Calling 的底层了，再看 LangChain 的封装会有一种"原来你帮我干了这些"的透明感）。最后揉成一个完整的单 Agent------能查数据库、能调外部 API、能在多轮对话里记住上下文。面试还在考 LangChain，你不学不行，但学完之后你不会只停留在 @tool 装饰器。
阶段三：学会协作（LangGraph + MCP + 多 Agent）
为什么不能跳过
单 Agent 能做的事有上限。复杂任务需要拆分、并行、协作。2026 年的 Agent 已经从"单打独斗"进了"团队作战"模式。MCP 是今年最重要的新东西------一个被 OpenAI、Google、微软、Cursor 全线采纳的工具调用协议，9700 万的月下载量，Linux 基金会在管。不会 MCP，就等于不会 Agent 的"HTTP"（这个类比不是我先说的，但确实到位）。
这篇会讲什么
用 LangGraph 把阶段二的链式调用升级成图结构编排------有条件路由、有状态快照、有 Human-in-the-loop。然后深入 MCP------写一个 MCP Server、让 Agent 发现并调用它、理解 Tool/Resource/Prompt 三元组的设计逻辑。最后用 CrewAI 搭一个多 Agent 的协作系统。同时也会告诉你什么时候不该用多 Agent------你大概率不需要一个 Agent 团队来查天气。
阶段四：实战打磨（SWE-Bench + 企业部署 + 性能优化）
2025 年出过一个事：有人把一段 Prompt Injection 藏在了网页的 alt 标签里，爬虫 Agent 读到之后，开始把用户数据往一个外部邮箱发。这不是漏洞，是 Agent 按指令行事------它只是不知道那条指令不该听。
你的 Agent 在本地能跑，和它在生产环境能活，是两码事。流式输出、错误重试、安全防护、记忆管理、可观测性------每一样在 demo 阶段都不重要，但在用户付钱的那一刻全部变成刚需。精度、延迟、成本三个东西互相打架，你该先优化哪个？
这篇在 SWE-Bench 上跑一个真实的 Code Agent------500 个 GitHub Issue，Agent 自己搜代码、定位 bug、修改、跑测试、验证。然后过企业部署的五关。最后讲精度/延迟/成本的三角优化：模型降级路由怎么搭、Prompt Caching 怎么用、什么时候该从 Flash 切到 Pro。生产框架怎么选也会在这篇展开------国内和海外是两条不同的路径，不会像其他教程那样丢给你一个"用 LangChain 就行"的敷衍答案。
工具箱
以下是这个系列会用到的核心工具和模型。都很便宜或者免费，不存在"学完先花五千块买 API"的情况。
教程模型：DeepSeek V4-Flash。兼容 OpenAI SDK，国内手机号就能注册，新用户有赠送额度------教程的代码量不大，基本够用。后续深扎篇里会标注怎么切到其他模型。
学习框架路线：OpenAI SDK 原生（理解底层机制）→ LangChain（理解社区生态和面试题）→ LangGraph（掌握复杂工作流）。不推荐在生产阶段用哪个------那个话题留给阶段四，到时候结合国内外的实际生产环境展开。
开发工具：Cursor 或者 Claude Code。Agent 开发的代码量不大，但调试链路长，一个好的 AI 辅助 IDE 能帮你省很多时间。两个都支持 MCP，教程里会讲到怎么配。
这个系列不会教你"怎么 import langchain"，也不会给你列一堆"学完能涨薪 50%"的鸡汤。
它做的事只有一件：让你理解 Agent 是怎么运转的，以及它在什么地方会坏。
剩下的，是你自己的事。
下一篇：阶段一------理解 Agent 的运行时心脏。