AI Agent入门：先手写核心循环，再学LangChain与Spring AI

1. 为什么我不建议新手一上来就啃框架

我带过不少想转行做 AI Agent 的朋友，也帮几个应届生做过入门规划。几乎每个人问我的第一个问题都是：“我该先学 LangChain 还是 Spring AI？”或者“Dify 和 CrewAI 哪个更值得投入时间？”说实话，每次听到这个问题，我都觉得他们把顺序搞反了。这就好比一个人连锅铲都没握过，就在纠结买德国产的不粘锅还是日本产的铁锅——工具确实重要，但你现在最该搞清楚的，是“炒菜”这件事本身是怎么回事。

AI Agent 这个词现在被炒得很热，但剥开那些花哨的概念，它的本质其实很朴素：让大模型不只是聊天，而是能自己决定调用什么工具、按什么顺序执行、拿到结果后怎么继续下一步。你听到的 ReAct、Plan-and-Execute、Multi-Agent 协作，全都是在这个朴素本质上长出来的枝干。如果你连“一次工具调用是怎么发生的”都没亲手跑通过，直接跳进 LangChain 的 Chain 和 AgentExecutor 里，大概率会被各种抽象层绕晕，最后变成“照着文档能跑，换个场景就懵”的状态。

我写这篇东西，就是想给正在纠结入门路径的人一个更务实的参考。不管你是完全没写过代码的纯小白，还是从 Java、前端、测试转过来的开发者，下面这套思路都适用。核心就一句话：先用最原始的方式把 Agent 的骨架搭一遍，再去用框架提效。这样你学 LangChain 也好，Spring AI 也好，MCP 也好，都是在给一个你已经理解的东西加装备，而不是在猜一个黑盒子里发生了什么。

2. 入门之前必须想清楚的三个问题

2.1 Agent 和普通脚本到底差在哪

很多人对 Agent 的理解停留在“会自己干活的程序”。这个说法不算错，但太模糊了。你写个 Python 脚本定时爬数据、发邮件，它也在“自己干活”，但那叫自动化脚本，不叫 Agent。真正的分界线在于：Agent 的下一步动作不是程序员写死的，而是模型根据当前上下文自己判断出来的。

举个具体例子。你要做一个“帮我查天气并决定要不要带伞”的功能。脚本的写法是：调天气 API，判断降水概率是否大于 50%，大于就输出“带伞”，否则输出“不用带”。逻辑全在你手里。而 Agent 的写法是：你把“查天气”这个工具的描述给模型，把用户的问题给模型，模型自己决定“我需要调用查天气工具”，拿到结果后自己判断“降水概率 70%，应该建议带伞”。你只提供了工具和规则，决策权交给了模型。

这个区别决定了两件事。第一，Agent 的行为有不确定性，同样的输入可能走出不同的路径，所以你得学会看日志、做评估。第二，Agent 的能力上限取决于你给它的工具质量和描述清晰度，工具描述写得含糊，模型就会乱调或者不调。理解这两点，你后面学任何框架都不会跑偏。

2.2 为什么 Python 是绕不开的第一站

热搜里“python安装”“python入门”“python教程”这些词一直居高不下，说明大量新手卡在最基础的环境问题上。我的建议很直接：做 AI Agent 入门，先用 Python，别纠结。原因不是 Python 有多高级，而是生态最全。LangChain、CrewAI、AutoGen 这些主流框架都是 Python 优先，各种大模型 SDK 的 Python 版本更新最快，社区里你能搜到的示例代码绝大多数也是 Python。

那 Java 转行者怎么办？我的看法是分两步走。第一步，花两三天用 Python 把 Agent 的核心逻辑跑通，不求写得多优雅，能跑就行。第二步，等你理解了原理，再回到 Spring AI 用 Java 重写一遍。Spring AI 这两年在国内热度很高，尤其是和阿里百炼、通义千问结合的场景，企业级项目里用得不少。但如果你连 Agent 的基本循环都没概念，直接看 Spring AI 的 Advisor、ChatClient 这些抽象，学习曲线会非常陡。

