AI Agent 这个方向这两年确实火得不行，随便刷两下信息流就能看到“AI Agent 开发”、“Agent 框架对比”之类的标题。我后台也经常收到私信，问得最多的就是：我是转行过来的，该先学什么？要不要直接上 LangChain？甚至还有人一上来就问我 Rust 写 Agent 框架怎么选型——说实话，这种问题一听就知道还没入门，因为真正的第一步根本不是框架。

这篇文章就是写给准备入坑 AI Agent 的新手和转行者看的。核心就一句话：别一上来就啃框架，先把底层的原理和基本功打扎实，否则你会被框架牵着鼻子走，遇到问题连排查的方向都没有。我会把入门前应该先学的几个东西拆开讲清楚，再告诉你什么时候才适合碰框架，以及一个完全不用框架的最小 Agent 示例是怎么跑通的。

1. 先搞清楚“Agent”到底是什么，比选框架重要一百倍

很多人对 Agent 的理解停留在“能用大模型自动干活”这个层面，这不算错，但太模糊了。如果你连 Agent 的边界、组成部分、运行机制都没概念，直接去选框架就像是还没学会开车就研究改装套件，大概率是事倍功半。

1.1 你以为的Agent和实际上的Agent

先说一个我经常打的比方：单纯的 ChatGPT 聊天，本质上是一个“问答机器”。你问一句，它答一句，它不会主动去调用外部工具，也不会自己决定要分几步完成一个任务。而 Agent 更像一个“实习生”——你给它一个目标，它会自己拆解任务、决定先做什么后做什么、需要查资料的时候自己去查、遇到错误自己尝试修正，最后把结果交给你。

这里面的关键词是“自主决策”和“循环执行”。Agent 不是一个单次调用的接口，它是一个有状态、有步骤、能反馈闭环的推理过程。所以在学 Agent 之前，你得先搞清楚大模型 API 的调用方式、Token 的消耗机制、上下文窗口的限制，这些才是真正的地基。

我见过不少转行的人，一上来就背了一堆框架名词——LangChain 是什么、Dify 是什么、CrewAI 是什么——但问他“如果模型返回的 JSON 格式不对，你在代码里怎么处理”，他完全没思路。这说明他的学习顺序是错的，把框架当成了 Agent 本身。

1.2 Agent的核心组成：模型、记忆、工具、行动

不管哪个框架，也不管架构多花哨，一个能跑起来的 Agent 基本离不开四样东西：

• 模型（Model）：负责理解和生成内容的大脑，通常是一个大语言模型，比如 GPT、Claude、开源的 Qwen 或 Llama。
• 记忆（Memory）：短期记忆负责保存当前任务上下文，长期记忆负责存储历史经验或向量数据库里的知识。
• 工具（Tools）：让 Agent 能跟外部世界交互的接口，比如搜索引擎、代码执行器、数据库查询、HTTP 请求。
• 行动（Action）：Agent 根据模型输出决定调哪个工具、传什么参数、然后如何根据结果继续下一步。

所谓“Agent 框架”，本质上就是把上面这几块东西用一套代码组织起来，让你不用从零开始写这些基础逻辑。但问题是，如果你自己不清楚这些组件的职责和边界，框架对你来说就只是一个黑盒。一旦出了问题，你不知道是该查模型、查记忆、还是查工具调用，只能干瞪眼。

所以我给新手的第一条建议就是：先用最原始的方式把上面四个组件手动实现一遍，哪怕只是最简单的一问一答加工具调用，也比你直接跑框架里的 demo 收获大得多。具体怎么做，我在第 4 部分会给一个完整示例。

2. 新手学习路径：先打下这几个底子再谈框架

很多转行者不是不努力，而是把有限的精力用错了地方。学 Agent 的正确路线，我建议分三步走：先把模型 API 调明白、再把提示词能力练扎实、最后才是碰框架。

2.1 起点：把大模型API调明白

不管未来你会用 OpenAI 的接口、国内的模型平台、还是本地部署一个开源模型，第一件事都是学会怎么用代码调通模型的 API。这个环节不需要任何框架，只需要 Python 加一个 HTTP 库就够。

你需要掌握的东西包括：

1. 构造请求：理解messages数组的结构，知道什么是 system prompt、user prompt、assistant response。
2. 处理流式输出：学会用stream=true接收增量数据，这是做一个有“打字效果”的 Agent 界面的基础。
3. Token 计算：搞清楚你的 prompt 加上回复会消耗多少 token，成本估算和上下文窗口管理都依赖这个能力。
4. 参数调整：temperature、max_tokens、top_p这些参数分别影响什么，什么场景下该调高调低。

