去年我朋友从后端转行做 AI 应用兴致勃勃问我该先学哪个 Agent 框架。我反问他你会写 Prompt 吗你知道 Token 怎么算吗他愣了一下说这些不都是调包的事吗。这其实就是大多数新手和转行人最容易踩的坑。AI Agent 的火爆带来了一堆框架名词——LangChain、Dify、CrewAI、MetaGPT满屏都是xxx 框架入门到精通。很多人一上来就打开框架文档跟着示例敲了两天代码结果连 Agent 的核心机制是什么都没搞明白最后做出来的东西换个场景就废了。这篇文章的目标非常明确带你先放下框架搞懂那些真正构成 Agent 能力边界的底层概念——大模型调用、Token 机制、函数调用、上下文管理、ReAct 循环。等你把这些基本功打通了再回头看框架会发现它们其实只是把你要做的事提前封装好了。我会用实际踩坑经历和可复现的代码示例帮你把这条学习路径走清楚无论你是零基础新手还是后端/前端转行者按这个顺序学比直接啃框架效率高得多。1. 为什么新手和转行者容易陷入框架焦虑1.1 框架狂热背后的真实原因先从我自己这几年的观察说起。AI Agent 方向在圈子里越来越热各种框架的 GitHub Star 数涨得飞快社区里每天都有人在晒Dify 接入小红书自动发消息用 CrewAI 做了一套自动化市场调研之类的成果。这种氛围特别容易给人一个错觉学 Agent 就等于学框架选对框架就赢了一半。但这里有个非常关键的盲区。框架解决的是工程化协作问题它负责把大模型调用、Prompt 组装、工具执行、结果解析这些流程串起来。框架本身不产生智能它只是把一个基础模型包上了一层手脚。你真正要解决的问题——让模型理解任务、合理规划步骤、正确调用工具、从错误中恢复——全部发生在那层框架看不到的地方。我记得有一次帮一个朋友排查他基于 LangChain 做的问答机器人发现他的 Agent 在遇到一个稍微绕弯的问题时就开始胡说八道。排查到最后问题根源根本不在框架而是他连模型上下文里放了什么东西都没搞清楚工具返回的长文本把上下文塞爆了模型早把原始用户需求给遗忘了。这种例子在社区里太常见了。1.2 过早啃框架的三种典型翻车现场我总结了三种我亲眼见过、自己也经历过的典型翻车场景你们可以对号入座。第一种叫API 黑洞型。这类人一开始就学了框架然后按教程往代码里填 API Key跑通了 demo 就觉得自己会了。等要做自己的项目时连 API 请求的返回结构都看不懂模型返回的 JSON 解析不了更不知道 temperature 和 top_p 是干什么用的。第二种叫死循环型。框架确实能帮你组装出 Agent但很多人根本不知道 Agent 内部有一个思考-行动-观察的循环。结果就是 Agent 反复调用一个失败的函数自己进入死循环Token 像流水一样烧掉他们还以为是网络问题。第三种叫选型瘫痪型。今天看 LangChain 生态最全明天看到有人说 Dify 做业务应用更快后天又觉得 CrewAI 的多角色协作很酷。一个项目还没做起来光在选框架上就纠结了两周。这三种翻车有个共同点都想跳过底层的为什么直接拿到怎么做的答案。但 Agent 这行跳过为什么恰恰是最大的弯路。2. 真正值得先学的AI Agent底层基础2.1 大模型工作原理与Token的直觉理解很多人天天说调大模型 API但没认真想过大模型到底是怎么理解你的输入的你把它想象成一个超级强的接龙选手就很好懂了——它根据你已经给它的所有文字也就是上下文预测下一个最可能出现的字或词然后一个一个往外蹦直到形成完整回答。它没有真正的逻辑推理它只是在做概率计算。这就引出了 Token 的概念。Token 是模型处理文本的最小单位一个 Token 不一定是完整单词中文里一个汉字往往对应一两个 Token英文一个常见单词通常是 1 个 Token偏门的长单词可能被拆成 2 到 3 个。模型收费就是按 Token 算的你的提问、它给你的回答、你塞进去的历史记录全部都在计费范围内。我强烈建议新手在学 Agent 之前先学会感知 Token。怎么感知两个办法一是用 OpenAI 官方的 Tokenizer 工具把你的一段中文贴进去看看它会切成多少 Token二是在代码里用 tiktoken 库统计。我让新人在笔记本上记录一段 200 字的中文 Prompt 大概消耗多少 Token这个习惯能帮他们建立成本意识避免后面 Agent 烧钱无感。理解 Token 为什么重要因为 Agent 的所有设计——记忆管理、上下文压缩、工具调用、多轮对话——本质都在围绕一个约束做文章有限的上下文窗口。窗口是模型一次能处理的 Token 上限比如 128K、200K听上去挺大但一旦你在工具返回里塞了 50 行日志、在历史记录里存了 10 轮对话几百行就没了。你连窗口都没概念怎么设计 Agent2.2 Prompt工程Agent的控制语言如果说大模型是发动机Prompt 就是你踩油门的脚。Agent 跟普通单次问答的差别恰恰在于用 Prompt 维持一个持续运行的系统。很多新手以为 Prompt 就是给模型一段话让它做事但 Agent 场景下的 Prompt 有完全不同的要求。第一Agent 的 System Prompt 不是一句指令它是一份完整的岗位说明书。它要包含角色定位你是谁、任务边界你要负责什么不负责什么、工作流程先做什么后做什么、输出格式必须返回 JSON 还是 Markdown、工具使用规则什么情况下调用工具、工具返回错误怎么办。一个合格的 System Prompt读起来像新员工入职手册而不像一句话命令。第二Agent 的 Prompt 里往往还有动态插槽。比如你想让 AI 基于用户问题判断调用哪个工具你就可以在 Prompt 里预留一个{tools_desc}位置运行时把工具列表描述注入进去。我踩过的坑是把工具描述写得太长太啰嗦每个工具几百字结果上下文被描述占掉一大块模型反而在决策时不够聚焦。后来我用表格化短句重写工具描述每条不超过 50 字决策准确率明显提升。第三Prompt 里要有错误恢复策略。真实世界的 Agent 一定会遇到工具调用失败、返回空值、用户把话说一半这类情况。你要提前在 Prompt 里写清楚若工具调用失败请明确告知用户暂时无法获取该信息不要编造。这一步不加你的 Agent 就会自己脑补答案做出来的东西完全没法用。我能给出的实操建议是新手先拿一个简单任务练手比如查询天气并生成穿衣建议把 System Prompt 写成五个段落——角色、任务、流程、输出格式、边界与容错。跑通之后再看看哪些地方模型行为不符合预期逐句调整 Prompt。这叫Prompt 调优的反馈闭环比背任何框架 API 都管用。2.3 函数调用让Agent与外部世界握手Agent 跟普通聊天机器人最本质的区别就是它能调用外部工具——查数据库、发 HTTP 请求、执行代码、操作文件。这个大杀器在技术上叫 Function Calling函数调用你要把这四个字刻在脑子里。它的工作流程是这样的你定义一批函数每个函数有名字、描述、参数结构JSON Schema把这些定义连同用户问题一起发给大模型。模型不直接执行你的函数它只做决策——这个问题需要调用search_products函数参数是{category:手机}然后以结构化 JSON 格式返回给你。你的代码收到这串 JSON再真正去调用函数把结果传回模型。你可以把它理解为模型是大脑你的代码是手函数调用是两者之间的指令通道。新手阶段我不建议直接用框架封装好的 Tool 类而是用最原始的方式自己实现一遍。我用一个非常简单的天气查询例子说明import json from openai import OpenAI client OpenAI() # 1. 定义函数交给模型做决策 tools [ { type: function, function: { name: get_weather, description: 查询指定城市的实时天气, parameters: { type: object, properties: { city: {type: string, description: 城市名如北京、上海} }, required: [city] } } } ] # 2. 第一轮请求把用户问题 工具定义发给模型 messages [{role: user, content: 北京今天适合穿什么}] resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools, tool_choiceauto ) # 3. 判断模型是否要求调用函数 msg resp.choices[0].message print(msg.tool_calls[0].function.name) # get_weather print(msg.tool_calls[0].function.arguments) # {city: 北京} # 4. 你拿到参数后真的去调天气 API拿到结果 weather_result {city:北京,temp:12,cond:阴} # 5. 把工具结果回传给模型 messages.append(msg) messages.append({ role: tool, tool_call_id: msg.tool_calls[0].id, content: weather_result }) final_resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages ) print(final_resp.choices[0].message.content) # 北京今天阴气温12度建议穿夹克或薄毛衣这 20 行代码就是所有 Agent 框架工具调用的原始内核。LangChain 里的tool装饰器干的也是这件事只不过帮你把定义和解析封装了。你亲手实现一遍才能理解模型输出里roletool是什么意思、tool_call_id用来做什么——这些细节在框架里被隐藏了一旦出问题你根本无法排查。3. 编程能力怎么补Agent入门的必备技能栈3.1 Python基础与异步编程做 AI Agent 开发Python 几乎是默认语言不用把语言学到精通再开工核心语法掌握就够了列表推导、字典操作、函数定义、类与装饰器、异常处理。异常处理必须重视因为 Agent 运行的一半时间都花在工具出错后怎么恢复上。我之前写过不少脚本起初 agent 一旦遇到超时就直接崩后来把所有工具调用包进try...except并返回结构化错误信息整个系统才可靠起来。异步编程是很多转行者的盲区。Agent 的本质是一个要频繁等待外部 API 返回的过程如果你用同步代码一个个调用一个任务里有 5 次工具调用每次等 2 秒总共等 10 秒用户早就走了。异步用async/await可以并发执行多个工具调用性能提升是肉眼可见的。我自己带新人的时候会给一个练手小任务写一个异步函数同时向三个不同的大模型 API 发起请求然后汇总三条结果再让其中一个模型做总结。这个小任务能让你真切感受到等待和并发的区别。别岔开去学什么 asyncio 源码先会用asyncio.gather就够了。3.2 API调用与数据处理AI Agent 离不开 API这里的 API 不只是大模型接口还有你接入的各种外部系统接口查询数据库的、发 HTTP 请求的、调用第三方服务的。新手至少要吃透以下几点。首先是 HTTP 请求的基础GET 和 POST 的区别、请求头里的Authorization怎么带、requests库和httpx库的基本用法以及超时和重试的处理逻辑。我遇到过很多次 Agent 工具调用莫名其妙卡住最后发现是没有设置timeout一个外部请求把整个 Agent 阻塞住了。后来我在所有外部 HTTP 调用里统一强制加timeout10问题立刻消失。其次是 JSON 数据的处理。大模型接口的返回、工具函数的参数、Agent 的内部状态传递在绝大多数实现里都用 JSON 串起来。你得熟练使用json.dumps/json.loads学会用字典取值而不是靠正则硬拆。这里有个高概率踩坑点模型返回的 JSON 偶尔会不合法可能是缺了个括号或者带了多余的 Markdown 代码块标记。你要为这种情况做兜底——先尝试json.loads失败就提取代码块内容再解析再不行就返回错误信息让模型修正输出。没有兜底的 Agent跑两天肯定会在某个深夜输出 JSON 解析错误让你爬起来修。3.3 动手从零实现一个不依赖框架的最小Agent我前面铺垫了这么多基础概念现在把它们串起来。你按下述步骤写不依赖任何 Agent 框架。这个最小 Agent 的目标是用户问天气Agent 自行判断调天气查询工具再总结回答。完整代码就是 2.3 节那段代码的扩展增加一个工具调度器把用户问题发给模型判断返回内容里是否有tool_calls有则解析函数名与参数并执行对应工具函数把结果回传进入下一轮循环没有tool_calls就直接把模型回答返回给用户。这个循环——模型返回工具调用指令、你执行工具、把结果喂回模型、模型生成最终回答——就是 ReActReasoning Acting模式的雏形。LangChain 里 Agent 帮你做的是同一件事只是它把调度封装成了AgentExecutor。你亲手实现一遍这个不到 60 行的小循环我可以保证你再看任何框架的 Agent 源码都不会觉得它是黑盒。我在团队里带新人都会让他们把这个小 Agent 作为结业作业。标准有两个一是能正确处理工具调用失败并回复用户暂时查不到二是能控制在 2 轮循环内完成天气查询任务。这个练习做完再进入框架学习心态完全不同——你是带着我知道底层发生了什么的底气去看框架的。4. 理解Agent的核心架构与主流设计模式4.1 ReAct 模式与 Agent 思考循环我在 3.3 节实现的最小 Agent本质上就是一个 ReAct 模式的简化版。ReAct 的全称是 Reason推理和 Act行动的结合它让模型在每一步先输出一段思考说明当前要干什么、为什么然后才输出要执行的行动。这个思考行动观察结果的循环不断重复直到得到最终答案。举一个更生活化的例子。你让 Agent 帮你规划从北京去上海出差顺便查一下沿途天气。ReAct 模式下它大致会这样做思考——用户想去上海我应查北京到上海沿线的天气情况行动——调用天气查询工具观察——工具返回沿途多个城市的天气再思考——天气信息已收到我现在整理成行程建议最后输出回答。这里核心要理解的是模型每轮只做下一步决策而不是一次性完成所有事。这种设计带来一个巨大优势——你可以随时把用户的需求插入到循环中也可以随时中断一个执行得不好的 Agent。我在实际项目里遇到 Agent 跑偏的情况处理方式通常是回溯 prompt、精简工具描述同时基于观察结果补充规则让它在下一轮循环里自我修正。这是 ReAct 的核心思想不追求一次答对追求在循环中不断修正。4.2 记忆、规划、工具Agent三大核心模块理解 Agent 架构你只需要掌握三个词记忆、规划、工具。记忆解决的是Agent 是否能记得更早的对话或结果。注意它分短期记忆和长期记忆。短期记忆就是把聊天历史塞进上下文窗口这是最简单也最常见的方式长期记忆一般把关键信息存到向量数据库里用相似度检索的方式在需要时取回。RAG检索增强生成本质上就是为 Agent 注入长期记忆的一种手段。我见过很多人把 RAG 和 Agent 混为一谈简单区分RAG 是给模型找参考资料Agent 是让模型自己决定怎么用这些资料做事。规划解决的是复杂任务怎么拆解。最简单的思路是让模型自行决定步骤也就是 ReAct进阶一点的用 Plan-and-Execute 模式先让模型生成一个计划再一步步执行每一个子任务再复杂一点就是多 Agent 协作——不同角色的 Agent 分工配合类似 CrewAI 做多角色编排。新手我建议先琢磨单 Agent 的 ReAct别一上来玩多 Agent那种多角色协作看起来炫酷但在没有把单个 Agent 调好之前只会放大错误。工具是 Agent 的手我在 2.3 节已经深入讲过了。三者之间的关系是一个循环模型基于记忆决定要做什么调工具执行观察结果,更新记忆再继续规划下一步。任何框架不管它包装得多花哨底层都是这个循环。4.3 主流Agent框架的本质与选型原则当你理解了 ReAct 循环和三大模块再回头分析主流框架思路会非常清晰。LangChain 的定位是生态和抽象层——它把模型、工具、记忆、向量库都统一封装成接口核心能力是灵活组装但你得适应它的抽象概念学习成本相对高。Dify 更像一个可视化应用平台适合业务背景的人快速搭建很多组件有界面操作底层帮你做了编排。CrewAI 主打角色化协作它把 Agent 定义成一个有角色、目标和记忆的团队角色适合模拟多角色工作流。选型原则其实并不复杂。我的建议是个人学习阶段先用 2.3 节那种手写方式把 Agent 基础吃透做项目时如果你的核心是多个模型 多种工具 事件复杂编排LangChain 这类灵活框架上手性价比更高如果你是业务团队、想快速验证 Agent 应用原型的Dify 这类可视化平台效率最高如果你想研究 Agent 多角色协作机制CrewAI 是不错的观察样本。但无论选哪个框架你都必须能回答三个问题这个框架如何封装记忆如何扩展你的自定义工具它的事件循环暴露到哪一层比如 LangChain 的AgentExecutor会跑完整个 ReAct 循环你要中途干预就相对麻烦Dify 里工具的配置是在界面完成但你没法直接在代码里精调每个次的模型参数。这些理解都是框架外的知识等你手写过一个 Agent一眼就能看懂各家的取舍。5. 新手怎么开始学框架从什么时候到怎么入手5.1 判断该上框架的时机我见过两类极端。一类是前面说的只啃框架不看底子另一类是永远手写一切、拒绝框架。第二类同样不值得提倡。手写 Agent 虽然让你懂原理但工程效率太低做五点足够往后你就会发现大量的时间花在重复实现工具解析、上下文管理上。那什么时候该上框架我认为有三个信号。第一你开始觉得手写代码里有一大段是固定的模板代码——重复实现 tool 定义和消息拼接这时候框架替你省掉的正是这段。第二你开始需要多种外部工具的集成——数据库、邮件、搜索、内部 API逐个手写太重了。第三你开始考虑状态持久化和错误处理的一致性——框架一般会给你一套统一约定。但有一个前提必须重复上框架前你的项目里至少出现过一次手写的 Agent 代码哪怕只有 60 行。带着这个基础去读框架文档你会发现它讲的不是一个陌生概念而是你熟悉的代码的另一种写法。没有这个前提就是我这篇博文标题说的一上来就啃框架的老路。5.2 框架选型与先读文档后动手的路径当你决定上框架选型前先做三件事。第一去 GitHub 看项目的 issue 列表和最近 commit 频率活跃度低的框架慎选。第二去框架官网看它的核心概念图重点看它怎么划分模型、工具、记忆、流程这几个模块。第三找到官方的快速开始教程按照教程跑通一个最小示例体会一下它的编程手感。我拿 LangChain 举个例子。它的核心概念图上至少有 Model、Tool、Memory、Chain/Agent 等几个模块每个都是一个大类。新手第一次看特别容易懵因为抽象太多。我的建议是先只关注 Agent Tool ChatModel 三个模块就好。把ChatOpenAI作为模型配置、用tool定义一个函数、用create_tool_calling_agent组装一个 Agent先让它带你跑通一遍。等你对这套组装逻辑有了体感再去补 Memory、Retriever、Callback 这些边角。在整个上手过程中我强烈建议做的习惯是看框架源码。框架本身就是很好的学习资料你手写过一个 Agent 后再去看 LangChain 的AgentExecutor源码你会看到它循环里其实也有是否调用工具调用后把结果丢回 messages这些你已经懂的步骤。框架源码不是天书读到不理解的地方也不要退怯它对应的就是你学过的那几个概念。看完一遍不仅你掌握了框架本身你的Agent 架构理解也会上一个台阶。6. 实际项目中一定会遇到的坑与排查心得6.1 Token消耗失控我做 Agent 项目初期最痛的经验就是 Token 账单。曾有个月末看后台发现某个 Agent 的日调用成本翻了 5 倍查下来原因很简单——某个工具每次返回一大段数据库日志工具结果被完整塞进上下文然后下轮循环它又被当历史记录保留几轮下来 Token 翻倍累积。解决思路有两个方向。一是节俭上下文工具返回只保留必要字段比如数据库查询只在结果里保留 top 5 条日志只保留错误摘要二是修剪历史多轮对话里把早期对话摘要化保留用户当前轮次和最近两轮细节即可。这里可以使用摘要模型把旧对话压缩成一段总结再放在上下文里。强烈建议新手从一开始就加 Token 用量日志记录每一轮的prompt_tokens、completion_tokens、total_tokens。你用 LiteLLM 或者 OpenAI 的 response usage 字段都能拿到。别等到账单炸了再查连续记录一周你对自己 Agent 的成本结构会有扎实的直觉。6.2 Agent死循环与失败重试死循环是 Agent 项目最常见也最让人头疼的问题。现象是Agent 反复调用某个工具每次工具返回一样的错误比如接口报 500Agent 不停止而是一遍遍重试直到把上下文窗口打满或预算耗尽。排查思路三步走。第一步检查工具返回的错误信息是否足够可行动。如果只是返回调用失败模型不知道下一步能做什么自然会重试。更好的做法是返回调用失败认证失败请检查 token这类带原因的信息。第二步在循环里设最大轮次限制比如 5 轮或 8 轮超出就强制停止并输出当前进展。第三步在 System Prompt 里预先写清楚工具失败后不要无脑重试如果连续两次失败直接告知用户失败原因并停止当前行动。我自己用的是退避封顶策略工具调用外部 API 失败后第一次立即重试第二次等 2 秒再试第三次直接返回服务暂时不可用。目标不是消灭所有错误而是让 Agent 在错误面前保持理性。6.3 上下文膨胀与遗忘问题接续 6.1 的话题上下文膨胀除了烧钱还会带来一个更隐蔽的问题——模型遗忘。有人发现 Agent 聊了好一会儿之后它会忘记最初用户给的约束原因很简单原始需求被淹没在大量工具返回和历史记录里了。这听起来很像人的注意力漂移但背后其实是技术性的注意力权重分布。解决方案有几种。最朴素的是把核心目标反复注入在每一轮的 System Prompt 末尾放上一段不可变的用户原始诉求确保每一轮模型决策时都能看到。这也是很多框架做 persistent system message 的做法。稍微进阶的是关键状态摘要每轮循环结束时用几十个 token 摘要当前的核心任务进展存到上下文替代冗长的原始对话。再往上是把用户意图提炼成结构化状态比如{goal: ..., done: [...], next: [...]}每次只把这份状态和最新观察放入上下文。这个方法相当于给 Agent 建了一个实时工作日志效果非常好。我在团队里的经验是任何单轮工具结果超过 500 字的 Agent 都要做摘要否则后面一定出问题。等到你再往前走还可以用向量库做长期记忆但注意长期记忆解决的是跨任务的持久留存而一日内的上下文膨胀仍然要靠前面说的修剪思路应对。6.4 工具描述被模型误解这类问题很容易被新手当成模型不够聪明而忽略。举个例子我的一个 Agent 同时提供查看订单和修改订单状态两个工具描述里都写了订单 id。结果模型经常在用户只想查订单时顺手把订单改成已发货。排查到最后发现工具描述不够限定——修改订单状态的描述里没有强调仅当用户明确要求变更时才能调用本工具。工具描述其实也是 Prompt。你要把工具描述当作给你的系统 Prompt来写除了功能说明还要写清调用边界什么时候不该调用本工具参数有哪些限制返回结果可能包括哪些格式我建议每个工具描述至少包含一句话说明不应调用该工具的场景。这个技巧在框架层面同样适用为 LangChain 的tool装饰器传入 docstring 时把你认为关键的边界信息写进 docstring效果远好过泛泛描述。结尾写了这么多其实就是想传达一个中心思想AI Agent 不是框架的拼装游戏它是一套涉及模型理解、上下文管理、工具设计、异常恢复的工程实践而框架只是这个实践的脚手架。与其花两周翻框架文档不如用一晚上亲手写一个 60 行的 Agent 循环这种体感是任何文档都给不了的。我当时从手写 Agent 过渡到使用 LangChain 时最大的感受不是框架帮我省了多少代码而是框架里每一步我都能想象到它在背后做什么遇到问题排查起来心里特别有底。最后再送一条我反复给新人讲的原则你在 Agent 方向的市场价值不取决于你背过多少框架 API而取决于你能否设计一个让模型稳定工作的循环以及当这个循环出了问题之后你能不能定位到是 Prompt 的问题、工具设计的问题还是上下文管理的问题。先把这三点吃透你在这个赛道就是站得住脚的。