至于 Rust，热搜里出现了“基于 rust 语言 ai agent”，说明也有人关注这个方向。Rust 写 Agent 的优势在于性能和部署体积，适合对延迟和资源敏感的场景。但作为入门第一语言，我不推荐，因为你会同时面对“理解 Agent”和“理解 Rust 所有权”两座大山，容易劝退。

2.3 框架到底解决了什么问题

先把结论摆出来：框架解决的是工程化和复用问题，不是理解问题。LangChain 帮你把提示词模板、模型调用、工具注册、记忆管理、输出解析这些重复劳动封装成组件，让你搭复杂流程时不用从零写。Dify 更进一步，把编排做成了可视化工作流，适合快速验证和给非技术同学演示。CrewAI 专注多角色协作，AutoGen 专注多 Agent 对话。

但你要清楚，这些框架的抽象层是有成本的。LangChain 的版本迭代快，API 经常变，网上半年前的教程可能已经跑不通了。Dify 的工作流虽然直观，但你想把它转成 Spring AI 的 Java 代码，中间有大量逻辑需要手动翻译。所以我的建议是：入门阶段用原生代码，把 Agent 的循环、工具调用、上下文管理各写一遍，哪怕写得丑。等你被重复代码折磨得受不了了，再去用框架，那时候你才知道框架每个设计是为了解决什么痛点。

3. 不碰框架的第一周：用原生 Python 跑通 Agent 核心循环

3.1 环境准备：把 Python 装明白

先说环境。Windows 用户去 Python 官网下载安装包，安装时务必勾选“Add Python to PATH”，这一步漏了后面命令行找不到 python 命令，新手最容易在这里卡住。装完之后打开终端，输入python --version，能显示版本号就成功了。如果你要用 numpy、cv2 这些库，用 pip 安装：pip install numpy opencv-python。国内网络下载慢的话，可以临时指定镜像源，这个网上教程很多，我就不展开了。

我建议用虚拟环境隔离项目依赖，命令是python -m venv agent-env，然后激活它。Windows 下是agent-env\Scripts\activate，Mac 和 Linux 下是source agent-env/bin/activate。这样做的好处是不同项目的依赖不会打架，你后面试 LangChain 不同版本的时候会感谢自己。

编辑器方面，VS Code 加 Python 插件足够用了。如果你想要更省心的体验，PyCharm 社区版也行。不用在这上面花太多时间纠结，工具顺手就行。

3.2 第一次工具调用：手写一个最朴素的 Agent

现在进入正题。我们要实现一个最小可用的 Agent：用户提问，模型判断是否需要调用工具，如果需要就调用，拿到结果后再生成最终回答。整个过程不用任何框架，只用大模型的基础 API。

先定义工具。假设我们有一个查天气的函数：

def get_weather(city): # 真实场景这里调天气 API，入门阶段先用假数据 fake_data = {"北京": "晴，25度", "上海": "多云，28度", "广州": "小雨，30度"} return fake_data.get(city, "查不到这个城市")

然后你要把这个工具的描述告诉模型。描述要写清楚三件事：工具叫什么、干什么用、需要什么参数。比如：“get_weather：查询指定城市的当前天气。参数 city，字符串类型，表示城市名称。”描述写得越清楚，模型调用越准确，这是很多人忽略的细节。

接下来是核心循环。伪代码逻辑是这样的：

1. 把用户问题和工具描述一起发给模型
2. 模型返回一个结构化的结果，要么是“我要调用 get_weather，参数是北京”，要么是“我直接回答”
3. 如果是调用工具，你执行函数拿到结果，把结果追加到对话历史里，再发给模型
4. 模型基于工具结果生成最终回答

