AI Agent入门正确路线：先手写核心循环，再学LangChain等框架

直接给你结论：AI Agent 入门最大的坑，不是学不会，而是学太快。很多人一上来就啃 LangChain、CrewAI、Dify 这些框架，结果啃了一周连 Agent 的核心循环都说不清楚，调个 bug 都要翻半天源码。我见过太多转行者栽在这条路上，今天这篇就想把一条相对扎实的路线摊开来说清楚——先学什么、后学什么、为什么顺序错了会事倍功半。

1. 为什么新手别急着碰框架：框架是给会走路的人准备的

1.1 Agent 到底是什么：先搞懂名词背后的实体

先别管那些营销号怎么吹，AI Agent 不是玄学，它本质上就是一个“能自己决定下一步干什么”的大模型程序。普通的大模型聊天机器人，你问一句它答一句，对话的主动权永远在你手里。Agent 不一样，它会拿到一个目标，然后自己拆解成步骤、调用工具、检查结果、失败了重试，直到完成目标或者确定做不下去了。

拆开来看，一个 Agent 的核心实体只有四个：大模型（大脑）、工具（手脚）、记忆（短期和长期）、规划器（决策逻辑）。大模型负责理解和生成，工具负责执行具体动作，比如搜索网页、调用计算器、发邮件、操作数据库，记忆负责记住上下文里的关键信息，规划器负责决定“下一步该做什么”。

这个认知非常关键。因为你会发现，所谓“框架”，做的事情无非就是把这四样东西打包、提供一些现成的接口、帮你管理状态。如果你连这四样东西分别是什么、各自解决什么问题都说不清楚，直接用框架就等于拿着一个黑盒在开发——出了问题你根本不知道是模型的问题、工具的问题还是编排逻辑的问题。

1.2 框架的定位与陷阱：框架帮你省事，也帮你把概念藏起来

市面上的 Agent 框架，比如 LangChain、Dify、CrewAI、AutoGen，核心价值在于把繁琐的工程化问题抽象掉：多轮调用、工具注册、消息传递、状态维护、任务队列、可视化编排，这些底层逻辑交给框架处理，你只需要关心业务逻辑。

听起来很美好对吧？但这里有个致命陷阱。框架的抽象层太厚，新人用起来会发现所有东西都“能用但说不清”。比如你在 LangChain 里写了一个AgentExecutor，它内部到底是怎么调用 LLM 的？工具返回的结果是怎么被塞回 Prompt 里的？什么时候触发 ReAct 循环的下一步？这些问题框架默认不让你看见。结果就是：你复制了官方示例、改了几个参数、跑通了 demo，但脑子里的知识还是空的。

更实际的问题是，框架的版本迭代太频繁。LangChain 从 0.1 到 0.3 的语法变动我已经经历过好几轮大改，网上教程大量过期。新人如果底层概念不牢固，追着版本更新跑会非常痛苦，今天能跑的代码明天可能就报错。嵌在框架里的“魔法”越多，你的可控感就越低。所以我一直的建议是：先用手写的方式、不加任何 Agent 框架、把 Agent 的核心循环从零实现一遍，再回头看框架，你会觉得它们其实就是那么回事。

2. 入门第一课：先把大模型用明白，再谈 Agent

2.1 Token、温度、上下文窗口：这些是 Agent 的基础货币

很多新手跳过了“把 LLM 用明白”这一步，直接进了 Agent 开发，结果连 temperature 调大调小有什么区别都说不清楚。Agent 本质上是在反复调用 LLM，你如果连单次调用的行为都掌控不了，就别提掌控整个循环了。所以第一步不是学框架，而是把大模型 API 的调用参数吃透。

先说 token。Token 是模型处理文本的最小单位，一个 token 大约是 0.7 个汉字或者 4 个英文字符。token 同时是计费单位和上下文长度单位。你在 Agent 里每次携带的历史消息、工具返回结果、中间推理步骤，全部要计入 token 消耗。很多新手做 Agent 发现费用飙升，一查日志才发现把工具返回的十几页 JSON 原文塞进了下一轮 Prompt，这既浪费钱又容易把上下文撑爆。

