如果你最近动了学习AI Agent的念头，大概率已经刷到过不少框架的教程，比如LangChain、LlamaIndex、AutoGPT这类名字。我要先泼一盆冷水：新手和转行者，千万别一上来就啃框架。这不是保守，而是效率问题。我带过不少从零开始学Agent的同事和学员，见过太多人把第一个月的时间全砸在框架上，结果几个月过去，除了会改Demo，离开教程连一个能跑的Agent都写不出来。这篇文章不为任何框架站台，只讲我实际验证过的入门顺序：先掌握Prompt、API调用、上下文管理，再理解Agent的三要素，最后才轮到框架。按照这个路径走，你大概几周就能建立完整心智模型；反过来先啃框架，大概率会在第三周开始怀疑自己是不是不适合干这行。
适合看这篇的，是准备进入AI应用开发的新手、想转行的非科班从业者，以及那些已经装了LangChain但被文档劝退的人。文章会尽量少一点术语轰炸，但该讲透的原理一个都不少。
1. 为什么劝你别先学框架：它把最重要的过程藏起来了
1.1 框架是加速器，不是教材
框架解决的是“重复劳动”问题。比如你要做一个带记忆的对话机器人，用框架可以一行代码把历史记录塞进上下文，再一行代码接上某个检索器。这确实方便，但代价是——框架把“为什么”全部替你消化掉了。
举一个不太恰当但很好懂的例子：学开车，驾校不会让你第一天就上赛道开F1。你总得先搞明白油门、刹车、方向盘和路况的关系。框架就是那辆F1，它把大量操控细节封装进了电子辅助系统，你一上车觉得“哇这也能自动”，但你完全不知道车是怎么保持平衡、怎么过弯的。一旦车辆报错，或者产品需求变了，比如想换个模型、加一种不常见的工具，你没有任何能力去判断哪里出了问题。
我在项目里遇到过一个真实的案例。一位同事直接用框架搭建CoT推理链条，当时跑通了。但第二天框架升级，某个核心类改了个接口名，代码立刻全线崩掉。他没有源码阅读习惯，也不清楚底层逻辑，结果花了整整三天才定位到只是构造函数参数变化。这个时间成本，放在学习期几乎是劝退级的。
1.2 框架的抽象层数太多，报错信息你根本看不懂
你想想看，用框架跑Agent时，一条报错信息的链路上游可能走过了Prompt模板渲染、工具注册中心、回调机制、流式协议封装、模型接口适配器五层抽象。任何一个环节出错，打印出来的Traceback都长到根本不想看。想查原因，你得从LangChain源码一层层扒到底层OpenAI SDK，这对新手来说是灾难级的阅读量。
而直接裸写API调用，一次请求的报错结构简单到一目了然：状态码、响应消息、是网络问题还是参数格式问题，全在眼前。我不是说抽象不好，而是说——你得先见过“裸写”的样子，才有能力理解“抽象”的价值。任何框架的学习，都建立在你已经知道它到底替你干了什么的基础之上。
1.3 入门路径的底层逻辑：先确定性，后不确定性
AI Agent开发最特殊的地方在于：它混合了“完全确定的代码逻辑”和“完全不确定的模型输出”。你写的工具函数是确定性，模型选择是否调用是确定性，如何解析结果也是确定性；唯独模型的理解和推理是概率性的。
新手应该先把确定性那部分练到滚瓜烂熟，比如如何发一次API请求、如何解析JSON、如何维护会话消息，然后再去面对不确定性——也就是模型行为调优。框架本质上就是无数个“确定性逻辑”和“不确定性决策”的编排器。你不懂前者的细节，就永远没法驾驭后者。
打个比方：学做菜。新手先学怎么切菜、怎么看火候、怎么调味，这是确定性基本功。然后才学自由配菜、临场发挥。框架是那个“自动炒菜机”，你把食材丢进去按个按钮确实能出菜，但你永远学不会炒菜。最后客人说“味道淡了”或者“少放点盐”，你连要调哪个旋钮都不知道。
2. 第一课：把Prompt Engineering当成写作训练
2.1 你不是在写代码，你是在指挥一个高智商实习生
很多新手低估了Prompt的重要性，觉得这不就是写几句话吗。可实际上，Agent开发里60%以上的效果问题，根源都在Prompt上。我经常跟团队说：大语言模型不是一个工具，而是一个“知识渊博但没有工作经验的高智商实习生”。它什么都懂一点，但没有你的业务上下文，没有你的纪律约束，也没有你的质量标准。你对它说的话，就是全部约束。
所以写Prompt本身就是编程，只是一门特殊的编程——你在跟一个概率模型做沟通。同样一句话，换个措辞，效果天差地别。这不是玄学，背后是模型在预训练阶段见过的模式决定的。
2.2 一套可复用的Prompt四要素结构
我测试过几百条Prompt之后，沉淀出一套稳定可靠的结构，任何Agent场景都可以套用：角色、任务、约束、示例。这四块缺一不可，少一个，输出质量就下降一个档次。
你是一位专业的内容审核助手（角色）。 你的任务是从用户输入中提取商品名称、价格和库存状态，并输出为JSON（任务）。 约束： 1. 只输出JSON，不要附加任何解释； 2. 价格取数字，不要带货币符号； 3. 如果库存未知，输出null。 示例： 输入：iPhone 15 128G 售价5999元 有现货 输出：{"商品": "iPhone 15 128G", "价格": 5999, "库存": "有"}这个Prompt能稳定工作，不是因为句子写得漂亮，而是因为：角色缩小了模型的知识搜索范围；任务限定了功能边界；约束列清楚了不能做什么；示例给模型提供了一个“输出模板”。特别是示例，这一条对输出格式稳定性的贡献最大，比你在Prompt里强调一百遍“不要输出其他内容”都管用。
新手常见的错误是只写角色和任务，不写约束和示例。然后模型开始自由发挥，输出一堆带“好的，我来帮你……”之类的客套话，或者把JSON格式输出得乱七八糟。你要意识到，模型不是故意的，它只是没有收到足够清晰的边界。
2.3 从单条Prompt到对话链：Agent的雏形
Agent不是一次Prompt问答，而是一连串Prompt的接力。打个比方：用户说“帮我查一下上海明天会不会下雨”。Agent拿到这句话，第一条Prompt负责“意图分析”，判断这是需要调用工具的问题。第二条Prompt负责“参数提取”，从用户话里抽出一个日期和城市。第三条Prompt在你成功拿到天气数据后，负责“结果组织”，把数据变成人能读懂的完整回复。
这个过程，业界叫Chain（链）或者Pipeline。而在这个链条里，每一次模型的调用，本质上都是一次Prompt的传递和结果解析。你可以完全不依赖框架，只用几段代码加三次API调用就把这个流程跑通。这反而是理解Agent最重要的一课：Agent不是一个魔法，它就是一连串“小决策”的串联。
3. 第二课：摸清LLM应用的骨架——调用、上下文与流式输出
3.1 裸调API是基本功，别怕重复造轮子
我坚持认为，每个学Agent的人都应该至少亲手写过一次裸调大模型API的代码，而不是直接装SDK。这就像学机器学习，数据清洗造轮子的那段路一定要走，否则你后面调库调得一头雾水。以最常见的兼容接口为例，一次最简单的调用大概长这样：
import requests url = "https://api.example.com/v1/chat/completions" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", } payload = { "model": "gpt-4o-mini", "max_tokens": 100, "temperature": 0.3, "messages": [ {"role": "system", "content": "你是一个简洁的助手"}, {"role": "user", "content": "什么是Agent？"}, ], } resp = requests.post(url, json=payload, headers=headers) data = resp.json() print(data["choices"][0]["message"]["content"])这段代码虽然糙，但它把一切底牌都摊在桌面上了。你会看到消息列表由system、user、assistant三种角色组成；你会理解system是给模型“人设和指令”的地方；你会知道最终回复藏在一个选择了哪个候选输出的数组里。
有人会觉得，用SDK不是更简洁吗？对，生产环境当然应该用SDK。但学习阶段，请你务必裸写一次。因为SDK帮你做的“消息组装”“请求重试”“错误处理”，正是你未来排查框架问题时最需要理解的底层知识。没见过底层的人，遇到“消息格式非法”这种报错根本不知道从哪里下手。
3.2 上下文窗口是硬约束，管理Token就是管理钱包
上下文窗口是指模型一次最多能“看到”的Token数量。很多人以为这个数字越大越好，实际用起来远远不是这么回事。首先，模型在长上下文下会出现“中间遗忘”现象，也就是说，几百条历史消息塞进去，模型可能只专注于开头和结尾，中间的细节直接忽略。其次，上下文越长，每次请求的成本越高、延迟越高。
你要管理Token，就像管理钱包。一个典型的对话应用，假设每轮用户消息300Token、回复500Token，如果完全不做压缩，10轮对话之后你就得往上下文里塞8000Token，这几乎就是一个小型灾难。所以实际项目里，大家普遍会做以下几件事：
- 滑动窗口：只保留最近N轮消息，更早的丢弃或做摘要。
- 摘要压缩：把十轮对话的要点压缩成一段200Token的总结，替换原文。
- 向量检索：把历史对话存入一个本地向量库，每次只检索出相关的3到5条片段拼进上下文。
这些能力，框架都提供了便捷方法，但你必须先理解它们解决的是“上下文管理”问题，才能在具体场景里做出正确取舍。我见过一个团队，为了让Agent“记住”更多，盲目把历史全塞进上下文，最后token成本翻了十几倍，回答质量反而变差了。这就是不学底层逻辑直接上框架的代价。
3.3 流式输出：用户感知和成本控制的平衡点
另外一个几乎所有Agent项目都绕不开的基本功是流式输出。模型生成一个200字的回答大约需要几秒钟，如果等全部生成完毕再一次性返回，用户会感觉卡死了一样。流式输出就像水龙头，模型每喷出一段字节，你立刻就把它转发给前端，用户看到的是“字在逐个蹦出来”，感知延迟大幅降低。
在裸API调用里，只要在请求里加一个参数：
payload["stream"] = True然后把响应按行读出来，不断把解析后的增量内容传给前端即可。这个能力理解起来不复杂，但它是Agent体验的基石。尤其是你要把Agent包装成聊天机器人、浏览器插件或者企微机器人时，几乎所有场景都需要流式返回。框架里同样提供了封装好的Stream协议，但你不先理解“它到底是怎样一段一段吐字的”，出了问题根本没法调。
4. 第三课：搞懂Agent的定义——大模型加工具加循环
4.1 Agent不是聊天机器人，核心是自主决策
很多人对Agent的理解停留在“能对话的机器人”。实际上，Agent和聊天机器人的本质区别在于一个词：自主决策。
聊天机器人收到消息，走一遍“理解-生成-回复”就结束了。All Agent则像一个员工：你给它一个目标，它自己规划第一步做什么，决定要不要查资料、要不要调用工具，然后做完一步观察结果，再决定下一步。整个过程是一个循环，直到它认为目标已经完成或者彻底失败为止。
我做过一个实际项目：用户用自然语言查询订单状态。聊天机器人的做法是：把“帮我查一下订单号12345”解析出来，直接查数据库，返回结果。Agent的做法是：先判断用户需不需要外送信息，然后调用订单查询工具，如果订单显示“运输中”，它会继续调用物流查询工具获取实时位置，再结合快递公司的公共接口，拼装一份完整的状态报告。每一步都是模型自主决定的循环决策。
要理解这个区别，关键点在于：Agent的价值不是在单个回答的“质量”，而是整个任务链条上的“路径选择能力”。
4.2 Function Calling的本质：模型只输出意图，代码才执行动作
一提到工具调用，很多新手会觉得神秘。其实它的本质极其简单，模型不会真的去调用你的任何函数，它只是“输出了一个结构化的请求”，然后由你自己的代码去执行这个请求，再把执行结果回传给模型。
完整链路分成四步：
- 你把可用工具的描述以JSON Schema格式传给模型。比如一个查询天气的工具，你会告诉模型“这个工具接收两个参数：city是城市名的字符串，date是日期字符串”。
- 模型根据用户的话，判断当前是否需要调用这个工具。如果确定要调用，它不会直接执行，而是输出一个特殊格式的JSON，内容是“工具名：get_weather；参数：{"city": "上海", "date": "2025-06-01"}”。
- 你的代码收到这个JSON，解析它，然后真正去请求天气API。
- 你把工具返回的结果作为一条消息追加到对话里，再次发送给模型，让模型基于这个结果生成最终回复。
这个模式在其他场景下有个名字叫ReAct（Reason + Act），但本质就是“思考-行动-观察”的循环。你和它的区别只在于，它把“行动”这一步挂到了外部工具上。
新手最容易犯的错误是：期望模型返回什么，就直接把输出当成结果来用。比如模型说“天气是晴天，温度30°”，你就直接把这句话展示给用户了。这是不可靠的，因为模型可能自行发挥，甚至凭空捏造一个天气。正确的做法永远是：只用模型输出去决定“调用哪个工具、填什么参数”，而真正的数据必须以工具返回值为准。
4.3 循环是Agent的引擎：用一个伪代码看清全貌
把前面所有概念合在一起，一个最小Agent的循环只有十行核心逻辑：
messages = [ {"role": "system", "content": "你是助手，可以调用工具完成用户请求"}, {"role": "user", "content": user_input}, ] while True: response = call_model(messages, tools=tool_schemas) if response.is_tool_call: messages.append(response) result = execute_tool(response.tool_call) messages.append({"role": "tool", "content": result}) else: print(response.content) break这个循环，你以后会在LangChain、AutoGPT、BabyAGI所有这些框架里反复看到。它们做的一切本质上都是：更友好的工具注册、更复杂的记忆管理、更强的Prompt模板，以及更灵活的中断和修复机制。但底层骨架就是上面这十几行。
我在给新人培训的时候，要求每个人不看框架，用纯代码把这个循环写出来并跑通三个工具：一个计算器、一个返回当前时间的函数、一个查找文件的函数。做完这个练习，再去看任何框架的文档，他们立刻就能在文档里找到“哦，这个组件就是干这个的”。到了这一步，框架学习就从一个“背API”的过程，变成了一个“验证已知概念”的过程，效率天差地别。
5. 第四课：框架到底怎么学？从需求倒推，而不是从工具倒推
5.1 手写一个最小Agent，先跑通脏活累活
我在前面反复强调裸手写，不是为了让你在生产环境里也这么干，而是为了拿到“我能掌控一切”的信心。具体到实操层面，你可以给自己设定一个小目标：用Python裸API实现一个能用工具查天气的Agent。要求包含下面的核心能力：
- 用一个函数，把tool_schemas传给模型
- 正确解析模型返回的工具调用JSON
- 真正执行工具，并把返回值追加为tool消息
- 设置最大循环次数（比如5次），防止模型反复调用工具不停止
- 每次调用都打印日志，告诉你现在走到了哪一步
这个练习做完，你可以再升级一点点：让Agent支持记忆功能，即自动把前面的关键信息压缩进系统提示词。这样你已经实现了一个简化版记忆机制。
等到你在裸API上碰到并解决过“工具参数格式错误”“模型陷入死循环”“上下文不断膨胀导致调用失败”这三个问题，再开框架教程，心态完全不一样——你不是在学新知识，而是在验收旧知识。
5.2 框架怎么选：明确你的场景需要什么
当你有能力手写最小Agent之后，面对框架就有了判断能力。框架的价值是节省时间，但也是有代价的：学习成本、版本升级风险、封装深度带来的不可控性。所以你的选型逻辑应该是这样：
如果任务是单次调用或者两三次调用就能完成的简单链条，别用框架。用裸代码加一点点模块化设计就够了。比如一个客服意图分类器、一个简单的审查助手。用框架反而要处理一堆抽象类、协议和入口配置。
如果需要复杂编排，比如多个工具自由组合、跨多轮长期记忆、需要并发或者流式分发到多个平台，那框架能提供极大的方便。你可以关注主流的Agent开发框架，但没必要哪个火学哪个。实际选型时，我会先看三点：项目在开源社区的活跃度、文档中文资料是否充足、和你手头主用的大模型SDK兼容性如何。
一个劝告：不要在新手期同时学多个框架。框架更新速度极快，接口说变就变，你同时维护两套框架的知识，只会把自己搞乱。先把一个框架用明白，把租一层抽象的能力建立起来，后面切换到任何新框架都是降维打击。
5.3 入门路上的技能自检清单
在正式上框架之前，建议你把下面这份清单当作“上路前自检”。任何一项不达标，都先别急着安装框架包：
- Python基础：列表、字典、JSON处理、for循环、try/except，至少能独立写五十行代码不卡壳
- HTTP请求：会用requests库发送GET/POST，理解status_code的含义
- JSON处理：能把字典转成JSON字符串、把JSON字符串解析成字典，并提取深层字段
- 并发入门：明白什么是异步任务、什么是阻塞，能理解流式响应里“边收边处理”的逻辑
- 版本控制：会用Git提交代码，能看懂基本的Diff
有些人会觉得“这些我都会啊，能不能直接上框架”。我遇到的实际情况是，所谓“都会”，多数只是眼熟。我建议你找一段真实的JSON样例，写一个Python脚本，把所有字段全部打印出来，并且处理掉字段缺失的情况。做不出来，就回到上面清单去补课。
6. 常见问题与避坑实录
6.1 新手遇到频率最高的四个问题
我把这些年带新人时看到的高频问题整理成一张速查表，建议收藏后对着排查。
| 问题 | 原因 | 解决方法 |
|---|---|---|
| 模型返回的JSON格式总是坏掉，没法解析 | Prompt里没有给出足够强的格式约束，示例数量不足 | 在Prompt里加“只输出JSON”和严格示例；用函数调用的JSON Schema约束输出；解析失败时增加一次“修正调用” |
| 工具调用一直不触发，模型总是直接回答 | 工具描述写得太模糊，或者模型不知道应该在什么时候调用 | 把工具描述写得更具体，注明触发条件；把用户意图和工具绑定的示例放进Prompt |
| Agent会陷入死循环，不断调用工具 | 缺少最大迭代次数限制；模型在一个工具失败的情况下反复重试 | 在循环里加硬性上限；工具调用失败后直接返回明确错误，引导模型换策略或结束 |
| 上下文越聊越长，最后提示Token超限 | 没有做任何历史压缩或滑动窗口 | 实现滑动窗口只保留最近N轮；老对话写入摘要；必要时用检索召回关键信息 |
6.2 我亲自踩过的几个深坑
第一个坑是温度参数（temperature）调太高。早期我想让Agent回复更“有创造性”，把temperature拉到了0.9。结果模型频繁伪造工具参数，把“城市名”都自我发挥成不存在的字符串。后来我把这个参数降到0.2，工具调用稳定性立刻上去。现在所有Agent工具调用链路的默认建议是：温度不超过0.3。如果面向的是数据分析或者代码生成，干脆直接设成0。
第二个坑是函数Schema写得太随意。模型是严格按照你提供的JSON Schema理解参数的。你写“date是日期”，但没给格式，模型就可能给出“2025年6月1日”这种不符合程序预期的格式。正确做法是：在Schema的description字段里明确写“严格遵循YYYY-MM-DD格式”，并为每个参数提供一道示例。你写给模型看的每一个字母，最后都会变成模型行为的一部分。
第三个坑是没有设最大循环次数。有一次我为了做演示，跑了一个Agent，让它自主调研一个主题。结果模型在调用一个不存在的内部接口时反复重试，整整消耗了一百多次API请求，花了十几美元，才被我的代码强制终止。那种时候你会特别感谢循环里那上限数字。现在我的所有Agent工程，迭代上限写死不超过10次，同时每一次调用前先检查全局预算。
6.3 给转行者的时间线建议
如果你是非科班转行，我会建议按下面这个节奏安排前两个月：
第一周：只学Prompt工程，每天写十条不同主题的Prompt并对比输出效果，练出手感。
第二周到第三周：裸调API，完成消息构建、多轮对话、流式输出、Json解析这四个练习。不需要做任何Agent架构的东西。
第四周到第五周：实现一个最小Agent，包含一次工具调用和循环终止逻辑。这个练习不要追求复杂度，而是追求“你能向别人完整解释你的每一步在做什么”。
第六周开始：可以读框架文档了。从你已经掌握的循环出发，先找“AgentExecutor”这类核心模块，理解它和你的手写循环的对应关系，再逐步扩展记忆、检索和外接工具。
这个进程最大的优势是：到了第六周，你其实已经了解了Agent的底层机制，框架这时成了提高效率的工具，而不是让你又爱又恨的黑盒。
最后说点心得
写这篇文章不是劝你永远别碰框架，恰恰相反，框架是你将来肯定会使用的生产力工具。只是我一直坚持一个判断：在AI Agent这个领域，真正拉开人与人差距的，不是谁记住的API更多，而是谁脑子里有一张清晰的架构地图。这张地图的绘制，只能靠一条一条裸API请求、一次次在报错里翻找原因来积累，没有任何框架能替你完成这个阶段。
我实际带人的体会是：凡是能沉住气先写几遍裸调用的，后面学框架的速度快得惊人，而且几乎不太会犯低级错误；反而是那些第一天就装好框架到处看教程的，往往一两个月后还停留在照猫画虎的阶段。如果你也是新手或者准备转行，不妨试试这个顺序，先把“地基”打得扎实一点。等你自己跑通那个最小Agent循环的那一刻，你会回来感谢这个决定。