这个循环就是 Agent 的心脏。你亲手写一遍，就会明白所谓 Agent 不过是“模型输出 + 程序执行 + 结果回灌”的反复迭代。LangChain 的 AgentExecutor 干的就是这件事，只是它帮你处理了各种边界情况和格式解析。

3.3 让模型输出结构化结果的两个办法

上面第 2 步有个关键问题：模型输出的是自然语言，你怎么知道它是要调工具还是要直接回答？两个办法。第一个是提示词约束，明确要求模型“如果需要调用工具，只输出 JSON 格式，包含 tool 和 args 两个字段”。第二个是用模型厂商提供的 function calling 能力，直接返回结构化的工具调用请求。

入门阶段我建议先用提示词约束，因为这样你能亲眼看到模型是怎么“决定”的，也能体会到提示词写得好不好对结果影响有多大。等你熟练了，再切换到 function calling，省去解析自然语言的麻烦。这两种方式在 LangChain 和 Spring AI 里都有对应封装，但你手写过之后，看文档就能秒懂它们在做什么。

注意：解析模型返回的 JSON 时一定要做异常处理。模型偶尔会输出多余的文字或者格式不对，直接 json.loads 会崩。用 try-except 包起来，解析失败就让它重新生成或者走兜底逻辑。

4. 理解 Agent 的骨架：循环、工具与上下文

4.1 ReAct 模式其实没那么神秘

你肯定听过 ReAct 这个词，论文里叫 Reasoning and Acting。拆开看就是“想一步、做一步、看结果、再想”。比如用户问“北京和上海哪个更适合今天出门”，Agent 的思考链可能是：我需要先查北京天气，再查上海天气，然后对比。查完北京发现晴天，查完上海发现多云，最后综合判断。

这个模式之所以有效，是因为它把复杂任务拆成了模型能处理的多个小步骤，每一步都有明确的观察结果作为下一步的依据。你在原生代码里实现 ReAct，无非就是在循环里维护一个“思考-行动-观察”的记录列表，每次把完整记录发给模型。LangChain 里的 Agent 类型虽然名字五花八门，底层都是这个套路。

我建议你在手写循环的时候，把每一步的中间结果打印出来。你会直观看到模型是怎么一步步逼近答案的，也会发现它在哪一步容易跑偏。这种观察经验，比看十篇原理文章都管用。

4.2 工具设计的三个原则

工具是 Agent 的手脚，设计得好不好直接决定 Agent 能不能用。我总结了三条原则。

第一，一个工具只做一件事。不要写一个“万能工具”既能查天气又能订机票，模型会搞混。拆成 get_weather 和 book_flight 两个独立工具，描述各自清晰，调用准确率会高很多。

第二，参数尽量简单。能用字符串就别用嵌套对象，能用必填就别搞一堆可选参数。模型对复杂参数结构的理解能力有限，参数越简单，出错概率越低。

第三，返回值要精简。工具返回一大堆无关信息，会占用上下文窗口，还可能干扰模型判断。只返回模型决策需要的关键字段。比如查天气返回“晴，25度”就够了，不用把湿度、风速、气压全塞进去。

这三条原则在你后面用 LangChain 或 Spring AI 注册工具时同样适用。框架只是帮你把工具注册流程标准化了，工具本身设计得好不好，还是取决于你的判断。

4.3 上下文管理：别让对话历史撑爆窗口

Agent 跑多轮之后，对话历史会越来越长，最终超过模型的上下文窗口限制。这时候你需要做上下文管理。最简单的办法是只保留最近 N 轮对话，更早的丢掉。但这样会丢失重要信息，比如用户最开始说的偏好。

好一点的做法是做摘要。当历史超过一定长度，让模型把前面的对话压缩成一段摘要，保留关键信息，丢弃冗余细节。再复杂一点的是做向量检索，把历史存进向量库，每次只召回和当前问题相关的片段。这个思路就是后来 RAG 的基础。

入门阶段你先用“保留最近 N 轮”就够了，重点是理解上下文是有限资源，需要有意识地管理。等你用上 LangChain 的 Memory 组件或者 Spring AI 的 ChatMemory，就会明白它们是在帮你自动化这些策略。