再说温度（temperature）。这个参数控制模型输出的随机性，取值范围一般是 0 到 2。做 Agent 和做创意写作完全不同——Agent 需要稳定、可靠、可复现的输出，temperature 应该尽量压低，0 到 0.3 之间比较稳妥。调高了之后模型可能在一个简单分类任务上给你输出出意想不到的变体，这在 Agent 循环里会被无限放大，最终表现为“行为诡异”。

上下文窗口（context window）是另一个核心概念。大模型有最大输入长度限制，比如 128K、200K 不等。但这个长度不是你随便就能用满的——当上下文接近窗口上限时，模型对中间信息的注意力会明显减弱，表现为“记不住前面说过的话”。这就引出了 Agent 开发里最实操的问题：你必须在每次请求中控制拼接内容的长度，而不是无脑把所有历史消息都丢进去。

2.2 从一次 API 调用开始：手写一个不带框架的“伪 Agent”

说太多不如写一行代码。先不用任何框架，用最原始的 API 调用做一次带“工具”的对话。假设我们要做一个能查询天气的 Agent，第一步是学会调用大模型 API 并把系统提示词写好：

from openai import OpenAI client = OpenAI() system_prompt = """ 你是一个智能助手。如果你的回答需要实时数据，请基于用户的描述做出合理推测， 不要编造不存在的事实。 """ response = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": "今天出门需要带伞吗？"} ], temperature=0.2 ) print(response.choices[0].message.content)

这里面的关键点不是代码本身，而是你要意识到 Agent 和普通聊天唯一的区别在于循环，而这个循环的起点就是你用代码控制 LLM 的输入输出。一次调用你控制不了它去调用工具，但你可以通过 Prompt 引导它输出特定的 JSON 格式，然后在代码里解析 JSON 来决定下一步动作。这在后面手写 Agent 循环时会非常有用。

2.3 结构化输出是 Agent 的命脉：让模型“说机器听得懂的话”

Agent 与传统聊天之间有个重要的工程细节：你让模型输出自然语言，然后自己去解析；但更可靠的做法是让模型直接输出结构化数据。当前几乎所有主流模型 API 都支持response_format参数，可以强制输出 JSON。这是 Agent 开发里最值得练熟的基本功。

response = client.chat.completions.create( model="gpt-4o-mini", messages=messages, response_format={"type": "json_object"}, temperature=0.0, )

把模型输出变成 JSON 之后，你就可以像操作普通数据一样处理它——判断字段值、做分支逻辑、拼接下一个请求。Agent 循环里的“决策”，本质上就是解析 JSON 字段后走不同的代码分支。所以，在学任何 Agent 框架之前，你能做到“让模型按指定格式输出、稳定解析、不出错”这一步，比会背十个框架的 API 都有用。

3. 真正该啃的基础三件套：提示词、函数调用、记忆管理

3.1 提示词工程：Agent 的“岗位说明书”

很多新手以为 Agent 的提示词就是“你是一个有用的助手”这种级别。真做 Agent 的时候，提示词更像是一份岗位说明书，要写清楚角色定位、可用工具清单、工作流程、输出格式要求、边界和禁忌。

举个例子，做一个“客服质检 Agent”，差的提示词是“你是质检员，请分析对话”，好的提示词至少包含：

• 角色：资深客服质检专家，具备心理学和沟通分析能力
• 任务：逐条分析对话中客服的响应质量
• 工具可用：无（或者可选调评分模板）
• 输出格式：严格 JSON，包含score、issue、suggestion字段
• 约束：只基于给定对话输出，不推测对话之外的背景；评分使用 0-100 整数

写提示词的核心逻辑是降低模型输出的不确定性。你在提示词里给的信息越明确，输出的变异就越小，后续解析和处理就越容易。这也解释了为什么在 Agent 开发里，提示词工程不是“文学”，而是“需求文档”。

但提示词也不是越长越好。我见过有人写两千字的提示词，结果模型在长上下文中迷失了重点，反而输出质量下降。好提示词是结构化的：用标题分节、用列表枚举工具、用示例固定输出格式。学习提示词工程最有效的方式不是看教程，而是拿你的真实任务反复做 A/B 测试，同一段输入配上不同的提示词版本，对比输出结果哪个更稳定。

