写在前面
过去一年我见过太多人问"AI Agent 怎么学"，然后被"先学 LangChain 再学 LangGraph 最后写个 RAG"这种路线劝退。问题在哪？这类路线把工具当成了目标，学完一圈你会写 Demo，但遇到生产问题一脸懵——模型调用失败怎么降级、多轮 tool call 中间状态丢了怎么办、Agent 死循环怎么打断、上了量之后 token 成本飙升怎么控……这些才是真实场景里每天遇到的。
这篇文章我想倒着来讲 Agent 学习路线：**从"我手写一个 Agent 时会遇到什么痛点"出发，反推每个框架、每个工具解决的是哪个具体问题。**走完这条路的人，面对新框架时看两天文档就能用，而不是每次都要从零学起。
路线分四个阶段，预计 2-3 个月能完整走一遍（全职大概一个月）：
- 吃透 LLM 本身的边界
- 手写不依赖框架的 Agent
- 带着问题学主流框架
- 上工程化（评测 / 观测 / 部署）
阶段一：吃透 LLM 本身的边界（1-2 周）
这阶段不是学 prompt engineering，而是把 LLM 的"物理参数"搞清楚。很多人跳过这步直接上框架，结果遇到延迟高、费用爆、输出不稳定时完全不知道哪里能调。
必须要会的几件事
1. 一次 LLM 调用的完整成本模型
- Input token / Output token 定价差异（通常 output 是 input 的 3-5 倍）
- Context 长度和延迟的关系：长 context 不只是贵，首 token 延迟也会显著上升
- 模型家族差异：Claude Opus 4.x / Sonnet 4.x / Haiku 4.x、GPT-4.x、Gemini 2.x、国内 DeepSeek / Qwen 这几家在推理速度、function calling 稳定性、结构化输出成功率上都有明显区别
2. Function calling 的可靠性边界
这是做 Agent 最关键的一项能力，但各模型的可靠性差异很大。建议自己跑一个 benchmark——准备 20 个 tool，设计 50 个需要多轮调用的任务，测各家模型的：
- 第一轮工具选择准确率
- 参数填充准确率
- 多轮场景下遗忘历史的比例
- 并发多工具调用的成功率
跑过一遍，你就知道为什么生产上很多团队用 Claude 做 Agent 而不是用别的——不是玄学，是实测数据。
3. 结构化输出（Structured Output）
LLM 输出 JSON 的失败率在没有 schema 约束时能高到 15%，带 schema（OpenAI 的 response_format、Anthropic 的 tool use、Gemini 的 structured output）后能降到 1% 以下。了解这些 API 的差异，后面你会反复用到。
4. Prompt Caching
Anthropic 和 OpenAI 都支持 prompt caching，能把重复的系统 prompt 和 few-shot 示例缓存起来，成本降 90%，延迟降 80%。做 Agent 一定要用，不用就是在浪费钱。
这阶段的产物
一个自己跑过数据的 Notion 页面或者 README，记录每家模型在你场景下的：延迟、成本、function calling 成功率、结构化输出成功率。这是你后面所有技术决策的基础。
阶段二：手写一个不依赖框架的 Agent（1 周）
这步是整条路线的分水岭，跳过这步直接学框架的人最后都会回来补。
200 行代码内写一个 Agent
核心循环就是：
while not done:
response = llm.call(messages, tools=tool_schemas)
if response.has_tool_calls:
for tool_call in response.tool_calls:
result = execute_tool(tool_call)
messages.append(tool_result(result))
else:
done = True
return response.content
就这么简单。不要用 LangChain，不要用任何框架，就用 OpenAI SDK 或 Anthropic SDK 的原始接口。
这阶段你会自然遇到的痛点
- 状态管理：messages 越攒越长，怎么压缩？
- 错误恢复：tool 执行失败了要不要重试？重试几次？
- 循环终止：模型一直调同一个 tool 怎么办？
- 并发控制：几个 tool 能并发跑吗？
- 中断恢复：Agent 跑到一半崩了，怎么从中断点继续？
- 人工介入：敏感操作（发邮件、扣款）要不要让人确认？
- 成本控制：跑一次到底花了多少 token？
把这些痛点一一记下来，这就是你下一步学框架的"购物清单"。
阶段三：带着问题学主流框架（3-4 周）
重点来了。现在带着上面那张购物清单，你去看每个框架时会发现：它不是随便设计的，每个 API 都在解决你手写时痛过的某个问题。
LangGraph
它解决什么：状态管理 + 中断恢复 + 人工介入。
- State：你手写时那个越攒越长的 messages，LangGraph 里就是一个带类型签名的 State Dict，每个 Node 明确声明读写了哪些字段
- Checkpointer：解决"Agent 跑到一半崩了"——每步自动存盘，可以从任意步恢复
- Human-in-the-loop：
interrupt()一行代码就能在关键节点让人工确认 - Edges：把循环逻辑从 if/else 地狱变成图的拓扑结构
学习要点：不要花时间背 API，就看它怎么组织 State 和 Edge。理解透之后其他图式框架（比如 LlamaIndex Workflow）都是一通百通。
Pydantic AI
它解决什么：类型契约 + 依赖注入 + 测试。
手写 Agent 时你会遇到一个烦人的事——Tool 的入参、LLM 的结构化输出，都需要各种格式校验代码。Pydantic AI 把这些全交给 Pydantic 的类型系统，Agent、Tool、Output 都是强类型的。
另外它的测试生态极好，可以用 TestModel 替换真实 LLM 跑单测，这在生产代码里非常重要。
DSPy
它解决什么：Prompt 优化的自动化。
手写 Agent 最痛的事之一是调 prompt——今天手调一版能跑通，明天模型升级又挂了。DSPy 把 prompt 看作可学习的参数，用少量标注数据就能自动优化 prompt 和 few-shot 例子。
学 DSPy 有助于你理解"Prompt 不是 art 而是可测量的组件"这个思维方式，哪怕你不用它，这个思维也能迁移到其他地方。
LangChain 要不要学？
个人观点：2026 年的今天，直接跳过 LangChain 学 LangGraph。 LangChain 作为入门包袱大、抽象多、文档散，新项目没有理由再用它。老项目维护会遇到，能看懂就行，不用深入。
RAG 相关：LlamaIndex / ColPali
如果你的 Agent 需要接知识库（99% 都需要），建议学 LlamaIndex。它比 LangChain 的 RAG 模块更系统，从 Document / Node / Index / Retriever / Synthesizer 这套抽象非常清晰。
ColPali 是近一年起来的视觉 RAG 方案，PDF / PPT / 截图这种富媒体的检索精度甩传统 OCR + 文本嵌入几条街，值得单独学。
多 Agent 协作
简单场景用 LangGraph 的 Supervisor 模式就够了。复杂场景可以看 CrewAI 或者 AutoGen，但别陷进去——90% 的"多 Agent"需求其实用单 Agent + 多 tool 就能解决，别为了架构而架构。
阶段四：上工程化（3-4 周）
能写出 Demo 不代表能上生产。这阶段是 80% 的人会卡住的地方。
评测（Evaluation）
没有评测的 Agent 就是盲盒。推荐学习：
- Ragas：专门做 RAG 评测，Faithfulness / Answer Relevancy / Context Precision 这几个指标要熟
- Phoenix / Langfuse Eval：做整体 Agent 轨迹评测，能看到每一步的输入输出
- 自建 Dataset：生产中最重要的还是自己的业务数据集，持续积累
关键思路：每次改 prompt 或换模型前，跑一遍 eval，有数字才有对比。 凭感觉调参是大忌。
观测（Observability）
生产上出 bug 最怕的是"不知道哪步挂了"。Langfuse / Logfire / OpenTelemetry 这套要熟：
- Trace 粒度：每个 LLM 调用 / 每个 tool 调用都有独立 span
- Metric：延迟、成本、失败率、用户满意度
- 报警：异常轨迹、高成本请求、死循环自动告警
Langfuse 自建、Logfire SaaS，看团队偏好选一个就行。
生产部署
- API 层：FastAPI + Streaming Response，SSE 和 WebSocket 都要会
- 多模型路由：LiteLLM 做统一网关，同时支持 OpenAI/Anthropic/国内模型，带 fallback 和 rate limit
- 缓存层：Redis 做 prompt 级缓存，数据库级 embedding 缓存用 PGVector / Qdrant
- 安全：PII 脱敏、Prompt Injection 防御、API Key 轮转
这一层的细节可以写好几篇文章，这里就不展开了。
时间规划建议
| 阶段 | 时长（业余） | 时长（全职） | 核心产物 |
|---|---|---|---|
| 一、吃透 LLM | 1-2 周 | 3-5 天 | 模型 benchmark 报告 |
| 二、手写 Agent | 1 周 | 2-3 天 | 200 行无框架 Agent |
| 三、学框架 | 3-4 周 | 1-2 周 | LangGraph + Pydantic AI + DSPy 三个 Demo |
| 四、工程化 | 3-4 周 | 2-3 周 | 一个带 eval + 观测 + 部署的生产级 Agent |
全程下来 2-3 个月，业余学完基本能应付 80% 的生产场景。
最常见的几个坑
- 别追最新论文：学路线期间不要去追 arXiv 每周的 Agent 新架构，它们 90% 一年后就没了。学稳的东西。
- 别用 chatgpt.com 写代码：用 Claude Code 或 Cursor，它们能看到完整项目上下文，效率差几倍。
- 别省钱用小模型学习：学习阶段用 Claude Opus 4.x 或 GPT-4.x 这类最强模型，小模型的 function calling 错误率会让你怀疑是自己代码写错。
- 早点上评测：第一天就建 eval 数据集，别等"等我项目跑起来再加"——不会加的。
- 不要跳过手写阶段：这步是性价比最高的一步，别想着"我直接上框架更快"。
最后
Agent 赛道的窗口期我觉得还有 2-3 年——2028 年之后基础设施会非常成熟，那时候学反而没太多红利了。现在入场，踏实把这四阶段走完，是能拿到职业回报的。
——顺便说一下，我平时学这些的时候会在 gufacode.com 上翻对应的教程做参考。上面 ai-agent、langgraph、dspy、pydantic-ai、llamaindex、langfuse、litellm 这些教程正好是按上面这条路线组织的，每一章带原理剖析和实战代码，不是翻译官方文档那种水货，想系统走一遍的朋友可以参考。
祝各位早日跑通自己的第一个生产级 Agent。
