1. 为什么“先啃框架”是新手最容易踩的坑
我见过太多想入门 AI Agent 的朋友，第一周就抱着某个开源框架的文档硬啃，第二周开始配环境，第三周卡在某个依赖版本冲突上，第四周就放弃了。这个路径几乎成了转行者的标准死法。问题不在于框架不好，而在于学习顺序和大脑的认知规律拧着来。
AI Agent 这个概念听起来很新，但拆开看，它无非就是“让模型能自己决定下一步做什么”。这个“决定”的过程，底层逻辑其实非常朴素：观察当前状态、选择一个动作、执行、看结果、再决定下一步。你在生活里做任何一件稍微复杂的事，都是这个循环。比如你早上出门发现下雨了，你会想“要不要带伞”，然后看一眼窗外雨大不大，再决定拿不拿伞。这就是一个 Agent 的完整决策链。
框架做的事情，是把这条决策链用代码封装起来，让你少写重复逻辑。但如果你连这条链长什么样都没在脑子里跑通过，框架对你来说就是一个黑盒。你调一个agent.run()，它返回一个结果，你也不知道中间发生了什么。一旦结果不对，你连从哪查起都不知道。
我自己的经验是，先用手写一个最简陋的 Agent 循环，哪怕只有二十行代码，哪怕它只能做“查天气然后决定带不带伞”这一件事。你亲手写过这个循环之后，再看任何框架的文档，都会有一种“哦，它是在帮我做这一步”的清晰感。这种清晰感，是你后面调参、排错、做架构决策的基础。
还有一个更隐蔽的坑：很多框架的抽象层级很高，高到你不需要理解底层就能跑通 Demo。但 Demo 跑通和真正做一个能用的 Agent 之间，隔着十万八千里。Demo 里模型永远返回格式正确的 JSON，真实场景里它可能返回一段带 markdown 的废话，可能把工具名拼错，可能在多轮对话后忘记自己是谁。这些问题的解决，靠的不是框架文档，而是你对“模型到底在干什么”的理解。
所以我的建议很直接：前两周不要碰任何框架。把时间花在三件事上——理解 Agent 的基本循环、亲手写一个最小实现、搞清楚模型的能力边界在哪里。这三件事做完，你再去看框架，会发现它们的设计逻辑一目了然，选型也不再是靠别人推荐。
2. 新手和转行者真正该先学的三块地基
2.1 第一块地基：把“决策循环”用代码跑通一遍
这块地基的核心就一句话：让模型输出一个动作，你执行这个动作，把结果喂回去，让它输出下一个动作。听起来简单，但亲手写一遍和看别人写一遍，理解深度完全不一样。
我建议的最小实现是这样的：定义一个工具列表，比如“查天气”和“查日历”。然后写一个循环，每次把用户问题、历史对话、可用工具列表一起发给模型，要求它返回一个 JSON，里面包含tool_name和tool_input。你解析这个 JSON，调用对应的函数，把返回值追加到对话历史里，再发给模型。循环直到模型返回一个final_answer字段。
这个过程中你会遇到第一个真实问题：模型不按格式返回。你要求它返回 JSON，它可能返回“好的，我来帮你查天气，工具名是 get_weather，参数是北京”。这时候你就得写解析逻辑，或者用更严格的提示词。这个坑你踩过一次，以后看任何框架的“输出解析器”模块，都知道它在解决什么问题。
第二个真实问题是：模型选错工具。你问“明天适合跑步吗”，它可能去查日历而不是查天气。这时候你就得在提示词里加约束，或者把工具描述写得更清楚。这个坑让你理解“工具描述”这个看似不起眼的字段，其实对 Agent 的行为影响巨大。
第三个真实问题是：多轮之后模型忘记原始目标。你让它帮你规划一个三天的旅行，它查完第一天天气后，第二天开始就忘了你要去哪。这时候你就得考虑对话历史怎么管理，是全部保留还是做摘要。这个坑直接引出了后面“记忆管理”这个核心话题。
这三个问题，你在手写循环的过程中都会遇到。解决它们的过程，就是你真正理解 Agent 的过程。框架能帮你简化这些问题的处理，但前提是你知道这些问题存在。
2.2 第二块地基：理解模型的“能力边界”而不是“能力上限”
新手最容易犯的另一个错误，是只看模型的“能力上限”——它能写诗、能写代码、能推理数学题。但做 Agent 的时候，你更需要关注的是它的“能力边界”——它在什么情况下会胡编、什么情况下会忽略指令、什么情况下会陷入循环。
我自己的经验是，模型的边界比它的上限更重要。举个例子，你让模型从一段文本里提取人名，它做得很好。但你让它从一段文本里提取“所有提到的时间，并且判断每个时间是过去还是未来”，它就开始出错了。它可能把“上周”判断成未来，也可能漏掉某个隐含的时间表达。这个边界你不亲自测，是不知道的。
怎么测？很简单，给你要做的 Agent 任务，手工构造二十个测试用例，然后自己扮演 Agent 的“执行器”，看模型每一步的输出。你会发现它在某些类型的输入上表现稳定，在另一些类型上时好时坏。这个“时好时坏”的区域，就是你后面做工程化时要重点处理的地方——要么加校验，要么加重试，要么换更结构化的提示词。
还有一个边界是上下文长度。模型在对话很短的时候表现很好，对话一长就开始丢信息。这个边界决定了你后面做记忆管理时，是选择“全部保留”还是“滑动窗口”还是“摘要压缩”。你不亲手测一下，就不知道你的场景下多长算“太长”。
2.3 第三块地基：学会写“给模型看的文档”
这块地基最容易被忽略，但它的重要性怎么强调都不过分。Agent 的行为，很大程度上取决于你给它的提示词和工具描述。而提示词和工具描述，本质上就是“给模型看的文档”。
写这种文档和写给人看的文档，逻辑完全不一样。给人看的文档可以省略“显而易见”的步骤，但给模型看的文档必须把每一步都写清楚。比如你写一个“查天气”的工具描述，给人看的话写“查询指定城市的天气”就够了。但给模型看，你得写“输入一个城市名称字符串，返回该城市当前的温度和天气状况。如果城市名称不明确，返回错误信息”。后面这句“如果城市名称不明确，返回错误信息”就是给模型的行为约束。
我见过很多 Agent 表现不稳定，最后排查下来就是工具描述写得太模糊。模型不知道这个工具接受什么格式的输入，也不知道遇到异常情况该怎么处理，于是它就自由发挥。自由发挥的结果就是时好时坏。
写这种文档有一个实用技巧：把你期望模型输出的格式，用一个具体例子写进描述里。比如“输入示例：北京。输出示例：温度 25 度，晴”。模型看到具体例子，比看到抽象描述的理解准确率高很多。这个技巧在手写循环阶段就应该练熟，后面用框架的时候直接迁移过去。
3. 从“手写循环”到“框架选型”的过渡信号
3.1 什么时候你才算“准备好用框架了”
这个问题我被问过很多次。我的判断标准很简单：当你手写的循环已经能稳定完成一个真实任务，并且你清楚地知道它在哪些环节容易出问题，你就可以开始看框架了。
“稳定完成一个真实任务”的意思是，你给它一个输入，它十次里有八次能给出正确结果。剩下两次失败，你能说出失败的原因——是模型选错工具了，还是输出格式解析失败了，还是上下文太长了。如果你能达到这个状态，说明你已经对 Agent 的基本运转有了体感。
这时候你去看框架，心态完全不一样。你不再是“这个框架好厉害，我要学它”，而是“这个框架帮我解决了手写循环里的哪个问题”。比如 LangChain 的 OutputParser 帮你解决了格式解析问题，AutoGen 的 GroupChat 帮你解决了多 Agent 协作问题，CrewAI 的 Role 定义帮你解决了角色分工问题。你带着问题去看框架，学习效率会高很多。
反过来，如果你手写循环还没跑通，看框架文档就是看天书。你不知道它为什么要设计那个抽象层，也不知道那个抽象层帮你省了什么。你只能照着 Demo 抄，抄完也不知道怎么改。
3.2 选框架时先看“它帮你省了什么”，而不是“它有什么功能”
框架的功能列表都很长，但对你来说，真正重要的是它帮你省掉了哪部分工作。我一般从三个维度去评估：
第一个维度是工具调用。有些框架把工具定义、参数校验、调用执行、结果回传这一整套都封装好了，你只需要写一个函数然后加个装饰器。有些框架只帮你做参数解析，调用还得自己来。你要看你的场景里，工具调用是简单还是复杂。如果只是几个固定工具，手写也不麻烦；如果工具有几十个而且经常变，那封装好的框架就很有价值。
第二个维度是记忆管理。有些框架内置了对话历史管理，支持滑动窗口、摘要压缩、向量检索等多种策略。有些框架完全不管，你自己维护一个列表。如果你的 Agent 需要长时间运行、多轮对话，记忆管理就是刚需，选一个有现成方案的框架能省很多事。
第三个维度是多 Agent 协作。如果你的场景只需要一个 Agent 从头干到尾，那多 Agent 框架对你来说就是负担。但如果你需要多个角色分工，比如一个负责规划、一个负责执行、一个负责检查，那支持多 Agent 的框架就能帮你省掉大量协调代码。
我自己的习惯是，先列出我手写循环时最烦的三件事，然后去看框架文档里有没有对应的解决方案。有，就加分；没有，就减分。这样选出来的框架，才是真正适合你当前阶段的。
3.3 一个常见的选型误区：追求“最强大”而不是“最合适”
新手选框架容易犯的另一个错误，是看哪个框架功能最多、社区最火就选哪个。但功能多意味着抽象层多，抽象层多意味着你遇到问题时排查链路长。你调一个方法，它内部可能经过五层封装，最后报了一个你看不懂的错。这时候你连从哪下手都不知道。
我的建议是，从最薄的框架开始。什么叫“薄”？就是它只帮你做你最烦的那件事，其他都让你自己控制。比如你只是不想手写 JSON 解析，那就找一个只做输出解析的库，而不是上一个全功能框架。等你发现“薄”框架不够用了，再往“厚”框架迁移。这个迁移成本，比你一开始就上“厚”框架然后被各种抽象层绕晕要低得多。
还有一个现实问题是，框架的更新速度很快。你今天学的 API，可能三个月后就变了。但底层的那套“决策循环、工具调用、记忆管理”的逻辑，是不会变的。所以把时间花在底层逻辑上，回报周期更长。
4. 转行者最容易忽略的“非技术”准备
4.1 学会“拆任务”比学会“调 API”更重要
转行者往往带着“我要学技术”的心态进来，但做 Agent 这件事，拆任务的能力比调 API 的能力更关键。什么叫拆任务？就是你把一个模糊的需求，拆成模型能一步步执行的明确步骤。
举个例子，用户说“帮我安排下周的出差”。这个需求对模型来说太模糊了。你得拆成：先确认出差目的地和日期，再查目的地天气，再查交通方式，再根据天气和交通推荐出发时间，最后生成一个行程表。每一步都是一个明确的、模型能执行的动作。
这个拆解过程，框架帮不了你。框架只能帮你把拆好的步骤串起来执行。但怎么拆、拆到什么粒度、哪些步骤可以合并、哪些步骤必须分开，这些全靠你自己的判断。而这个判断力，来自你对业务的理解和对模型能力的了解。
我自己的经验是，拆任务的粒度，以“模型单次调用能稳定完成”为准。如果一个步骤模型经常做错，说明粒度太粗了，继续拆。如果一个步骤模型每次都做得很好，说明粒度合适。这个标准很实用，你不需要纠结“理论上应该拆成几步”，只需要看模型的实际表现。
4.2 建立“测试驱动”的开发习惯
做 Agent 和做传统软件有一个很大的区别：传统软件的行为是确定的，你写if x > 0它就一定走那个分支。但 Agent 的行为是不确定的，同样的输入，模型可能给出不同的输出。所以你不能用传统的方式去“调试”，你得用“测试”的方式去验证。
我的做法是，每加一个新功能，先写五个测试用例。这五个用例覆盖正常情况、边界情况、异常情况。然后跑一遍，看通过率。如果通过率低于八成，说明这个功能还不稳定，得继续调提示词或者改拆解方式。如果通过率高于八成，就可以先放着，继续加下一个功能。
这个习惯的好处是，你随时知道你的 Agent 在什么水平上。不会出现“Demo 跑通了但一上真实场景就崩”的情况。而且当你后面换模型或者改提示词的时候，跑一遍测试用例就知道有没有退化。
4.3 接受“不完美”，学会“兜底”
新手做 Agent 容易陷入一个执念：我要让它百分百正确。但这个目标在现阶段是不现实的。模型就是会犯错，你再怎么调提示词，它还是会在某些输入上出错。所以与其追求“不犯错”，不如学会“犯错之后怎么办”。
兜底策略有很多种。最简单的是重试：模型输出格式不对，就让它重新输出一次。稍微复杂一点的是校验加回退：模型选了一个不存在的工具，你就返回一个错误信息让它重新选。再复杂一点的是人工介入：某些关键决策，模型拿不准的时候，转给人工确认。
我自己的经验是，兜底策略的设计，比提示词的优化更重要。因为提示词优化有上限，但兜底策略可以无限叠加。一个设计良好的兜底机制，能让一个只有七成准确率的 Agent，在实际使用中达到九成以上的可用性。因为剩下那三成错误，都被兜底机制接住了。
5. 一个可以照着走的学习路线图
5.1 第一周：只做一件事——手写循环
第一周的目标很纯粹：不借助任何框架，手写一个能完成单一任务的 Agent。任务可以很简单，比如“根据用户输入的城市名，查天气并给出穿衣建议”。工具就两个：查天气、查穿衣建议。
这一周你会遇到我前面说的所有问题：模型不按格式返回、选错工具、多轮后忘记目标。遇到一个问题就解决一个问题，不要跳过。解决的方式可以是改提示词，可以是加解析逻辑，可以是加校验。重点是亲手解决，而不是找一个库来帮你解决。
这一周结束时，你应该有一个能跑通的脚本，以及一份记录了你遇到的所有问题的笔记。这份笔记就是你后面选框架的依据。
5.2 第二周：加复杂度——多工具、多轮、异常处理
第二周在第一周的基础上加三样东西：工具数量增加到五个以上、支持至少五轮对话、加入异常处理和重试逻辑。
工具多了之后，你会发现模型选错工具的概率上升了。这时候你就得优化工具描述，让每个工具的功能边界更清晰。对话轮次多了之后，你会发现上下文越来越长，模型开始丢信息。这时候你就得考虑怎么做历史管理。异常处理加入之后，你会发现有些错误是可以通过重试解决的，有些错误重试也没用，得换策略。
这一周的目标不是做出一个完美的 Agent，而是让你对 Agent 的复杂度有体感。你知道多工具、多轮、异常处理分别会带来什么问题，后面看框架的时候就知道它在帮你解决哪个层面的问题。
5.3 第三周：选一个薄框架，把手写循环迁移过去
第三周开始接触框架。选一个最薄的、只解决你最烦的那个问题的框架。比如你第二周最烦的是输出解析，那就选一个只做输出解析的库。把它集成到你第二周的代码里，替换掉你手写的解析逻辑。
迁移的过程中，你会对比“手写”和“框架”的差异。你会发现框架帮你省了一些代码，但也引入了一些新的抽象概念。这些抽象概念如果你不理解，就会成为新的黑盒。但因为你已经手写过一遍，你知道这些抽象概念背后对应的是什么，所以理解起来很快。
这一周的目标是建立“框架是工具，不是黑盒”的心态。你知道它帮你做了什么，也知道它没帮你做什么。后面再遇到更复杂的框架，你也能用同样的方式去拆解它。
5.4 第四周：做一个完整的、能演示的小项目
第四周把前三周的东西整合起来，做一个完整的、能给别人演示的小项目。项目不需要复杂，但需要完整——有输入、有处理、有输出、有异常处理、有简单的界面（命令行也行）。
这个项目的价值在于，它让你走完了一个完整的开发闭环。你知道从零到一做一个 Agent 是什么感觉，也知道哪些环节最花时间、哪些环节最容易出问题。这个体感，是你后面做任何复杂项目的基础。
而且这个项目可以成为你的“作品”。转行者最缺的就是作品。一个能跑通的、你自己亲手写的 Agent 项目，比任何证书都有说服力。
6. 几个我踩过的坑和对应的绕行方案
6.1 坑一：过早追求“多 Agent 协作”
我刚开始做 Agent 的时候，觉得多 Agent 协作特别酷——一个负责规划、一个负责执行、一个负责检查，像一个小团队一样。于是我花了很多时间去设计 Agent 之间的通信协议、角色定义、任务分配。结果做出来的东西，还不如一个单 Agent 加几个工具来得稳定。
后来我想明白了：多 Agent 协作解决的是“单 Agent 上下文不够用”的问题。如果你的任务在一个 Agent 的上下文里能装下，那多 Agent 就是徒增复杂度。只有当任务复杂到单个 Agent 的上下文装不下，或者需要不同角色用不同的提示词来约束行为时，多 Agent 才有价值。
所以我的建议是：先用单 Agent 做，做到上下文装不下了，再考虑拆成多 Agent。不要一开始就上多 Agent，那是给自己找麻烦。
6.2 坑二：把“提示词工程”当成“写小作文”
我有一段时间特别迷信“提示词工程”，觉得只要提示词写得好，模型就能做对。于是我花大量时间打磨提示词，加各种约束、各种示例、各种格式要求。提示词越写越长，从几百字写到几千字。
结果呢？模型确实在某些用例上表现更好了，但在另一些用例上反而更差了。因为提示词太长，模型抓不住重点。而且提示词越长，维护成本越高，改一个地方可能影响另一个地方。
后来我学乖了：提示词要短、要结构化、要可测试。短的意思是只写必要的信息，不写废话。结构化的意思是用列表、用分隔符、用明确的段落来组织，而不是写成一大段。可测试的意思是每改一次提示词，都跑一遍测试用例，看通过率是升了还是降了。
这个教训让我明白，提示词工程不是“写小作文”，而是“设计接口”。你是在设计模型和你之间的接口，接口要清晰、要稳定、要可验证。
6.3 坑三：忽略“成本”和“延迟”
新手做 Agent 容易只看“效果”，不看“成本”和“延迟”。但这两个因素在实际使用中非常关键。一个 Agent 如果每次调用要花几毛钱、等十几秒，那它基本没法用。
我自己的经验是，在开发阶段就要把成本和延迟纳入考量。比如你设计一个循环，每次循环都调用一次模型，那循环五次就是五次调用。你能不能把五次调用合并成两次？能不能用更小的模型来做一些简单的判断？能不能缓存一些不常变的结果？
这些优化在开发阶段做，比上线之后再做好得多。因为上线之后，你可能已经积累了大量依赖当前架构的代码，改起来成本很高。
还有一个现实问题是，不同模型的成本和延迟差异很大。有些模型便宜但慢，有些模型快但贵。你得根据你的场景来选。比如一个需要快速响应的场景，你可能愿意多花点钱用更快的模型。一个对延迟不敏感的场景，你就可以用更便宜的模型来省钱。
6.4 坑四：不写文档，不写注释
这个坑很朴素，但很致命。我刚开始做 Agent 的时候，觉得代码能跑就行，写什么文档。结果过了一个月回头看，自己都忘了当时为什么那么设计。改一个地方，牵一发而动全身，因为不知道各个模块之间的依赖关系。
后来我强制自己每做一个模块，就写一段说明：这个模块解决什么问题、输入是什么、输出是什么、依赖哪些其他模块、有哪些已知的限制。这段说明不需要很长，但必须写。写完之后，后面改代码的时候先看说明，就知道改动会影响哪些地方。
这个习惯让我后面做复杂项目的时候轻松很多。因为我知道每个模块的边界在哪里，改一个模块不会意外影响另一个模块。
7. 给不同背景转行者的针对性建议
7.1 有后端开发背景的人：你的优势在工程，不在模型
如果你有后端开发经验，你的优势是工程能力——你知道怎么写可维护的代码、怎么做错误处理、怎么做日志、怎么做测试。这些能力在做 Agent 的时候非常值钱，因为 Agent 的很多问题本质上是工程问题，不是模型问题。
但你的劣势可能是对模型的行为不够敏感。后端开发习惯了确定性，输入 A 就输出 B。但模型是不确定的，同样的输入可能输出 B 也可能输出 C。你需要花时间去适应这种不确定性，学会用概率的思维去设计系统。
我的建议是，把你后端的工程能力用在“兜底”和“可观测性”上。设计好错误处理、设计好日志、设计好测试用例。这些是你擅长的，也是 Agent 开发中最容易被忽略但最重要的部分。
7.2 有产品背景的人：你的优势在拆任务，不在写代码
如果你有产品背景，你的优势是拆任务——你知道用户真正想要什么，知道怎么把一个模糊需求拆成明确的步骤。这个能力在做 Agent 的时候非常关键，因为 Agent 的核心就是“把任务拆成模型能执行的步骤”。
但你的劣势可能是代码能力不够。你可能有很好的想法，但不知道怎么实现。这时候我的建议是，先用低代码或者无代码的方式把想法跑通。现在有很多工具可以让你不写代码就能搭一个简单的 Agent。你先用这些工具验证你的想法，验证通过之后，再找人合作或者自己学代码来实现更复杂的版本。
不要因为代码能力不够就放弃。Agent 这个领域，想法和拆解能力比代码能力更稀缺。代码可以学，但拆解能力是练出来的。
7.3 完全零基础的人：你的优势是没有思维定式
如果你完全零基础，没有编程经验也没有产品经验，你的优势是没有思维定式。你不会被“以前是这么做的”束缚，你会更愿意尝试新的方式。
但你的劣势也很明显：你需要同时学编程、学模型、学 Agent 的概念。这个学习曲线很陡。我的建议是，不要试图同时学所有东西。先学最基础的编程——变量、循环、函数、列表、字典。这些学明白了，再学怎么调用模型 API。API 调明白了，再学 Agent 的循环。一步一步来，不要跳。
而且零基础的人有一个隐藏优势：你更接近普通用户。你知道普通用户会怎么描述需求，你知道哪些表达是模糊的。这个视角在做 Agent 的时候很有价值，因为 Agent 最终是要给普通用户用的。
8. 关于“学到什么程度才算入门”的实话
8.1 入门不是“学完所有知识”，而是“能独立做一个能用的东西”
很多人问“AI Agent 入门要学多久”，这个问题没有标准答案。但我觉得“入门”的标准可以很明确：你能独立做一个能用的 Agent，并且能说清楚它为什么能用、在什么情况下会不能用。
“能用”的意思是，它在一个明确的场景下，能稳定地完成一个明确的任务。比如“根据用户输入的城市名，查天气并给出穿衣建议”，这个任务很明确，你的 Agent 能稳定完成，那你就入门了。
“能说清楚”的意思是，你知道它的能力边界在哪里。你知道它在什么输入下表现好，在什么输入下表现差。你知道它为什么会差，也知道怎么改进。这个“知道”，比“能做”更重要。
8.2 不要追求“学完再动手”，要“边做边学”
我见过很多人，买了一大堆课程，看了一大堆视频，但就是不动手。问就是“我还没学完”。但 Agent 这个东西，不动手是学不会的。你看一百个视频，不如自己手写一个循环。
我的建议是，看一个最小的教程，然后立刻动手。动手过程中遇到问题，再回去查资料。查完继续动手。这个循环比“先学完再动手”高效得多。因为你在动手过程中遇到的问题，是你真正的问题，你查资料的时候会更有针对性。
而且 Agent 这个领域变化很快，你今天学的“最佳实践”，可能下个月就过时了。但你在动手过程中积累的“体感”，是不会过时的。你知道模型大概能做什么、不能做什么，你知道一个循环大概长什么样，你知道哪些环节容易出问题。这些体感，是你后面学任何新框架、新工具的基础。
8.3 保持“够用就好”的心态，不要陷入“工具收集癖”
最后说一个心态问题。Agent 这个领域工具很多，每天都有新框架、新库、新平台出来。新手容易陷入“工具收集癖”——看到一个新工具就想学，学了一半又看到另一个，又去学另一个。结果学了一堆工具，但一个都没学透。
我的建议是，保持“够用就好”的心态。你手头有一个能用的工具，就先把它用熟。等你发现它真的不够用了，再去找新的。不要因为“别人都在用”就去学一个新工具。你的时间有限，花在刀刃上。
而且工具是会变的，但底层逻辑不会变。你把底层逻辑搞明白了，学任何新工具都快。你把底层逻辑没搞明白，学再多工具也只是浮在表面。
我自己到现在，常用的工具就那么几个。不是因为我不知道其他工具，而是因为这几个工具够用了。我把时间花在理解业务、拆解任务、优化兜底策略上，而不是花在学新工具上。这个取舍，我觉得是值得的。