3.2 函数调用（Function Calling）：给 Agent 装上“手和脚”

Agent 区别于聊天机器人的关键能力是能调用外部工具。现在主流的实现方式叫函数调用。它的原理并不复杂：你把可用工具的描述以 JSON Schema 的形式传给模型，模型在回答时先输出一个“我想调用某个工具、参数是什么”的请求，你的代码收到请求后执行对应函数，再把结果返回给模型，模型基于结果继续生成下一轮回答。

代码层面看，OpenAI 风格的工具定义长这样：

tools = [ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的当前天气", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名，如北京" } }, "required": ["city"] } } } ]

这个定义非常值得新手反复研究。注意我强调顺序：先定义工具的名称和用途，再定义参数结构（类型、描述、必填项）。工具描述写得好不好，直接决定模型能不能在正确场景下调用正确的工具。我踩过的坑是：工具描述里用太模糊的词，比如“获取信息”，模型就会在不确定的情况下反复调用它；把描述改成“获取指定城市未来24小时天气预报”，调用准确率会明显提高。

3.3 记忆管理：别把 Agent 当“金鱼”

Agent 的“记忆”分两层：短期记忆是当前任务的上下文，长期记忆是跨会话存储的用户偏好或历史事实。入门阶段先把短期记忆管理好就够了。

最常见的错误是盲目地把全部历史消息都塞进每次请求。短期记忆管理的核心是裁剪策略：只保留最近 N 轮消息、把早期消息做摘要压缩、或者只保留与当前任务相关的关键信息。你可以这样简单实现：设定一个最大消息数（比如 20 轮），超过之后就把最早的两轮消息替换为一条摘要。这种”滑动窗口+摘要”的模式在很多 Agent 产品里都能看到。

到后期你还会接触向量数据库、Embedding、RAG 这种“长期记忆”方案。但入门阶段我建议你先别急着上那一套——等你能把一个无记忆 Agent 跑通、能讲清楚状态是怎么流转的，再引入记忆机制会学得扎实得多。

4. 从“单次问答”到“循环行动”：手写一个最简单的 Agent

4.1 ReAct 模式：Agent 循环的“标准动作”

Agent 领域最重要的思想来自一篇叫 ReAct 的论文，它提出让模型交替进行“推理（Reason）”和“行动（Act）”。具体循环是：模型先观察当前状况，推理出下一步应该做什么，然后调用一个工具执行动作，拿到结果后再观察，再推理，再行动，直到得出最终答案。这个循环就像你早上起床：看时间（观察）→ 判断要迟到了（推理）→ 打车（行动）→ 确认到公司（观察下一步）→ 开始工作。

手写一个最小的 ReAct Agent，不需要任何框架，只需要：一个能输出 JSON 和调用工具的接口 + 一个函数注册表 + 一个循环控制逻辑。

import json from openai import OpenAI client = OpenAI() def get_weather(city): # 模拟天气查询工具 return f"{city}: 多云, 24度" tools = { "get_weather": get_weather } def run_agent(user_query, max_steps=5): messages = [ {"role": "system", "content": "你是一个有工具可用的小助手。当需要工具时，输出 JSON，格式为：{\"tool\": \"工具名\", \"params\": {...}}。否则直接输出最终回答。"}, {"role": "user", "content": user_query} ] for step in range(max_steps): response = client.chat.completions.create( model="gpt-4o-mini", messages=messages, temperature=0.0 ) content = response.choices[0].message.content # 尝试解析为 JSON try: action = json.loads(content) tool_name = action["tool"] params = action["params"] result = tools[tool_name](**params) # 把工具结果加回消息列表 messages.append({"role": "assistant", "content": content}) messages.append({"role": "user", "content": f"工具执行结果: {result}"}) except json.JSONDecodeError: # 不是 JSON，视为最终回答 return content return "到达最大步数，任务未完成" print(run_agent("上海天气怎么样？"))

