1. 为什么我不建议新手一上来就啃框架AI Agent 这个词这两年快被说烂了。只要打开技术社区满屏都是 LangChain、Dify、CrewAI、AutoGen好像不会几个 Agent 框架就不配叫 AI 开发者。但我想先泼一盆冷水越是新手和转行者越别急着接触框架。市面上这些 Agent 框架本质上是在帮你封装底层逻辑。它们提供了现成的记忆管理、工具调用、多智能体协作机制表面上省事实际对初学者来说是个巨大的黑洞。你花三天时间学会了 LangChain 里各种 Chain 的写法跟着官方文档把例子跑通了但问你几个底层问题大概率答不上来LLM 调用为什么是流式的、一个 Agent 的 ReAct 循环是怎么一点点抠出最终答案的、工具返回的结果是靠什么规则被 Agent 理解并继续行动的。这些框架的文档写得天花乱坠每个都宣称自己是 下一代应用范式。但文档永远只为“已经懂的人”服务它默认你理解大模型对话的基本原理默认你知道 Token 和上下文的真实含义默认你分得清 Prompt 里哪些内容是给模型说、哪些是留给代码判断的。对新手来说这种默认就是一道无形的门槛。我的建议很简单先花时间去补不依赖任何框架的底层能力用最朴素的 HTTP 请求调一次大模型接口用几十行代码自己写一个简单 ReAct 循环。等你亲手把一个 Agent 从零搭起来再回头看那些框架你会发现框架每天更新的版本、层出不穷的新概念全都变得无比亲切。那时候你才能判断一个框架到底是解决了真问题还是单纯在制造新问题。这个观点不是我拍脑袋想的。结合我身边做 Agent 应用落地的人聊下来的经验真正能在实际业务里稳定跑起来的 Agent背后往往是简单的结构加上仔细的工程控制。框架负责锦上添花但锦怎么织出来靠的是基本功。所以这篇文章我就从“新手和转行者入门 AI Agent 到底先学什么”这个角度出发把学习路径拆开讲清楚全文用的是我自己的实操体会不搞框架崇拜也不堆华丽词汇。2. AI Agent 入门先学什么五个必补的基本功2.1 先搞懂 LLM 调用的最小闭环很多人口口声声说在做 Agent但问他“大模型接口返回的 message 里content 字段和 tool_calls 字段分别是干嘛用的”他就卡壳了。这不行。你必须先用最原始的方式理解LLM 本身是“无状态的文本映射器”。你给一段输入它给你一段输出。没有网络搜索没有记忆没有自动的工具选择。所有 Agent 的天花板能力都是外层代码一层层叠上去的。最基本的调用闭环是这样的from openai import OpenAI client OpenAI(api_keyyour-key, base_urlhttps://your-endpoint) resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个有用的助手。}, {role: user, content: 请用一句话解释什么是函数调用。} ] ) print(resp.choices[0].message.content)这段代码里没有什么高深的东西就一条 HTTP 请求。你自己能用 Python 的 requests 库对着接口文档手写一遍才真正理解 API 的请求体、鉴权方式、response 结构。这一遍下来后面学什么框架都不虚。实操体会建议每个人都用 fetch 或 requests 裸调一次接口然后打印 response 的完整 JSON。你会发现里面有个 usage 字段里面是 prompt_tokens 和 completion_tokens。看明白这个才能理解为什么上下文一长费用就飙也才算对“Token 是一个计量单位”这句话有了体感。2.2 Prompt 工程Agent 的灵魂不在模型在指令系统Agent 和普通聊天应用的最大区别是多了一层“行为约束”。让模型扮演一个自动化的角色、按指定流程处理问题本质是靠 Prompt 在控制。很多人迷信模型能力总觉得换个大模型效果自然提升实际上 80% 的效果差距出在 Prompt 写得对不对。以我调 Agent 的经验好的 Prompt 至少具备三个要素角色定义、任务拆解、输出格式约束。角色定义告诉模型“你是谁、你服务的对象是谁、你有哪些边界”任务拆解把工作分成几步让模型按顺序推理输出格式约束则把返回结果圈进 JSON 或固定结构的文本中方便程序解析。给你一个我常用的模板你是[角色名]服务于[目标用户]。 你的核心任务是[任务描述]。 请严格按以下步骤执行 第一步[动作1] 第二步[动作2] 第三步[动作3] 所有输出必须以 JSON 格式给出字段包括status, result, reason。 如果信息不足请输出 status 为 need_more_info并在 reason 中说明缺少什么。这个模板看起来简单但实际工作里救了我很多次。以前写 Agent 输出自由文本下游程序解析起来全是坑。强制 JSON 格式后下游逻辑瞬间清爽。记住一个原则Prompt 是给模型看的代码它也需要版本管理、逻辑清晰、可测试。2.3 ReAct 模式Agent 思考与行动的循环机制AI Agent 底层最经典的思想是 ReActReasoning and Acting。通俗点说就是让模型一边思考“下一步该干什么”一边决定“是不是要调用某个工具”然后根据工具返回结果继续思考直到得出答案。网上资料喜欢画流程图我这里用文字描述一下真实运行过程用户问“帮我查一下北京的天气然后告诉我适不适合户外跑步。”模型第一轮输出Thought我想我需要查天气→ Action调用工具 get_weather→ Action Input{city: 北京}。Agent 代码解析出这一串内容执行 get_weather 函数获得返回“北京晴22度微风”。模型第二轮输入里除了原来的用户问题还要加上刚拿到的工具结果。模型再次输出Thought天气很好→ Final Answer适合户外跑步建议穿薄外套。Agent 看到 Final Answer 就把这段文字返回给用户。这个模式的核心在于每一次调用大模型都要把“之前的全部对话 工具返回结果”塞回 messages 里模型才知道下一步怎么做。这就是 Agent 的“上下文闭环”。不要被各种框架的封装吓唬住框架无非是把这套循环打包了而已。你只要自己手写过一次 ReAct 循环再去看 LangChain 的 AgentExecutor、OpenAI 的 function calling就会觉得豁然开朗。2.4 工具调用的设计思维Agent 的能力边界由工具决定Agent 自己不能上网、不能读数据库、不能操作软件这些能力全靠“工具”给它开外挂。你可以把一个工具理解为“一个带描述的函数”。大模型要正确选择并调用工具靠的是函数的描述声明所以工具描述写得越清楚调用成功率越高。这就是“工具的描述是你的第二套 Prompt”。举一个反面例子。你写一个 send_email 工具描述写“给用户发邮件”。模型看到这个描述根本不知道它需要哪些参数、适合什么场景。改进后{ name: send_email, description: 向指定邮箱发送邮件。当用户要求主动联系某人、发送通知或回复邮件时使用。需要提供收件人地址、主题与正文。, parameters: { type: object, properties: { to: {type: string, description: 收件人邮箱地址}, subject: {type: string, description: 邮件主题}, body: {type: string, description: 邮件正文} }, required: [to, subject, body] } }描述里包含了触发条件、参数含义、示例场景。模型一看就知道该不该调用、怎么调用、参数填什么。工具设计上有两个个人经验每个工具只做一件事拆细不贪大。一个工具既要查天气又要查空气质量覆盖面变宽描述就会模糊模型反而拿不准。工具数量不是越多越好。初期控制在 5 个以内模型的选择准确率最高。到 20 个以上GPT 级别的模型也会开始出现选择漂移。2.5 记忆机制上下文窗口和持久化存储的边界Agent 对话一长就会“失忆”这是几乎所有新手都会撞上的墙。根源在于大模型上下文窗口有限且默认不会保存任何历史。最基础的记忆方案是用列表把所有历史消息存进内存每次请求全部带给模型。但这样撑不了几轮Token 一多既贵又慢。工程上常用的策略有滑动窗口只保留最近 N 轮对话摘要压缩把前面聊过的内容定期让模型提炼成摘要替换掉原始长文本持久化存储把关键信息写进数据库在需要时按条件检索注入。稳妥的组合拳是短期记忆用滑动窗口长期记忆落库每次构建 messages 时往系统 Prompt 里插入与该用户相关的检索结果。这一套思路在框架里被封装成了各种 Memory 类但理解了本质你用 Redis、SQLite 也能实现而且更可控。3. LangChain、Dify、CrewAI 等框架到底怎么选3.1 先分清框架的定位层级新手最容易犯的第二个错是把所有带“框架”两个字的工具混为一谈。实际上 Agent 框架大致分三层层级代表定位底层编排库LangChain、LlamaIndex面向开发者提供流程编排、工具调用、记忆封装低代码平台Dify、Coze面向业务或快速验证拖拽配置流程多智能体协作框架CrewAI、AutoGen面向多角色协同任务定义角色后让它们互相对话分工这三层解决的问题不一样。LangChain 适合写代码的人深度定制Dify 适合先跑通产品流程CrewAI 则是你要做“多个 AI 角色配合完成复杂任务”时才派得上用场。我的忠告是入门阶段一个都不要急着上。先用裸代码做两个小项目再挑一个最贴近你业务场景的框架去学。我见过太多人学 LangChain 学了一个月最后发现产品用 Dify 反而更快白白浪费了时间。3.2 一个场景一个选择教你按需匹配框架判断标准非常简单看你是在做“内部工具”还是“外部产品”。如果你要接入公司的业务系统需要大量私有化定制、精细控制 Prompt 与调用链选 LangChain 这类库级方案更合适。它是库不是平台你可以随意嵌入代码。如果你要快速做业务验证、做演示 Demo或者团队里没有全职开发者Dify 这类平台是真香。几分钟就能搭出一个带知识库和工具调用的 Agent。如果你的任务天然是多角色协作的比如让一个“调研员”Agent 去搜资料、一个“分析师”Agent 去写报告、一个“审核员”Agent 去改错CrewAI 的设计更贴近。有一个细节容易被忽略CrewAI 底层依赖不少模型调用多个 Agent 之间来回通信Token 消耗翻倍。很多新人兴奋地搭好流程一算费用直接傻眼。多智能体不是越高大上越好能用单 Agent 完成的任务不要为了复杂度去拆成多 Agent。3.3 既然避不开框架什么时候开始碰前面说了那么多“别急着学框架”但我也说一个明确的时间点当你能做到以下三件事中任意一件就可以正大光明地打开框架文档了能不带框架地写出一个能调用外部天气 API 并给出出行建议的 Agent能说清楚 ReAct 循环每一步发生时程序的调用栈长什么样能在完全没有帮助的情况下为你的 Agent 增加一个自定义工具。满足不了的说明基础还没打牢老老实实回去补基本功。框架能用但不能替代你建立心智模型。4. 零基础搭建你的第一个 Agent完整实操流程4.1 需求定义与架构拆解这一步是很多新手最容易跳过的但它是最值钱的一步。我们先定一个具体的、可验证的小项目做一个“会议纪要助手”。它能接收一段会议文本提取待办事项、负责人和截止时间并按格式输出。拆解下来它需要两部分一部分是 Prompt 把原始文本整理成结构化 JSON另一部分是后端逻辑把 JSON 按固定模板渲染成 Markdown 报告。里面不需要外部工具所以理论上不依赖任何框架用最基础的大模型 API 就能完成。设计时的关键决策是“模型只负责信息抽取和整理不负责排版”。排版这类确定性工作交给代码完成避免模型输出不稳定、格式时好时坏。4.2 手写代码实现 ReAct 循环和小工具我先用最简单的方式实现一个 ReAct 循环骨架然后在此基础上加一个查询工具让它具备“能行动”的能力。下面是核心代码import json import requests from openai import OpenAI client OpenAI(api_keyyour-key, base_urlhttps://your-endpoint) def get_weather(city: str) - str: url fhttps://api.example.com/weather?city{city} resp requests.get(url) return resp.json().get(weather, 未知) TOOLS { get_weather: { description: 查询指定城市当前天气, call: get_weather } } SYSTEM_PROMPT 你是一个会使用工具的助手。当需要查询天气时按以下格式输出 Thought: 你的思考 Action: get_weather Action Input: {city: 城市名} 当获得工具结果后继续思考最终回答时使用 Thought: 你的结论 Final Answer: 对用户的最终答复 def run_agent(user_input: str, max_steps: int 5): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for _ in range(max_steps): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages ) content resp.choices[0].message.content print(模型输出, content) if Final Answer in content: return content.split(Final Answer:)[-1].strip() # 简单解析工具调用 if Action: in content and Action Input: in content: action_name content.split(Action:)[1].split(\n)[0].strip() action_input content.split(Action Input:)[1].strip() try: action_input_dict json.loads(action_input) except: action_input_dict {} if action_name in TOOLS: result TOOLS[action_name][call](**action_input_dict) messages.append({role: assistant, content: content}) messages.append({role: tool, content: str(result)}) continue messages.append({role: assistant, content: content}) return 已达到最大步骤数 print(run_agent(北京今天能出门跑步吗))这套代码虽然简陋但 ReAct 的精髓全在里面。解析工具名、执行函数、把结果塞回 messages、继续产模型输出这就是 Agent 的核心引擎。4.3 让输出结果可控的进阶手段结构化输出上面的代码里文本解析依赖“Action:”这类关键词模型输出稍微不规范就断链。现实工程中我会更倾向于让模型直接返回 JSON然后用 pydantic 做校验。from pydantic import BaseModel class AgentStep(BaseModel): thought: str action: str action_input: dict {} final_answer: str SYSTEM_PROMPT_JSON 你是会议纪要助手。请阅读用户输入的会议内容提取待办事项。输出必须是 JSON格式如下 { todos: [ {task: 任务描述, owner: 负责人, due_date: 截止日期} ] } 不允许输出 JSON 以外的任何文字。 用结构化输出把模型限制住后面的一切处理都变得异常舒适。这也是我给所有新人的建议大模型的输出越结构化程序就越稳定。自由文本是 Agent 的敌人约束格式是 Agent 的朋友。4.4 现场记录跑通这个小 Agent 的过程与坑我实际跑上面代码的时候遇到过三个非常典型的问题这里如实记录一下。第一次跑模型把 Action Input 的 JSON 里用了单引号json.loads 直接崩溃。这是我预料之中的坑所以我在解析前加了异常处理。后来我干脆在 Prompt 里强制要求“Action Input 必须是合法 JSONkey 必须用双引号”崩溃率明显下降。第二次跑模型在同一个问题上来回调用同一个工具形成了死循环。原因是我没有在循环里判断“如果 Action 是刚才调用过的同一个就换一种方式输出”。加了最大步数和重复检测后才彻底解决。第三次是 Token 问题。我把每轮模型输出都塞回 messages工作区一长请求体膨胀响应速度肉眼可见地变慢。后来我只保留最近的 4 轮上下文再把之前的内容压缩成一句摘要速度又回来了。这三个坑几乎每个 Agent 项目都会遇到。新手要是直接上手框架遇到同样的问题根本不知道该去哪里排查因为框架把细节都藏起来了。5. Agent 开发中常见问题速查与排查技巧作为一个踩过不少坑的人我把新手问得最多的问题列了个清单方便你直接对照排查。问题现象可能原因解决办法模型一直调用同一个工具不结束缺少停止条件与工具去重判断设置最大步骤数检测到重复工具调用时强制让模型总结回答输出格式时而 JSON 时而文本Prompt 约束不严格在系统 Prompt 中强调“只输出 JSON”用结构化输出 API 代替纯文本Agent 多轮后越发越慢上下文无限制膨胀引入滑动窗口或摘要压缩控制每轮 messages 条数工具调用参数报错工具描述里的参数示例与函数签名不一致让工具描述与函数参数一一对账并写单元测试覆盖模型乱选工具工具数量多且描述含糊精简工具数量重写描述加入“什么时候该用/不该用”回答带有用户不该看到的内部过程调试信息混进了最终返回值前后端彻底分离Agent 中间过程只写日志最终用户只收 final_answer排错基操我一般按三步走第一步把 messages 完整打印出来看模型到底收到了什么第二步检查工具函数返回的数据格式有没有变化是不是塞了 None 或者空数组第三步把相同的输入丢到 Playground 里手动试看是不是历史上下文干扰了模型判断。很多时候问题不在代码而在“模型当前能看到的上下文”。一个被遗忘的工具调用残留信息可能直接带偏模型下一轮的决策。所以日志里开通“完整 messages 链路的 dump 开关”是你排查 Agent 问题最锐利的武器。另外我还想分享一个独家习惯每次给 Agent 升级 Prompt 后我都会准备一组固定的测试用例自动跑一遍看结构化输出和 Final Answer 的成功率。这些测试用例是基线任何一次 Prompt 修改先过基线再上线。没有基线的 Prompt 改动基本就是盲人摸象。6. 罗列一下入门学习路线与分阶段清单前段时间有位读者问我“你说了半天别学框架那总得有个路线图吧。” 我干脆把路线压缩成了三阶段清单按照这个节奏走新手大概 4 到 8 周能完成基本认知到实战的过渡。阶段学习重点产出物是否需要框架第一阶段第 1 周HTTP 调用大模型接口理解 API 结构写一个最简单的问答脚本一个命令行对话机器人完全不需要第二阶段第 2-3 周ReAct 循环工具函数设计理解上下文与记忆一个能查天气/查任务的单工具 Agent完全不需要第三阶段第 4-6 周结构化输出多工具管理错误处理与日志一个可用于实际场景的垂直 Agent可选若项目复杂度上升可引入第四阶段第 7-8 周对比学习一个主流框架读其源码中关于记忆和工具调用的部分用框架重写第三阶段的项目是个人建议第一阶段尽量压到最短别恋战。API 调用本身没多少知识量快速过一遍就够了。第二、三阶段是真正的体力活和心智积累值得反复练习。一个很关键的心态是学 Agent 不是学“某个软件的说明书”而是学“一套组合思想”。你最终的自由度不取决于你会用哪个框架而取决于你能不能用最小成本拼出自己的流程。我见过用五个 Python 文件加一个 Redis 实现稳定生产级 Agent 的团队也见过用 LangChain 跑 Demo 都经常出错的团队。前者把基本功打在投标上后者把复杂度堆在玩具上。7. 选对模型与部署思路AI Agent 踩坑避雷指南7.1 模型能力的分工原则很多人做 Agent 的时候把所有智能都押在一个模型上。实际工程里更合理的思路是“按任务难度分模型”。简单分类任务比如意图识别、关键词抽取用小模型又快又便宜复杂推理任务比如多步规划、长文生成用大模型保证准确率代码生成任务则可以用专门优化过的代码模型。这个“模型路由”思想能让你的 Agent 成本下降 50% 以上效果反而更稳。我实际测过的组合方案是意图识别用一个小参数模型对话生成用中档模型复杂工具编排才调用旗舰模型。四条链路各司其职Token 费用和响应延迟都控制得相当好。7.2 本地部署与云端 API 的取舍新手常被“开源模型的部署成本”劝退其实要分情况看待。纯做学习和验证直接用云端 API 是效率最高的选择。但如果你的业务涉及敏感数据、需要低延迟离线运行本地部署开源模型就绕不开。本地部署需要关注的指标包括显存占用、推理速度、量化格式。以 7B 级别的模型为例用 4bit 量化大约需要 6GB 显存普通家用的消费级显卡就可以跑起来速度尚可。如果要做高吞吐服务还得考虑 GPU 集群和推理框架优化这部分工作量和成本都不小。我的建议是小项目先在云端跑通逻辑确认 PMF产品市场匹配之后再谈本地化部署。开头就纠结部署细节多半是在错误的地方浪费精力。AI Agent 的核心价值是“解决问题的能力”不是“跑在谁的服务器上”。8. 从入门到能接业务一个真实的转行者经验复盘我个人是从传统后端开发转到 AI 应用方向的当时最大的恐慌也是“框架学不过来”。现在回头想真正帮我打通任督二脉的不是框架文档而是自己在纸上一遍遍画 ReAct 循环的图、手动模拟工具调用的一来一回。那段时间我做了四个小项目命令行天气助手、会议纪要结构化整理、微信群自动消息汇总、还有一个小型 RAG 客服问答机器人。其中每个项目都没有用现成的 Agent 框架全部基于 OpenAI SDK 加 requests 手写。日记账本上大概记了两万字的心得也积攒了大量“参数调整的直觉”。这些直觉在后来看 LangChain 源码、甚至自己写轻量内部框架的时候发挥了决定性作用。有一位我认识的转行产品经理用了完全相反的路径她先考完一堆框架认证开口闭口都是“我这个 Agent 用了 LangChain 加 Chroma”但面试官让她现场设计一个“自动订餐 Agent”的工具调用流程她画了一个小时也画不利索。后来她花了三周老老实实补基础概念再回头看那些框架教程发现有 80% 的内容她之前根本没看懂、只是记住了名词。这两个例子没有谁更聪明差别只是学习顺序。框架是“已知正确答案的总结”但如果你连问题本身都看不懂看答案也没有意义。9. 推荐阅读材料与下一步探索方向既然你不该只盯框架那应该看什么我给你列一个精简过的清单概念类OpenAI 官方文档中关于 Function Calling、Structured Outputs、Agents 的说明这是最权威的基础论文类ReAct 原论文是必读的篇幅不长但读完能理解 Agent 的思想源头源码阅读挑一个你感兴趣的框架不要从头看到尾只读其 agent 执行循环、tool registry、memory 三个模块实践类Kaggle、GitHub 上有大量 “minimal agent” 项目找那种几百行代码以内的小项目直接读源码比看几千字的教程高效得多。进阶方向上如果你已经能驾驭单 Agent下一步可以考虑多 Agent 协作、复杂工作流编排和主动学习型 Agent。这些方向都建立在你对底层理解足够深的前提下否则只会陷入框架的术语海洋。我个人后续打算做的内容方向是把一套“轻量内部 Agent 框架”的演进过程完整记录下来包括从零手写的 v0.1 版本、到逐步抽出工具注册表、记忆模块、重试机制、再到接入更稳定模型的过程。这既是对我自己的工程复盘也是一个给新手看“框架从哪来”的活教材。如果你对这个方向感兴趣可以顺着这个思路自己先做一版遇到的问题越多进步越快。