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.3API 改了一轮又一轮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: 你好}]}, timeout30 ) 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, toolstool_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 是什么为什么值得单独关注MCPModel 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 手写不碰框架第二工具描述当文档写越清楚越好第三从无聊但完整的场景开始别一上来就挑战高难度。把这三条做到你入门的速度会比啃框架快得多。至于后面怎么深入等你手写循环跑顺了、用过一两个框架了自然会知道下一步该学什么。这个领域变化快但底层的东西变得慢把底层吃透上面怎么变你都不慌。
