最近私信里被问得最多的一句话是“我想往 AI Agent 方向发展是不是应该先把 LangChain 啃一遍”我的答案一直很统一先别。至少别一上来就啃框架尤其别照着网上的热门榜单挨个去点星标、跑 demo。AI Agent 这个方向看起来很新但它的内核其实非常朴素——大模型 规划 记忆 工具使用而框架只是把这些零件拼装起来的脚手架。你如果连“零件”长什么样、为什么要拼、怎么拼都还没概念直接去学脚手架就会出现一个特别典型的状态文档读得懂demo 也跑得通但一旦换个场景、换个工具、换个模型就一脸懵。这篇文章就是写给刚入门的新人和准备转行过来做应用开发的朋友我会把入门前真正该学的几件事按我自己的实践顺序拆开讲清楚内容不依赖任何特定框架看完你甚至会发现自己已经能徒手搭出一个能跑的小 Agent。1. 别急着学框架先搞清楚 Agent 到底是个什么东西1.1 Agent 的四个零件模型、规划、记忆、工具我见过不少人把 Agent 想得很玄总觉得它像科幻片里的智能体或者至少是个很复杂的神经网络。实际做应用开发的视角完全不是这样。你可以把一个 Agent 拆成四个零件大模型LLM负责理解、推理、生成是 Agent 的“大脑”规划Planning决定下一步该干什么任务怎么拆解步骤怎么排记忆Memory短期记忆就是上下文窗口里的话长期记忆是外部存储里存的知识和过去的经验工具Tool Use让 Agent 能操作外部世界比如查天气、查数据库、发消息、调接口。这四个零件缺一不可但入门阶段真正要花时间去练的是搞清楚“大模型”和“工具使用”之间的配合方式。给你一个最直白的类比Agent 就像一个实习生大模型是这个实习生的脑子工具是他手上的电话和电脑。脑子再聪明没有打电话和查资料的技能他也什么都办不成。框架呢框架相当于公司给你配好的办公流程系统告诉你事情可以怎么流转。如果实习生自己都不清楚该给谁打电话、电话里说什么你用再好的流程系统也没用。我最早就是踩了这个坑——看了两天 LangChain 文档觉得 concept 都懂了结果让自己写一个“能查天气再告诉我该不该带伞”的 Agent完全不知道该从哪里入手。问题不在框架而在我的底层概念是空的。所以后来我索性把所有框架全扔掉先徒手做了一遍 Agent 的核心循环才真正把这些概念打通。1.2 为什么“先啃框架”是新手最容易踩的坑你可能想问“框架都这么流行了学框架不就是最快的路吗”我的看法是框架是捷径但不是起点。如果你连 Agent 本身怎么运转都不知道框架里的那些抽象概念Chain、Graph、Runnable、Pipeline就会变成一层一层挡在你和真实原理之间的黑盒。踩坑的具体表现通常有这几种调试难Agent 出错了框架日志把错误层层包装你根本分不清是模型输出不对、工具调用失败还是框架内部状态出了问题。不夸张地说至少一半的时间花在“猜框架到底替我做了什么”上面。版本升级就崩热门框架迭代非常快API 一变你之前学的那些写法全废又要从头学一遍。如果你底层原理明显换框架、换版本对你而言其实只是换一层皮但如果你只有框架的知识版本一升就等于从零开始。不会自己组装只学过框架提供的现成组件当项目需求稍微偏一点比如想要自定义一个很简单的 Agent 循环你就发现框架的默认模式写不了但又不知道魔改从哪里下手。我的观点很明确框架是别人对“Agent 该怎么做”的一种参考答案它省的是你的重复劳动但省不了你对基本概念的理解。工具可以晚点再选地基必须趁早打牢。2. 入场第一关把 LLM 调用练到条件反射2.1 从一次最简单的 API 调用开始别管你用的是哪家大模型的接口OpenAI 风格接口是目前最通用的一种把一次普通的对话补全调用写到“闭着眼都能敲出来”的程度是你后面所有动作的基础。Agent 的本质不是训练模型而是反复调用已经训练好的模型所以 API 调用就是你和模型之间的唯一沟通通道。这个通道越熟后面做 Agent 越顺手。一个最基础的调用长这样from openai import OpenAI client OpenAI( api_key你的key, base_url你的接口地址, # 很多国产模型都兼容这种格式 ) response client.chat.completions.create( model你的模型名称, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: 用一句话解释什么是AI Agent。}, ], temperature0.3, max_tokens200, ) print(response.choices[0].message.content)这段代码里有几个关键参数新手一定要搞清楚它们各自的含义因为后面调 Agent 时你会反复和它们打交道messages模型看到的所有上下文都由这个数组决定。system是系统设定user是用户输入assistant是模型之前的回复。Agent 的“记忆”本质上就是不断往这个数组里追加内容。temperature控制回答的随机性。数值越低回答越稳定、越适合执行任务数值越高回答越有创造性。做 Agent 的默认建议先设为 0 附近大部分任务你都不希望模型天马行空。max_tokens限制单次输出的最大长度。新手常常忽略这个参数结果长任务被截断输出格式不完整后续解析全部失败。我在实操中的一个小建议一开始练习时不要只用一个模型你可以多试两三个兼容 OpenAI 格式的国产接口目前像 DeepSeek、智谱、通义等都有对应版本你会发现不同模型对同样指令的遵循程度差别很大——这也是将来做 Agent 选型需要重点关注的维度。但入口都是同一个学会一次走遍通用。2.2 结构化输出才是 Agent 的地基很多新手在 API 调用练习阶段容易忽略一件事你做 Agent 不是让它写诗而是让它替你完成精确的任务。所以在大多数情况下你不能接受模型输出一段“自然语言”你需要的是结构化输出——也就是让模型严格按固定格式给你返回结果最好直接是 JSON因为你的代码需要进一步解析和执行。为什么要这么做我用一个例子说明。假设你在做一个“查天气并推荐穿搭”的 Agent你需要模型不仅仅是回复一句话而是输出一个决策比如“要不要带伞”。如果你的代码要基于这个决策去拼接消息或者推送通知那自然语言的回复就很难处理。而结构化输出就不会有歧义response client.chat.completions.create( model你的模型名称, messagesmessages, response_format{type: json_object}, # 强制 JSON 格式 ) import json data json.loads(response.choices[0].message.content) # data 里可能长这样 # {need_umbrella: true, suggestion: 建议带伞下午有雨}这一步是 Agent 的重要转折点模型的任务不一定是直接回答用户而是先“吐出一个机器可读的决策”再由你的程序去执行下一步。你能让模型的输出变成代码可以解析的数据Agent 的自动化闭环才开始成立。所以我会建议所有新手在你碰任何框架之前先用三四个 API 练习场景把“自然语言输入 - JSON 输出”这个模式练熟。哪怕只是让模型对一条商品评论做情感分类输出{sentiment: positive}就行练一遍就会明白结构化输出的价值。3. 第二关提示词与 Function Calling让模型有能力操作世界3.1 系统提示词别写诗按“目标-约束-输出”三段来很多新手把提示词工程理解为“怎么把话说得更漂亮”其实并不是。在 Agent 场景里提示词更像是给实习生写任务说明书。你不需要写得多有文采但一定要写清楚三件事目标是什么、约束是什么、输出格式是什么。我通常用的结构长这样你是某某 Agent负责帮助用户查询天气并给出出行建议。 目标 1. 分析用户的出行需求。 2. 根据实时天气数据给出建议。 约束 1. 只能使用提供的工具获取天气不得编造数据。 2. 如果用户没有提供城市必须先向用户询问。 3. 回答控制在 50 字以内。 输出格式 { city: 城市名, weather_summary: 天气概述, advice: 出行建议 }这套写法有两个坑要特别提醒你。第一约束要写得像“不可违反”而不是“建议”。比如你要写“不要编造数据”直接写“只能使用工具返回的结果禁止自行猜测任何数值”效果会好很多。第二输出格式的示例一定要具体比“返回 JSON”这种话有用得多给一个{...}示例模型照抄你格式的成功率会显著提升。我见过不少 Agent 项目翻车翻的不是模型能力而是提示词里没写清楚边界导致模型“自由发挥”自己编数据或者输出无法解析的文本。这些问题在后期的“框架封装”下更难排查因为你看不到原始 prompt 了。所以在入门阶段我强烈建议你把每一次发给模型的完整提示词打印出来亲眼看看它长什么样你才能理解 Agent 的行为边界是由什么决定的。3.2 Function Calling把“工具说明书”喂给模型如果说提示词是教模型“表达”那 Function Calling函数调用就是教模型“行动”。这是 Agent 能真正影响外部世界的核心机制也是整个学习路线里最值得花时间的一块。理解 Function Calling 的思想其实很简单模型本身不能执行代码但你可以告诉它“你面前有哪些工具每个工具的参数是什么什么情况下调用哪个”然后模型会在回复中输出一个“工具调用请求”由你的代码去真正执行这个函数再把结果反馈给模型。也就是说模型负责“决策”你的程序负责“执行”。来看一个最经典的例子给模型提供两个工具一个是查天气一个是做数学计算。tools [ { type: function, function: { name: get_weather, description: 查询指定城市的当前天气, parameters: { type: object, properties: { city: {type: string, description: 城市名如北京} }, required: [city] } } }, { type: function, function: { name: calculator, description: 执行基础的数学运算, parameters: { type: object, properties: { a: {type: number}, b: {type: number}, op: {type: string, enum: [, -, *, /]} }, required: [a, b, op] } } } ] # 发给模型时带上 tools 参数 response client.chat.completions.create( model你的模型名称, messagesmessages, toolstools, tool_choiceauto, )拿到响应之后你要检查response.choices[0].message.tool_calls字段里面有模型决定要调用的函数名和参数。然后你在自己的代码里if分支执行对应的 Python 函数把执行结果以tool角色消息追加进messages再调用一次模型让模型基于结果继续回答。这个“决策-执行-反馈-再决策”的循环就是 Agent 的最核心形态。这里有几个新手必踩的坑工具的 description 不要偷懒。模型选工具很大程度靠描述里的语义。你写“查询天气”和“根据城市名称返回真实天气数据如用户问到天气或出行建议时可调用”选对的概率完全不一样。参数名要清晰避免使用a、b、c这种简称不然模型填参数时经常张冠李戴。执行函数的代码不要放在给模型看的 prompt 里只把工具的定义传给模型真正的函数体留在你的程序里。这是安全和职责分离的基本要求。4. 第三关手动搭一个“什么框架都没用的 Agent”4.1 ReAct 循环思考、行动、观察“手搓 Agent”听起来很硬核其实核心逻辑非常简单——就一个 while 循环。这个循环的学名叫 ReActReason Act意思是模型交替进行“推理Reason”和“行动Act”并根据行动后的观察Observation继续推理直到任务完成。你可以把它想成问路你先看地图观察决定先走到哪个路口思考走一段之后看路牌观察再决定下一个方向思考。Agent 也是这么工作的max_iterations 5 for i in range(max_iterations): response client.chat.completions.create( model你的模型名称, messagesmessages, toolstools, ) message response.choices[0].message # 如果模型没有要求调用工具说明它已经能给出最终回答了 if not message.tool_calls: print(最终答案, message.content) break # 否则执行模型要求的工具调用 messages.append(message) for tool_call in message.tool_calls: result execute_local_function(tool_call) # 你程序里的真实函数体 messages.append({ role: tool, tool_call_id: tool_call.id, content: result, })不要小看这段只有十几行的代码。它就是我理解的 Agent 骨架模型负责推理程序负责执行循环负责推进。所以 Agent 的“思考”其实很浅层真正跑起来靠的是你精心设计的工具和循环控制。这里有两点实践经验一定要设max_iterations。没有这一步模型可能在循环里反复调用工具token 烧得像流水一样快而且一旦陷入死循环调试过程非常崩溃。把每一步的中间结果都打印出来。很多新手觉得循环里不用看中间过程直接看最后答案就行。但 Agent 恰恰是最需要观察中间过程的场景——你要看它每一步调用了什么工具、拿到了什么结果、下一步怎么改变策略这些信息量远大于最终答案。等你手动写完了这个循环你会发现 LangChain 里的AgentExecutor这类概念瞬间变得特别好懂——它就是把上面的循环加上了各种分支处理和状态记录原理没有秘密。4.2 记忆怎么做短期上下文与长期检索Agent 循环跑起来了之后紧接着就会遇到“记忆”的问题。一个完整的对话不可能所有内容都永远塞在上下文里不然 token 成本会失控。我的经验是把记忆分成两层来理解短期记忆就是messages数组里倒序保留最近的若干轮对话这最接近我们平时的“chat history”。你需要做的只是控制它别无限增长比如只保留最近十条消息。长期记忆把更早的重要信息存到外部存储里在需要的时候通过检索召回。最简单的实现是给每条历史消息打个关键词标签存进 SQLite下次用户提到某个词时用关键词匹配召回相关背景。进阶方案是使用 embedding 做向量检索把历史记录转成向量按相似度召回但效果和复杂度都会明显上升。这里给新手一个忠告先别急着上向量数据库。对于刚开始的项目用 SQLite 关键词搜索完全够用甚至可以先只做一个简单版本历史对话太多时让模型把之前的对话“总结压缩”成几句要点存进上下文。等你的场景真的有长文本、多轮、跨会话需求时再引入向量检索也不迟。核心原因是记忆管理的关键不是“选哪个数据库”而是“什么信息需要被记住、什么信息可以丢掉”。这个问题不依靠存储技术解决依靠你对业务的理解解决。我也要提醒一句 token 成本意识。Agent 的循环意味着每步都要调用模型一次完整任务下来消耗的 token 往往是你想象的数倍。所以从第一天起就养成习惯只把当下需要的上下文放进去无关的历史、冗长的工具返回结果该截断就截断。这不是优化技巧这是基本生存技能。5. 理解了底层再谈框架怎么选5.1 框架到底帮你省了哪些事当你能徒手调 API、写函数调用、搭 ReAct 循环、做简单的记忆管理之后你才有资格判断框架对你到底有没有用。这时候再看框架你不会被它的概念术语唬住而是能清醒地说出“这一层它帮我封装了什么、这一层我自己写也不难”。具体来说主流框架通常帮你封装了这几件事模型接入层各种各样的模型通过统一接口接入换来换去不用改业务代码工具调用管线函数注册、参数解析、结果回填这些动作自动化链式编排把“先调用 A 模型再调用 B 模型中间做两次工具调用”这种流程做成可复用的组件记忆与向量检索集成内置对话历史、向量存储、RAG 的常用方案开箱即用多 Agent 通信当你需要多个 Agent 协作完成任务时框架提供角色定义、消息路由、任务分发等抽象。这些能力里有人非常需要有人完全不需要。比如你只是做一个内部工具一个 Agent 配三个工具就够了那很多框架的能力对你来说是负累。但如果你要做的是复杂业务流程比如“客服 Agent 先判断用户意图再转给售后 Agent售后 Agent 再调用工单系统”那框架的编排能力会帮你省大量体力活。5.2 LangChain、Dify、CrewAI按场景选而不是按热度选目前最常被问到的三个框架/平台我按适用场景给你拆一下方便你做选型判断对比项LangChainDifyCrewAI定位开发库代码集成LLMOps 平台可视化 API多 Agent 编排框架上手难度较高概念多抽象层级多较低界面拖拽即可搭建中等偏代码但概念清晰最擅长灵活编排复杂流程深度定制快速搭 MVP、可视化调试、RAG 应用多个角色 Agent 分工协作适合人群有编程经验、要深度定制后端逻辑的工程师产品经理、非深度开发、想快速验证 idea 的团队已经清楚单 Agent 不够用、确有多角色需求的人调试体验需要熟悉隐式行为初期容易懵可视化日志直观过程可读性好但生态相对小典型场景复杂业务链路、自定义工具多的应用企业知识库问答、客服机器人快速落地需要规划者和执行者分开的场景我的建议很直接新手第一个项目不要从选框架开始。先徒手把第一个 Agent 做出来然后问自己一个问题——“这个项目里最难写的是哪段代码”。如果是“把多个流程串起来太麻烦”那 LangChain 能帮到你如果是“想快速做个界面、配个知识库给团队用”Dify 这种可视化平台更合适如果是“我明显需要三个 Agent 分工协作”再去看 CrewAI 也不迟。框架没有绝对的好坏只有和你的场景匹配不匹配。5.3 一句话判断你现在该不该上框架我把自己的判断标准分享给你你可以对号入座如果模型调用还没练熟、工具循环还没自己写过一遍那答案很明确不上框架先手写如果项目复杂度和场景历历在目框架能明显省你时间那就果断引入如果其实还没想清楚具体需求只是听到“大家都在用某个框架”那你要警惕——这多半是“FOMO”错失恐惧不是需求。对了还有一个常被问到的方向问题做 Agent 应用开发要不要先把 PyTorch、Rust 这类底层技术学一遍我的答案是不需要除非你的方向是模型训练、推理优化或者高性能部署。Agent 应用开发本质上是“模型能力 工具系统 业务逻辑”的粘合工作你的编程基础更多体现在代码能力、接口设计、数据流梳理上而不是机器学习的底层原理。这一点想通能帮你少走很多弯路。6. 新手实践路线图与踩坑记录6.1 四周渐进路线从 API 到小产品如果让现在的我重新入行我会给自己排一个非常明确的四周计划分享给你参考第 1 周API 与结构化输出。目标是把模型调用练到条件反射每天做一个小任务让模型做翻译、做分类、抽 JSON、限长输出、换不同模型对比效果。这周结束前你要能不看文档写出一个完整的 chat completion 调用。第 2 周函数调用与 ReAct 循环。给模型定义两三个工具天气、计算、时间手动实现 15 行左右的 ReAct 循环跑通一个让模型自己选工具、自己多步完成的端到端任务。这周结束前你要能跟别人说清楚“决策、执行、反馈”这三个环节各自在代码里是哪一段。第 3 周记忆与对话体验。引入 SQLite 存储对话历史做一个简单的长期记忆召回同时优化上下文截断策略。这周结束前你的 Agent 应该能记住三天前聊过的事情。第 4 周选一个框架做一个完整小产品。用前面学到的知识快速理解某个框架的文档然后做一个真实可用的东西——比如小红书自动回复、内部知识库问答机器人、自动整理周报的工具随意。因为你的底层基础已经在这周你对框架的学习速度会快到让自己都惊讶。这个路线图最大的特点就是逆向学习先懂原理再学框架。你在第 4 周学到的框架知识会像长在自己身上一样牢固因为你清楚框架每一行都是在替你完成什么。6.2 新手最容易翻车的五个现场我把自己和身边朋友踩过的坑整理成一份问题速查表你在开发过程中遇到类似现象可以直接对号入座现象根本原因排查/解决办法Agent 陷入死循环反复调用同一个工具缺少循环次数上限或工具返回结果不够明确模型无法判断结束设置max_iterations检查工具返回的内容是否清晰是否提供了足够决策依据模型生成的 JSON 总是解析失败没有启用结构化输出提示词中的格式说明不具体使用 JSON 模式在提示词中给出完整示例要求严格按示例输出上下文越长回答越来越慢且贵没有做上下文截断历史对话无限累积只保留最近若干条消息把早期对话总结成摘要后放入上下文模型调用了错误的工具工具描述太笼统多个工具功能边界模糊改写 description明确使用场景必要时限制tool_choice指定某个工具框架一升级代码就废全局散落框架 API 调用没做隔离把框架相关的调用集中在一个 adapter 层升级时只改一处其中第一个问题最容易被忽略也最值得警惕。很多新手觉得“模型肯定知道什么时候停下来”实战中你会发现它会一意孤行地重复动作。这不是模型笨而是你的工具返回信息让它误以为任务还没完成。所以设计工具返回内容时尽量返回“结构化的事实 一句结论”比如{rain: true, summary: 将有大雨}模型更容易据此判断下一步。6.3 我的最后建议把“框架”当资料而不是当答案说到最后我想分享一个未必能写进教程的判断框架资料不是用来“学”的而是用来“查”的。你真正需要记住的是自己动手实现过一遍的 Agent 原理和那些让你头疼过的坑。当有人问我“Agent 新手该先学什么”时我会说——先学提示词、学 API、学函数调用、学那个朴素的循环和循环里的每一步输出观察。这些不会因为某个框架过时而失效它们就是这行的底层语言。把底层语言练熟了无论是 LangChain 将来被什么新框架替代你随手就能迁移过去。反过来说如果你一上来就把时间压在某个框架的 API 细节上赌注就押在了别人随时可能更改的规则上。我在带一些转行的朋友时反复叮嘱一句话你能在纸上不依赖文档画出自己 Agent 的数据流转图画得出模型在哪、工具在哪、循环在哪、记忆在哪才算真的入门。画不出就继续拆、继续手写。这个过程不会太长但一定值得。最后再分享一个我自己的小习惯每做完一个 Agent 项目我会把“这个项目里框架帮我解决的真问题”和“框架实际没能解决、还得我自己改的问题”各记一条。攒多了你就能发现框架解决的问题其实大同小异而那些框架没能解决的问题才是一个 Agent 做得比别人好的真正差异化所在。把精力放在后者你会走得更远。