这些内容其实一天就能上手，但很多人跳过了这一步，直接在框架里传字符串，根本不理解后台发生了什么。等你需要排查“为什么输出被截断”或者“为什么上下文混乱”的时候，还得回头补这一课，绕了一大圈。

2.2 提示词工程不是选修课

提示词工程在 Agent 开发中的地位，比大多数人想象的要高。因为 Agent 的“思考过程”本质上是靠提示词引导出来的，比如让模型输出 JSON 格式的“下一步行动指令”、让模型在不确定时主动询问而不是瞎猜、让模型把复杂任务拆成多步执行。

我见过很多新手写了简单的 prompt 就跑 Agent，结果模型要么乱调工具、要么一步到位给出答案而不是分步执行。原因就是 prompt 里缺少角色设定、任务边界、输出格式、失败兜底这些要素。你可以不背所谓的“提示词模板”，但你一定要学怎么设计一个结构清晰、可校验的 prompt，这会在你排查 Agent 行为时省下无数时间。

这里有一个很实用的练习方式：不用框架，直接用 API 写一个提示词，让它输出一个包含thought和action字段的 JSON，然后你写代码去解析这个 JSON 并执行相应动作。这套流程跑通了，你对 Agent 的理解就超过一半的框架搬运工了。

2.3 编程基础到底需要学到什么程度

这个问题很现实。我的答案是：不需要你成为算法高手，但基本的 Python 编程能力必须过关。具体来说，你得熟练处理这几件事：

• 字典、列表、字符串的常用操作，因为你每天都要解析 JSON；
• 函数定义和模块化组织代码，因为你至少要能把 Agent 的逻辑拆成独立模块；
• 异常处理和重试机制，这一点在调用外部工具和模型接口时尤其重要；
• 基本的异步编程概念，因为大量 Agent 场景需要并发调用接口。

有人问学 Java 行不行、用 Node.js 行不行，我觉得都行，Python 只是生态最顺、教程最多，不是唯一选择。但如果你连“列表推导式”和“装饰器”都觉得吃力，那真的先别碰任何框架，否则框架代码里的报错足够让你怀疑人生。我还特别建议学一点基础的pytest测试用法，给 Agent 的核心逻辑写几条简单的单元测试，等你迭代代码的时候会痛哭流涕地感谢自己当初这个决定。

3. 框架的正确打开方式：不是不用，是时机没到

我在这行待了这些年，见过太多“框架中毒”的初学者：简历上写着熟练使用 LangChain，真到做项目时，连 Agent 报错是出在模型调用还是工具执行都分不清。这话可能得罪人，但确实是大实话。

3.1 为什么一上来就啃框架容易翻车

框架本身没有错，它是工程化沉淀的产物。问题是它把很多底层细节封装得过于干净，反而让你失去了“从原理层面理解问题”的机会。举几个我见过的高频翻车场景：

• 用框架搭了一个 Agent，跑起来能聊，但你想加一个特别简单的“先查数据库再回答”逻辑，翻了一晚上文档也不知道该往哪里塞；
• Agent 回答的内容明显是幻觉，你怀疑是提示词问题、工具调用问题还是记忆污染问题，但框架的抽象层让你看不见中间过程；
• 框架升级了一个大版本，API 变了，你的代码要重写，但你连原来调用了什么底层逻辑都不知道，只能上网搜“某框架 替代方案”。

这不代表框架不能用，而是说你在没有“裸调”经验的时候，框架对你来说是负担，不是加速器。等你已经能手动实现一个包含模型、记忆、工具调用的小型 Agent，再去用框架，你会发现它的每个抽象你都能“脑补”出背后的实现方式，遇到问题也知道该往哪个层面排查，这时候框架才真正变成你的工具。

3.2 主流Agent框架盘点与选型参考

虽说我不建议新手一开始就上框架，但迟早要接触，我还是把现阶段最常被提到的几类列一下，方便你以后做选型。

除了这些通用框架，市面上还有基于 Rust 的 Agent 运行时、针对垂直领域的“具身机器人训练部署框架”、以及像“硬参数共享框架”这种特定方向的前沿研究框架，这些都不是新手该操心的事。新手只要记住一个原则：选框架是你在已经懂 Agent 原理之后的项目决策，而不是你的入门起点。