这个代码第一个版本当然很粗糙——它甚至没有处理工具名不存在的情况，也没有把工具描述传给模型。但它的教学价值在于：你亲眼看到了 Agent 循环的骨架。所谓的 Agent 框架，就是在这个骨架上增加健壮性、可扩展性和可观测性。你先把这段代码跑通，再去看 LangChain 的AgentExecutor的源码，会惊喜地发现自己能看懂十有七八。

4.2 循环的边界和健壮性：新手最容易翻车的地方

手工写 Agent 循环时，最常遇到两个问题：一是模型根本不按约定输出 JSON，直接给自然语言；二是工具执行报错后循环直接崩溃。这两个问题能帮你理解为什么框架要存在——它们本质上都是工程可靠性问题。

对于第一个问题，建议加入自动重试和纠错机制：如果解析 JSON 失败，用提示词让模型重新输出。我当时用的方法是在异常分支里返回一条消息“注意：你的上一条输出无法解析为有效 JSON，请重新按要求的格式输出”，把这个反馈加进 messages 里再调用一次。这个技巧叫“反馈修正”，在 Agent 开发中非常常见。

第二个问题的通用做法是给工具调用加异常捕获，让错误消息作为工具结果返回给模型，而不是向上抛异常。这样模型能“看到”工具失败了，并根据错误信息调整策略——比如换个参数重试，或者告诉用户当前工具不可用。这类逻辑在框架里往往已经内置，但你自己写过一遍之后，才能理解框架默认行为背后的取舍。

4.3 从单 Agent 到多 Agent：你只需要加一层“调度”

多 Agent 系统听起来很高大上，比如 CrewAI 里的角色扮演、AutoGen 里的群聊模式。但拆开本质，多 Agent 不过是一个外层循环在调度多个内部循环罢了。每个 Agent 依然是“模型+工具+记忆”，区别只是外层增加了一份“谁来干活”的分配逻辑。

入门阶段我不建议立刻学多 Agent 框架。你先做到单 Agent 稳定运行、能按预期完成任务，就已经比很多人强了。多 Agent 的核心难点不在技术，而在任务分配和消息传递设计——这部分牵扯到实际的业务场景，没有一套通用的黄金法则。

5. 什么时候才需要框架：新手怎么选工具

5.1 先手写、再选型：框架不是越重越好

如果你已经能手写一个单 Agent 循环，那时再看框架你会有完全不同的视角。你可能会发现，自己并不需要 LangChain 那么重的抽象。我个人的选型标准是：如果业务只需要单一模型、少数工具、固定流程，直接用框架反而是负累。一个简单的 Agent 用几十行原生 API 调用就能搞定，完全没有必要引入一个依赖上百个子包的项目。

反过来，如果你的 Agent 需要多种模型切换、复杂工具链、人机共驾工作流、可视化调试界面，那找成熟框架能省大量时间。记住选框架的原则：框架解决的是规模化、可维护性和复杂编排的问题，不是帮你学习基本概念的问题。

5.2 主流框架的定位差异：简单任务是 Dify，敏捷开发是 LangChain，多角色协作看 CrewAI

给新手一个简单的横向对比，按场景而不是按热度选：

• Dify：适合产品化、可视化。如果你不想写太多代码，希望通过拖拽式工作流搭建 Agent 应用，Dify 上手最快。它自带知识库、日志、发布功能，适合快速做 MVP。
• LangChain：适合开发者，生态最全，资料最多，但也最抽象、版本迭代快。如果你打算深入做定制化开发，LangChain 是必经之路，但建议基础扎实后再进入。
• CrewAI：主打多角色协作，适合做“团队型”Agent。它的抽象很贴近直觉——不同角色领不同任务、协作产出结果。但多 Agent 调度本身有调试复杂度，新手容易一头雾水。
• AutoGen：微软出品，适合做多 Agent 对话和复杂推理任务。它的设计强调 Agent 之间的对话过程，适合研究型项目。

注意我的用词：“适合”不等于“必须”。如果一个框架解决不了的问题你能用原生代码几分钟搞定，千万别犹豫，原生代码就是当前场景下最好的“框架”。

5.3 转行者常见误区：学框架不等于学概念

我见过不少转行者简历上写“精通 LangChain”，但追问起来连 Chain 和 Agent 的区别都说不清楚。框架名称可以作为技能关键词，但面试官真正会考察的是你是否理解概念、是否能独立设计一个 Agent 流程。