5. 框架该怎么选：LangChain、Spring AI、Dify 的适用场景

5.1 LangChain：生态最全但迭代快

LangChain 是目前 Python 生态里组件最全的 Agent 框架，模型接入、工具、记忆、检索、评估都有覆盖。它的优势是社区大，你遇到问题基本能搜到答案。劣势是版本迭代太快，API 变动频繁，而且抽象层多，出问题的时候排查链路长。

我的建议是：等你手写过 Agent 循环之后，用 LangChain 重写一遍同样的功能。这时候你会对它的每个组件有感觉，知道 Chain 是在封装什么、AgentExecutor 帮你处理了哪些边界。LangChain 中文教程网上很多，但注意看发布时间，太老的直接跳过。

5.2 Spring AI：Java 团队的企业级选择

Spring AI 这两年在国内企业里落地不少，尤其是和阿里百炼、通义千问结合的场景。它的设计风格延续了 Spring 家族的一贯做法，用注解和配置来声明模型调用、工具注册、对话记忆。对于已经熟悉 Spring 生态的 Java 开发者来说，上手成本比 LangChain 低。

热搜里有人问“spring ai alibaba 停更了吗”，这个我没法给确定答案，建议直接看官方仓库的提交记录。但可以确定的是，Spring AI 本身在持续更新，2.0 版本对工具调用和 MCP 的支持都在完善。如果你是企业开发者，想把手里的 Java 系统接入 Agent 能力，Spring AI 是值得投入的方向。但前提还是那句话，先理解 Agent 原理，再学框架。

5.3 Dify 和 CrewAI：可视化与多角色的不同路线

Dify 走的是可视化工作流路线，拖拽节点就能编排一个 Agent 流程，适合快速验证想法和给非技术同学演示。它的优势是门槛低，劣势是复杂逻辑表达起来受限，而且从 Dify 工作流转成 Spring AI 的 Java 代码，中间需要大量手动翻译，热搜里就有人问这个。

CrewAI 专注多 Agent 协作，你可以定义几个角色，每个角色有自己的目标和工具，让它们分工完成一个任务。这个模式适合模拟团队协作场景，比如一个 Agent 负责调研、一个负责写作、一个负责审核。但多 Agent 的调试比单 Agent 复杂得多，不建议入门阶段碰。

6. MCP 是什么，为什么值得单独了解

6.1 MCP 解决的是工具接入标准化问题

MCP 全称 Model Context Protocol，你可以把它理解成“Agent 和外部工具之间的统一接口规范”。在没有 MCP 之前，你每接一个工具就要写一套适配代码，查数据库写一套、调 API 写一套、读文件写一套。MCP 定义了一套标准协议，工具提供方按这个协议暴露能力，Agent 按这个协议调用，双方解耦。

这个思路的价值在于复用。比如有人写了一个操作数据库的 MCP Server，你直接接进来就能用，不用自己从头写。热搜里出现的“ida mcp”“x32dbg 的 mcp 插件”“altium designer ai 接口 mcp”，说明 MCP 正在往各种专业工具里渗透，逆向工程、硬件设计这些领域都有人在接。

6.2 入门阶段怎么理解 MCP

你不需要一上来就自己写 MCP Server。入门阶段先理解三个概念就够了：MCP Host 是运行 Agent 的程序，MCP Client 是 Host 里负责和 Server 通信的模块，MCP Server 是提供具体工具能力的一方。三者之间用标准协议通信，Server 可以本地跑也可以远程跑。

想动手体验的话，可以找一个现成的 MCP Server 接进来试试。比如文件操作的 Server，让 Agent 通过 MCP 读写本地文件。你会看到工具调用的流程和你手写的原生版本本质一样，只是通信格式标准化了。等你理解了这一层，再去看 LangChain 或 Spring AI 里怎么集成 MCP，就会很顺。