我之前做一个内部工具的时候也考虑过引入某个重量级 Agent 框架，后来评估下来，团队只需要三个工具调用和两个角色的协作逻辑，最后用几十行原生 Python 就实现了，部署还更简单。不是说框架不好，而是“杀鸡焉用牛刀”，你自己能掌控的轮子，才是最好的轮子。

3.3 框架的生态位置：别神化，也别妖魔化

框架会帮你处理一些通用麻烦事，比如：维护多轮对话历史、集成各种向量数据库做记忆召回、统一工具调用的 schema、提供可视化编排界面等。如果你要做的是一个面向非技术人员也能配置 Agent 的产品，那么 Dify 或 Coze 这类平台就很有价值；如果你要在已有代码库里深度集成 Agent 逻辑，LangChain 或自研都是选项。

我的态度很明确：框架是第二梯队的工具，不是Agent 本身。它可以帮你放大效率，前提是你已经掌握了第一梯队的能力：模型调用、提示词设计、工具封装、状态管理。否则你只是在复制粘贴别人的思路，永远没有自己的方法论。

4. 用最原始的方式跑通第一个Agent，不用框架

纸上谈兵没意思，我直接带你写一个极简的 Agent，不用 LangChain，只用 Python 和一个大模型 API。这个练习的目的不是造一个产品，而是让你亲眼看到 Agent 循环的每一环是怎么咬合的。

4.1 一个极简Agent的完整实现

假设我们要做一个“能查天气、能算加减法”的小 Agent。它要做的事很简单：根据用户的自然语言输入，模型判断是调用天气工具还是计算器工具，然后把工具结果组装成最终答案。

我先贴一份伪代码级别的实现，语言是 Python，模型接口部分用openai库示意（换成任意国产模型 SDK 也类似）：

import json from openai import OpenAI client = OpenAI() def call_model(messages): resp = client.chat.completions.create( model="gpt-4o-mini", messages=messages, temperature=0, tools=[get_weather_tool_schema(), calculator_tool_schema()], ) return resp.choices[0].message def get_weather(city: str) -> str: # 这里假装调用真实天气 API return f"{city} 今天晴，温度 25°C" def calculator(expr: str) -> str: # 仅为演示，生产环境不要用 eval return str(eval(expr)) def run_agent(user_input: str): messages = [ {"role": "system", "content": "你是智能助手，必要时使用工具，不要编造结果。"}, {"role": "user", "content": user_input}, ] msg = call_model(messages) messages.append(msg) while msg.tool_calls: for tc in msg.tool_calls: fn_name = tc.function.name args = json.loads(tc.function.arguments) if fn_name == "get_weather": result = get_weather(args["city"]) elif fn_name == "calculator": result = calculator(args["expression"]) # 把工具结果回传给模型 messages.append({ "role": "tool", "tool_call_id": tc.id, "content": result, }) msg = call_model(messages) messages.append(msg) return msg.content print(run_agent("帮我算一下(12+13)*5，再告诉我上海天气怎么样"))

这段代码大概 60 行，但它已经包含了一个 Agent 循环的核心要素：模型决策、工具调用、结果回传、继续决策、最后输出自然语言答案。

4.2 逐步拆解Agent循环里的每个细节

上面这段代码跑通之后，你要盯住几个细节，这些正是框架替你隐藏起来的部分：

第一个细节是tools参数的结构。每个工具都要用一份 JSON Schema 描述它的名字、功能和参数，模型会根据这个描述来决定调用哪个工具。很多人用框架时直接写个函数装饰器就觉得完事了，其实背后就是这个东西。

第二个细节是tool_calls的循环判断。模型第一次返回可能带着tool_calls，也可能没有。有就执行工具然后把结果塞回消息列表；没有就直接输出最终回答。这个while循环就是 Agent 循环的本体，每转一圈，就是一次“推理+行动”。

第三个细节是消息列表的顺序。system、user、assistant、tool这些角色是按顺序拼起来的，模型在同一次对话里能看到完整的上下文。如果顺序乱掉，或者漏掉了某条工具结果，模型就可能在下一轮输出错误答案。这就是为什么说“用框架你不懂过程，出了问题就两眼一抹黑”。

第四个细节是工具结果必须可信。真实项目里，get_weather里应该是真实的 HTTP 请求，而不是我这里的假数据。反向讲，你也要在提示词里告诉模型“工具结果优先，不要自行发挥”，否则模型完全可能忽略工具结果，直接编一个天气出来。

