AI Agent 这个词在过去一年里被反复提起，打开任何一个技术社区，满屏都是 LangChain、LangGraph、MCP、CrewAI、Dify 这些名词。很多新手和想转行做 AI 应用开发的朋友，第一反应就是去搜"LangChain 入门教程"，然后花两周时间啃文档，结果连一个能跑起来的最小 Demo 都没搭出来。我自己带过几个转行的朋友，也见过太多人在第一步就选错了方向。这篇内容就是想把"新手到底该先学什么"这件事讲透，从底层能力到工具选型，从最小可运行单元到真正能落地的项目，给出一条我自己验证过的路径。不管你是刚学完 Python 基础，还是从 Java、前端转过来想做 AI Agent 开发，都能从里面找到可以直接抄作业的步骤和判断依据。
1. 为什么一上来啃框架是新手最容易踩的坑
1.1 框架封装掉的恰恰是你最该理解的东西
LangChain 这类框架最大的价值是"抽象"——它把提示词拼接、模型调用、工具注册、记忆管理、输出解析这些环节封装成链式调用。问题在于，抽象层是给已经理解底层的人提效用的，不是给新手学原理用的。你调用一个AgentExecutor，它内部帮你做了循环推理、工具选择、结果回填，你看到的只是几行配置，但真正出问题时——比如模型不调用工具、工具参数传错、循环停不下来——你完全不知道从哪下手。
我见过一个很典型的例子：有人用 LangChain 写了个查询天气的 Agent，模型死活不调用工具，一直在那自言自语。他翻了两天文档也没解决，最后发现是工具描述写得太模糊，模型判断不出该不该用。这个问题如果他自己手写过一遍"把工具描述塞进提示词、解析模型输出、判断是否调用"的完整流程，十分钟就能定位。框架把这段逻辑藏起来了，也就把调试的抓手藏起来了。
1.2 框架迭代速度远超你的学习速度
LangChain 从 0.0.x 到 0.1、0.2、0.3，API 改了一轮又一轮，AgentExecutor、initialize_agent、LCEL 表达式、LangGraph 状态机，每一代写法都不一样。你跟着某个 2023 年的教程学，跑起来一堆 deprecation warning，改到最后发现整个思路都过时了。这不是框架的错，是这个领域本身还在快速演化。新手把宝贵的时间投在一个半年就变样的 API 上，性价比极低。
反过来，如果你先掌握了"模型调用 + 提示词工程 + 工具调用协议 + 循环控制"这几个稳定不变的核心概念，那么无论上层框架怎么换，你都能在半天内迁移过去。LangChain 换了，你用原生 SDK 照样写；明天出了个新框架，你看一眼文档就知道它在封装什么。
1.3 先建立"没有框架也能跑"的底气
我的建议很直接：第一个 Agent 一定要用原生 SDK 手写，不引入任何 Agent 框架。用 OpenAI 的 Python SDK 也好，用国内模型的 API 也好，核心就是三件事——发请求、解析返回、根据返回决定下一步。等你手写完一个能调用两三个工具的 Agent，再去看 LangChain 的源码，你会发现它做的事情你全都理解，这时候用框架才是真的提效，而不是被框架牵着走。
提示：判断自己是否"准备好用框架"的标准很简单——你能不能在不看文档的情况下，说清楚一个 Agent 从接收用户输入到返回结果的完整数据流。说不清楚，就再手写一遍。
2. 动手之前必须打牢的四块地基
2.1 Python 不是"会语法"就够，重点是这几样
AI Agent 开发目前主流还是 Python 生态，Java 有 Spring AI，但资料和社区活跃度差一截。Python 基础不用学到能写装饰器元类那么深，但有几样必须熟练：
- 函数与参数处理：Agent 的工具本质就是函数，你要能熟练写带默认参数、关键字参数、类型注解的函数，因为工具的参数 schema 就是从类型注解生成的。
- 字典与 JSON 互转：模型返回的 tool call 是 JSON 结构，你要能自如地在 dict 和 JSON 字符串之间转换、取值、拼装。
- 异常处理：网络请求会超时，模型会返回格式错误的内容，工具会抛异常，
try/except写不熟，Agent 跑两次就崩。 - 虚拟环境与包管理：
venv或conda建环境，pip install装包，这是最基本的工程习惯，别把包装到系统 Python 里。
如果你连python安装都还没搞定，先去官网下载安装包，装完在命令行敲python --version能看到版本号，再往下走。这一步卡住的人比想象中多，尤其是 Windows 用户遇到路径问题、pip找不到命令，这些都得先解决。
2.2 HTTP 与 API 调用：Agent 的命脉
Agent 的一切都建立在 API 调用之上。你得理解 HTTP 请求长什么样，什么是请求头、请求体，什么是状态码，什么是流式返回。具体到实操：
import requests resp = requests.post( "https://api.example.com/v1/chat/completions", headers={"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}, json={"model": "xxx", "messages": [{"role": "user", "content": "你好"}]}, timeout=30 ) print(resp.status_code) print(resp.json())这段代码你要能看懂每一行在干什么，能自己改参数、加字段、处理错误。很多人跳过这一步直接上框架，结果连"为什么我的请求 401"都排查不了。401 是鉴权失败，通常是 key 错了或没带；429 是限流，要加退避重试；500 是服务端问题，重试或换模型。这些判断能力，是后面所有调试的基础。
2.3 提示词工程：不是"会写 prompt"，是理解模型怎么想
提示词工程被说烂了，但新手对它的理解往往停留在"把话说清楚"。真正的核心是理解模型的推理机制：它是根据上下文预测下一个 token，所以你的提示词结构、示例数量、指令位置都会显著影响输出。
对 Agent 来说，提示词工程最关键的两个场景是：
- 工具描述：模型靠工具的名字和描述来判断该不该调用、怎么填参数。描述要写清楚"这个工具做什么、什么时候用、参数是什么格式"，含糊的描述直接导致模型不调用或乱调用。
- 输出格式约束：你要模型返回结构化数据（比如 JSON），就得在提示词里明确格式，最好给一个示例。光说"返回 JSON"不够，模型可能给你包一层 markdown 代码块。
2.4 工具调用协议：Agent 和普通聊天机器人的分水岭
普通聊天机器人只会说话，Agent 能"做事"，靠的就是工具调用。主流模型都支持 function calling / tool use，机制大同小异：你在请求里声明有哪些工具（名字、描述、参数 schema），模型判断需要时返回一个结构化的调用请求，你执行工具，把结果回传，模型再继续。
这个循环就是 Agent 的心脏。手写一遍这个循环，你就理解了所有 Agent 框架的本质。下面是一个极简的伪代码示意：
messages = [{"role": "user", "content": user_input}] while True: resp = call_model(messages, tools=tool_schemas) if resp.has_tool_call: result = execute_tool(resp.tool_name, resp.tool_args) messages.append(resp.message) messages.append({"role": "tool", "content": result}) else: return resp.content就这么简单。所有复杂的 Agent 框架，无非是在这个循环上加记忆、加多 Agent 协作、加状态持久化、加错误恢复。你把这段吃透，后面全是增量。
3. 第一个 Agent 应该长什么样：从最小可运行单元开始
3.1 选一个"无聊但完整"的场景
新手第一个 Agent 千万别选花哨的场景，比如"自动操作浏览器发小红书"或者"全自动写代码"。这类场景涉及登录、反爬、页面结构变化，变量太多，你会把时间全耗在环境适配上，学不到 Agent 本身的东西。
我推荐从"计算器 + 天气查询 + 时间查询"这种无聊但完整的场景开始。它满足几个条件：工具有明确输入输出、不需要外部鉴权、结果可验证、失败原因单一。你先把这三个工具跑通，Agent 的完整链路就通了。
3.2 工具函数的写法有讲究
工具函数不是随便写个函数就行，它的签名和文档字符串直接影响模型能不能正确调用。看这个例子：
def get_weather(city: str, unit: str = "celsius") -> str: """查询指定城市的当前天气。 Args: city: 城市名称，例如 "北京"、"上海"。 unit: 温度单位，可选 "celsius" 或 "fahrenheit"，默认摄氏度。 """ # 实际实现省略，返回天气描述字符串 return f"{city} 当前晴，25 度"要点在于：类型注解要准确（模型据此生成参数 schema），文档字符串要写清楚每个参数的含义和取值范围。很多人工具调不通，问题就出在文档字符串写得太随意，模型不知道unit该填什么。
3.3 把工具 schema 喂给模型
不同模型的 schema 格式略有差异，但结构一致：工具名、描述、参数对象（属性 + 必填项）。以 OpenAI 风格为例：
tools = [{ "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的当前天气", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名称"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} }, "required": ["city"] } } }]注意required字段——只有city是必填，unit有默认值。这个细节决定了模型在用户没说单位时会不会硬编一个值。
3.4 跑通第一个循环，观察模型的行为
把上面几块拼起来，你就能跑一个完整的 Agent 循环。第一次跑的时候，重点观察几件事：模型在什么情况下决定调用工具、参数填得对不对、工具返回后它怎么组织最终回答。这些观察比看十篇教程都有用。
我自己的经验是，第一次跑大概率会遇到模型不调用工具、直接编答案的情况。这时候别急着改代码，先看提示词——通常是你没在 system prompt 里明确告诉它"涉及实时信息必须调用工具，不要凭记忆回答"。加一句约束，问题就解决了。这个排查过程本身就是最好的学习。
4. 框架什么时候该上场，怎么选
4.1 手写循环撑不住的三个信号
手写 Agent 循环能撑到什么时候？我的判断是三个信号出现时，就该考虑框架了：
- 工具数量超过十个：手动维护 schema、手动分发调用开始变得繁琐，容易出错。
- 需要多轮记忆和状态持久化：用户会话要跨请求保持上下文，手写就得自己设计存储结构。
- 需要多 Agent 协作或复杂流程编排：一个 Agent 干不完的活，要拆成多个角色协作，手写循环会变成一团乱麻。
在这三个信号出现之前，手写完全够用，而且更可控。
4.2 LangChain、LangGraph、Dify、CrewAI 各自适合谁
这几个是热词里出现频率最高的，我按自己的使用体验给个定位：
| 框架 | 核心定位 | 适合场景 | 上手门槛 |
|---|---|---|---|
| LangChain | 通用组件库 | 快速拼装单 Agent、工具链 | 中，API 变动频繁 |
| LangGraph | 状态机式编排 | 复杂多步流程、多 Agent | 较高，需理解图结构 |
| Dify | 低代码平台 | 快速搭原型、非程序员 | 低，可视化配置 |
| CrewAI | 多角色协作 | 角色分工明确的团队式任务 | 中，概念直观 |
选型逻辑很简单：如果你只是想快速验证一个想法，Dify 拖拽最快；如果你要写进生产代码、需要精细控制，LangGraph 更合适；如果你要多个 Agent 扮演不同角色协作，CrewAI 的概念模型最贴合。LangChain 现在更像一个底层组件库，LangGraph 才是它主推的编排方案。
4.3 MCP 是什么，为什么值得单独关注
MCP（Model Context Protocol）是热词里绕不开的一个。简单说，它是一套标准化协议，让模型能以统一的方式连接外部工具和数据源。以前每个工具都要单独写适配代码，MCP 想解决的就是"一次接入、到处可用"的问题。
对新手来说，MCP 的意义在于：你不需要为每个模型、每个框架重复写工具适配。一个符合 MCP 的工具服务，理论上可以被任何支持 MCP 的客户端调用。现在很多工具（比如浏览器自动化、数据库查询、文件操作）都有现成的 MCP 实现，你直接接进来就能用。
但要注意，MCP 目前生态还在早期，各家支持程度不一，接入时经常遇到授权、协议版本、流式输出这些问题。新手可以先理解它的设计理念，实际项目里再按需接入，不用一上来就深挖。
4.4 别被"框架鄙视链"带偏
社区里总有人争论"用 LangChain 的是不是菜鸟""手写才是真本事"。这种争论毫无意义。框架是工具，判断标准只有一个：它能不能帮你更快、更稳地解决问题。你手写过、理解原理，用框架就是提效；你没手写过、只会调 API，用框架就是被绑架。区别不在用不用框架，在你懂不懂底层。
5. 转行者的差异化路径：别和科班拼同一套
5.1 Java 转过来的人，Spring AI 是天然入口
如果你本来就是 Java 后端，没必要硬转 Python。Spring AI 把模型调用、工具注册、向量存储这些能力做成了 Spring 风格的 Bean 和注解，你现有的 Spring Boot 工程经验直接复用。热词里spring ai和java rest接口快速转为mcp接口这类需求，正是 Java 开发者的主场。
路径建议：先用 Spring AI 写一个能调用工具的 Agent，理解工具调用循环，再回头看 Python 生态的框架，你会发现概念完全相通，只是写法不同。
5.2 前端转过来的人，从"能看见效果"的场景切入
前端开发者对交互和可视化敏感，适合从有明确 UI 反馈的场景入手，比如做一个能调用工具、把结果渲染成卡片的聊天界面。Playwright 这类浏览器自动化工具配合 MCP，能做出很直观的 Agent 应用。你的优势在于能把 Agent 的能力包装成用户愿意用的产品，这是纯后端背景的人容易忽略的。
5.3 完全零基础的人，先别碰 Agent
如果你连编程都没学过，直接冲 AI Agent 会非常痛苦。Agent 开发涉及 API 调用、异步、错误处理、数据结构，这些都需要编程基础。建议先用两三个月把 Python 基础打牢，能独立写出调用 API、处理 JSON、读写文件的小脚本，再进入 Agent 领域。热词里python入门、python教程、python安装教程这些搜索量高是有原因的——地基不牢，上面全是空中楼阁。
6. 学习路径上的几个关键判断点
6.1 什么时候该深入源码
不是越早看源码越好。我的建议是：手写完一个完整 Agent、用过至少一个框架之后，再去看框架源码。这时候你带着"它是怎么实现我手写过的那个循环"的问题去看，效率最高。没写过就去看源码，你会迷失在抽象层里。
6.2 项目驱动还是知识驱动
纯看文档学不会 Agent，纯做项目又容易知其然不知其所以然。我的做法是"项目驱动 + 定点补知识"：先定一个小项目（比如一个能查资料并总结的 Agent），做的过程中遇到不懂的概念（比如 embedding、向量检索）再去定点学。这样学到的知识都是带着问题场景的，记得牢、用得上。
6.3 怎么判断自己真的入门了
一个很实在的标准：给你一个没做过的需求，你能在不看教程的情况下，判断出该用几个工具、工具怎么设计、需不需要记忆、要不要上框架，并且能把它跑通。达到这个状态，你就不是"学过 Agent"，而是"会做 Agent"了。
6.4 关于 token 和成本，早点建立意识
热词里ai agent token是什么意思说明很多人对 token 没概念。简单说，token 是模型处理文本的基本单位，你发的每条消息、模型回的每条内容、工具调用的参数和结果，都消耗 token，都花钱。Agent 因为要循环调用，token 消耗比普通聊天高得多。早点学会看 token 用量、控制上下文长度、精简工具描述，能帮你省下不少成本，也能避免上下文超限导致 Agent 崩溃。
7. 我踩过的几个坑和给你的实操建议
第一个坑是过早引入框架。我最早学 Agent 时，直接上 LangChain，跟着教程跑通了一个 Demo，以为自己会了。结果换个需求，模型不按预期调用工具，我完全不知道从哪查。后来老老实实手写了一遍循环，才真正理解每个环节。这个弯路我建议你别走。
第二个坑是工具描述写得太随意。有次我写了个查询数据库的工具，描述就一句"查询数据"，模型要么不调用，要么传错参数。改成详细描述表结构、字段含义、查询示例之后，调用准确率立刻上来了。工具描述是提示词工程里最容易被忽视、又最影响效果的部分。
第三个坑是忽略错误处理。Agent 循环里任何一步都可能失败——网络超时、模型返回格式错误、工具抛异常。我早期没做重试和兜底，Agent 跑几次就挂。后来加了超时重试、格式校验、异常捕获，稳定性才上来。这些工程细节，框架会帮你做一部分，但理解原理才能配好参数。
第四个坑是上下文无限增长。多轮对话加工具调用，消息列表会越来越长，最后超出模型上下文限制。解决办法是定期裁剪历史、只保留关键信息，或者用摘要压缩。这个机制框架里有现成的，但你得知道它为什么存在、什么时候该开。
给你的实操建议就三条：第一，第一个 Agent 手写，不碰框架；第二，工具描述当文档写，越清楚越好；第三，从无聊但完整的场景开始，别一上来就挑战高难度。把这三条做到，你入门的速度会比啃框架快得多。
至于后面怎么深入，等你手写循环跑顺了、用过一两个框架了，自然会知道下一步该学什么。这个领域变化快，但底层的东西变得慢，把底层吃透，上面怎么变你都不慌。