注意：MCP Server 的权限控制很重要。一个能读写文件、执行命令的 Server，如果被恶意提示词诱导，可能造成数据泄露或误操作。生产环境一定要限制 Server 的能力范围，做好沙箱隔离。

7. 新手最容易踩的五个坑

7.1 坑一：环境没配好就开始抄代码

这是最高频的问题。Python 没加 PATH、虚拟环境没激活、依赖版本冲突，任何一个都能让你卡半天。我的建议是，每装完一个东西就验证一下，python --version、pip list、python -c "import xxx"，确认没问题再往下走。别一口气装一堆，出了问题不知道是哪个环节的锅。

7.2 坑二：提示词写得太随意

工具描述、系统提示词、输出格式要求，这些写得含糊，模型行为就会飘。我见过有人工具描述只写“查询数据”，模型根本不知道查什么数据、参数是什么，结果要么不调用，要么乱传参数。把提示词当成给新同事写交接文档，写清楚背景、目标、格式、边界，模型的表现会稳定很多。

7.3 坑三：不做错误处理

模型会输出格式错误的内容，工具会调用失败，网络会超时。如果你的代码没有 try-except，一个异常就整个流程崩掉。入门阶段就要养成习惯：模型输出解析失败怎么办、工具调用失败怎么办、超过最大循环次数怎么办，这些都要有兜底逻辑。

7.4 坑四：一上来就搞多 Agent

多 Agent 协作听起来很酷，但调试难度是指数级上升的。两个 Agent 互相等待、消息格式对不上、任务分配不合理，问题一大堆。先把单 Agent 跑稳，理解清楚工具调用和上下文管理，再考虑多 Agent。单 Agent 都搞不定，多 Agent 只会更乱。

7.5 坑五：只看教程不动手

AI Agent 这个领域，看十篇教程不如自己跑通一个 demo。很多细节问题只有亲手做才会遇到，比如模型返回的 JSON 多了个换行、工具参数类型不对、上下文超长被截断。这些经验是看不会的，必须踩过才算数。

8. 一条可执行的四周学习路线

8.1 第一周：Python 基础和 API 调用

目标是把 Python 基本语法过一遍，能写函数、能处理字典和列表、会用 requests 发 HTTP 请求。然后注册一个大模型 API，用最原始的方式发一条消息、收一条回复。这一周不求快，求稳，环境配好，基础打牢。

8.2 第二周：手写 Agent 核心循环

用原生 Python 实现工具定义、模型调用、结果解析、循环控制。先做一个单工具的 Agent，比如查天气。跑通之后加第二个工具，观察模型怎么在多个工具之间选择。这一周结束，你应该能画出 Agent 的执行流程图，说清楚每一步在干什么。

8.3 第三周：引入框架重写

选一个框架，LangChain 或 Spring AI 都行，把第二周的功能重写一遍。重点不是功能本身，而是对比框架帮你省了哪些事、引入了哪些新概念。遇到不懂的组件，回到你手写的版本里找对应，理解会快很多。

8.4 第四周：接 MCP 和做小项目

找一个现成的 MCP Server 接进来，体验标准化工具接入的流程。然后做一个小项目，比如“自动整理本地文件”或者“根据日程查天气提醒带伞”。项目不用复杂，重点是完整走一遍从需求到落地的流程，把前面学的东西串起来。

这个路线不追求速成，四周下来你对 Agent 的理解会比那些直接啃框架的人扎实得多。后面你再去看 Dify 的工作流、CrewAI 的多角色、企业级的 Agent 部署方案，都会有一个稳固的参照系。

我自己带人的经验是，那些先手写再学框架的人，遇到问题能自己定位，因为他们知道框架底层在干什么。而那些直接上框架的人，一旦报错就懵，只能到处搜或者问人。这个差别在入门阶段不明显，但到了要改框架源码或者做定制化的时候，差距就拉开了。所以别急，先把最朴素的那条路走一遍。