我每次带新人跑这个练习，都会让他在三个地方打日志：模型原始返回、工具执行结果、最终回复内容。这样他能清楚看到每一轮 Agent 是怎么思考、怎么行动的，比任何架构图都直观。

4.3 Token消耗与成本估算

很多新手忽略一件事：Agent 每多一个工具调用，就意味着模型要多生成一轮输出；每多一个工具结果，下一轮的输入 token 就要加上这一大段内容。所以 Agent 的 token 消耗不是“一次问答”的量，而是多轮累积的量。

举个例子，用户问一句“帮我分析这份报告并生成摘要”，如果 Agent 先读取文件、再搜索资料、再写摘要，可能就是三次或四次模型调用。假设每次输入 3000 token、输出 500 token，总共就接近 14000 token。如果用的是按量计费的商业模型，成本已经不是几分钱的问题了，尤其是你要批量跑的时候。

理解了这一点，你再去谈“框架哪家便宜”“如何做缓存”“如何精简上下文窗口”，才是有意义的。一上来就啃框架的初学者，连“自己的 Agent 跑一趟到底烧了多少 token”都说不清楚，后面做成本优化就更无从谈起。

4.4 从简陋Agent到工程化之间的空档期做什么

当你用裸代码跑通了上面的小 Agent，下一步不是立刻找框架，而是做这些事：

1. 把工具的调用改成真实服务，比如接入搜索 API 或数据库；
2. 加一个记忆模块，把多轮对话的关键信息和历史工具结果存起来；
3. 加一个状态机或者固定的工作流，让 Agent 不是每次自由发挥，而是按预设路径走；
4. 给 Agent 的输入输出做校验和错误处理，避免用户一句话就把整个流程带偏。

你会发现，当你把这些需求列出来的时候，其实你已经在做框架的活了。这时候再去看 LangChain 或 LangGraph 的源码，你会豁然开朗：原来那个模块是干这个的、那个抽象是为了解决什么问题的。带着问题去学框架，效率至少翻三倍。

5. 典型翻车现场与排查思路

这节你看完一定能少踩几个坑。我每年都要经手好几个 Agent 项目，自己也交过不少学费，把最常见的问题和排查思路整理成一张速查表。

5.1 常见问题速查表

这里面最隐蔽、最常见的一个坑就是“模型忽略工具结果”。模型毕竟不是代码，它有可能看了工具输出但决定“不采纳”，尤其当你 prompt 写得很随意的时候。解决办法很简单，在 system prompt 里把话说死：比如“你是工具执行助理，当工具返回结果时，你必须使用该结果回答用户，禁止编造未出现在工具结果中的信息”。

5.2 我踩过的几个坑和反思

第一个坑是过度依赖“万能提示词”。我有一个项目，一开始觉得把这套 Agent 跑通就完事了，结果模型在复杂任务里经常不按流程走，一会儿输出 JSON 一会儿输出纯文本。后来我才意识到，可靠的结构化输出不是靠“喊口号”实现的，而是要配合工具调用规范、解析与校验机制一起做。你既要在 prompt 里定义格式，也要在代码里做好容错和二次格式化。

第二个坑是过早引入现成框架。我曾经想让一个刚转行的同事直接用框架搭一个检索问答 Agent，结果他花了两周还卡在配置依赖和版本冲突上。后来我带着他把框架换成几十行裸代码，用 FastAPI 包成一个小服务，一下午就上线了。这不是说框架差，而是“人+时机”不匹配。你还没到需要框架复杂抽象的那一步时，越简单的东西越可控。

第三个坑是忽略日志记录。Agent 领域有个特点：模型是不可完全确定的，哪怕同样的输入，输出的中间轨迹都可能不一样。如果你没有详细记录每次调用的请求参数、工具结果和模型输出，出了问题根本无从复现。现在我写的每个 Agent 都有一个完整日志结构，至少包含时间戳、输入消息、工具调用、输出回复、token 消耗这些字段。建议你在入门阶段就养成这个习惯，后面会很省钱。

最后再分享一个小技巧：如果你在写自己的 Agent 循环，可以把“思考过程”也打进日志里。很多国产模型或者 GPT 系列的reasoning字段能透露一部分推理过程，你会看到 Agent 是怎么选择下一步行动的，这比任何架构图都有启发。

这个方向的知识还在快速迭代，但底层的学习方法论反而很稳定：先裸写、再框架、后自研。把这一步踩扎实了，不管未来是哪个框架火，你都能稳稳站住。别急着追逐你还没能力驾驭的工具，慢下来，把基础补上，这反而是通往这个领域最近的路。