“精通框架”和“会用框架”是两码事。前者意味着你能读懂源码、能在框架之上做二次开发、能给框架做扩展；后者只是照着示例改参数。新手前期应该追求的是“概念扎实+能独立实现”，而不是“API 背得多熟”。另外提醒一句：在简历里如果不是真读过大半源码，别写“精通”，改成“熟练使用”或“有项目实践”，面试反而更从容。

6. 常见问题与排查技巧实录

6.1 模型“不听话”：输出格式一直不稳定

这是新手做 Agent 时排在最前面的问题。排查步骤我按经验排列：第一步检查 temperature 是否过高，温度超过 0.5 就容易有随机性；第二步检查提示词是否用了足够的“强制句式”，比如“必须输出 JSON，不得输出其他内容”这种；第三步确认你是否启用了response_format强制 JSON 参数；第四步检查是否有系统级的 output 拦截把格式破坏了。

实测下来，把temperature=0和response_format组合使用，格式稳定性是最高的。如果仍然不稳定，再把你期望的输出格式写成一个具体示例放进提示词。注意是“具体示例”而不是“格式说明”，模型对示例的跟随能力比对规则描述强得多。

6.2 上下文爆炸：Agent 跑几轮就变笨

表现是 Agent 前几轮正常，越往后回答质量越差，或者干脆报超长错误。原因是 messages 数组里的历史消息和工具结果不断累积，把上下文窗口撑满了。排查方法：打印sum(len(m["content"]) for m in messages)，看体积增长曲线。

常用解决策略是设置 soft 上限，比如单轮请求总 token 超过 8000 时，触发历史压缩：把早期对话用一次单独的摘要请求压缩成一段概括文字，替换掉原始消息。这个技巧需要提前设计，不要等到报错了再救火。你也可以在每次工具返回时做后处理，把冗余字段删除、截断到固定长度，再丢回上下文。

6.3 工具调用失败：错误信息没有正确回传

有人说“我注册了工具，但 Agent 明显没调用”，或者”工具总是调用参数错误”。前者大概率是工具描述不清晰，模型不知道什么时候该用它；后者大概率是参数 schema 定义有问题。调试技巧是把模型的完整输出打印出来，看它到底生成了什么。我看过太多次小白只是盯着“最终结果不对”而忽略中间输出，完全排查不了问题。

打印 assistant 消息里tool_calls字段的内容，确认模型选择的工具名和参数，再检查这些参数是否跟 schema 定义一致。如果模型一直把参数名写错，试着给参数加别名或改写描述。

6.4 死循环：Agent 停不下来

表现是 Agent 反复调用同一个工具、结果也一样，却不见停止。本质上是因为你给模型的停止条件不够明确。检查提示词里有没有写“当你已经完成目标时，直接输出最终答案，不再调用工具”；同时检查外层循环有没有设置最大步数保险。我习惯给所有 Agent 加max_steps=5之类上限，这不是为了限制能力，而是防止生产环境里出现不可控的成本消耗。

结语：从“背框架”到“懂 Agent”需要刻意练习

我个人带过不少从前后端、测试、数据分析转 AI 方向的朋友，他们最大的共同问题是焦虑——“市面上框架这么多，不学是不是就落后了”。但我的答案一直没变：框架可以三个月一换，概念可以吃十年。你花两周时间手写一个最小 Agent、搞清楚 ReAct 循环、掌握函数调用和记忆裁剪，比花两周刷完 LangChain 教程要值得多。

先写代码，再看源码；先跑通循环，再上框架；先做单 Agent，再玩多 Agent。这套顺序可能听起来不够“时髦”，但它真的能让你在后续遇到框架迭代、模型更换、业务调整的时候，依然站得住脚。

最后分享一个具体的小习惯：把你完成过的 Agent demo 都保留下来，每做一个就记录当时的 Prompt 版本、参数选择、遇到坑。这些一手记录就是你最快的成长素材——等积累到十个 demo，你会发现“学什么框架”这个问题已经不再困扰你了，因为你只需要花一两天就能看懂任何框架的核心设计。这就是基础扎实带来的自信。