最近几个月我收到最多的私信就是“AI Agent 新手到底怎么入门”尤其是一些准备转行的朋友一上来就问我LangChain和Dify哪个好、Agent框架到底该啃哪一个。我每次都会先泼一盆冷水你先别急着选框架AI Agent的核心思路都没跑通盲目啃框架只会让你在抽象层里越转越晕。AI Agent说白了就是一个能自主规划、调用工具、根据反馈不断调整行动的智能程序本质上是“大模型决策循环工具库”的组合。这篇文章就是写给刚接触AI Agent的新手或者准备从传统开发、数据分析转行过来的朋友我先带你看懂Agent底层是怎么运作的再给你一条“不依赖任何框架”的入门路径最后才说框架到底该怎么选、什么时候上。阅读全文大约需要二十分钟但我建议你跟着实操一遍比收藏十篇教程都管用。1. 先搞清楚Agent是什么——新手入门前的心态准备1.1 Agent的底层三件套模型、工具、循环很多新手把Agent想得很玄觉得它是一个会自己“思考”的超级程序。实际拆开来看一个最小可用的Agent就三个东西一个能理解自然语言的大模型一组能被调用的工具函数还有一个控制执行流程的循环。模型负责“想”工具负责“做”循环负责“重复想-做直到出结果”。这跟人类解决一道复杂问题的思路非常像先读题然后列出步骤试着执行一步看结果不对再调整。普通程序是写死的if-else分支走哪条路完全由程序员预定Agent则是把“决策权”交给了大模型让模型根据当前情境临时决定下一步干什么。举个例子你给一个传统程序“帮我查北京天气再提醒我带伞”如果代码里没写“带伞提醒”这个分支它就做不了。但Agent不一样它会把任务拆成“查天气-看降水概率-判断是否提醒”每一步都由模型灵活决策。这个“灵活”既是Agent的亮点也是Agent的难点——亮点在于它能处理开放任务难点在于你要花很多功夫教会它别跑偏。1.2 脱离框架理解主流架构ReAct是最好上手的起点讲架构之前先声明Agent架构在工程领域有很多变体比如Plan-and-Execute、Self-Refine、Multi-Agent等。但对新手来说ReActReasoning Acting是最值得先弄懂的一个没有之一。ReAct的核心是一个循环Reason模型根据当前信息进行推理说明为什么这么做→ Act调用某个工具完成一个动作→ Observe观察工具返回的结果→ 再Reason……如此反复直到模型认为任务完成了。很多框架底层都在做这件事只是换了个名字而已。理解ReAct最好的方式是自己手写一遍这个循环哪怕只有三十行代码。这也是这篇文章的核心建议先实现一遍再谈框架。因为只有亲手写过ReAct你才会真正理解tool_calls是怎么工作的、工具返回结果是怎么喂回模型的、系统提示词在约束模型行为时有多重要——这些基本功如果靠框架掩盖过去后面做复杂项目时一定会补课。2. 入门到底该先学什么——知识地图和优先级排序我见过不少新手陷入一个误区买课先看LangChain实战报班先学Dify工作流搭建结果连system prompt和用户消息怎么拼接都说不清楚。这个顺序是反的。2.1 一定要先吃透的提示词工程与上下文管理Agent的能力上限很大程度取决于你写提示词的水平。这里的提示词不是“你是一个AI助手”这么一句话而是包括系统提示词system prompt、任务描述、约束条件、示例few-shot在内的完整上下文设计。我说几个新手最容易忽略的细节。第一系统提示词要写清楚工具使用的边界比如“只有在用户明确要求查天气时才调用天气工具”否则模型会在闲聊时也莫名触发工具。第二工具描述要精确因为你传给大模型的不是Python函数本身而是一段描述这个函数功能的JSON模型靠这段描述来决定要不要调用它描述写得太模糊模型就会瞎猜参数。第三注意上下文的长度限制和成本每轮对话都会把历史记录重发给大模型消息太长不光慢还烧钱后面要学截断和压缩。这些听起来平平无奇但真到实操中八成以上Agent翻车都是提示词和上下文管理没做好而不是模型不够聪明。所以我把这块放在最高优先级。2.2 躲不开的实操课LLM接口调用与Function Calling如果连最基本的一次大模型接口调用都没写过先不要急着碰Agent。你需要先会用代码发起一次chat completion请求能处理返回的JSON能处理流式输出stream最好还要理解什么是temperature、max_tokens这些参数。这些是Agent的地基地基不牢楼盖得再花哨也白搭。接下来要重点练Function Calling有的平台叫工具调用Tool Use。这是Agent最关键的机制你给大模型描述好有哪些工具可用模型在回答中会返回一个结构化的“我想调用某个工具、参数是什么”的指令然后你的代码去执行真实函数再把执行结果返回给模型。整个过程可以理解为模型先写了一张“执行申请单”你负责去跑腿然后把跑腿结果拿回来给模型过目模型再决定下一步。这个机制难在两点一是工具函数的输入参数必须能被正确解析和校验二是工具的执行结果要以正确的消息格式回传给模型格式错了模型会直接报错或者产生幻觉。这两个坑我后面在实操部分会详细演示。2.3 先放一放的进阶话题向量检索、RAG、多智能体协作网上很多Agent教程喜欢第一课就讲RAG再讲向量数据库还给你画一堆多智能体架构图。我建议新手先别碰这些。为什么RAG解决的是“给模型补充私有知识”的问题比如你要让Agent回答公司内部文档里的问题。但它的前提是你已经能跑通一个干净的单Agent循环否则检索结果回来了、上下文塞进去了你根本分不清问题出在检索、上下文还是Agent决策上排查成本直接翻倍。向量数据库、embedding、多智能体协作都属于“锦上添花”的进阶能力。我的建议是花两周时间把单Agent的ReAct循环吃透再加一点RAG也不迟。基础路径应该像盖楼一样先框架后装修而很多人恰恰把装修材料搬进来就开始往里堆连承重墙都没砌。3. 框架怎么选——主流Agent框架的真实定位说到这一步才轮到框架。我知道大家很关心LangChain、Dify、CrewAI这些名字到底怎么选先上一张速查表再解释背后的逻辑。3.1 一句话看懂LangChain、Dify、CrewAI、MetaGPT框架/工具核心定位适合谁上手难度LangChain通用开发框架提供链式调用、工具集成、记忆管理等底层组件有一定开发基础想深度定制Agent的开发者中等偏难概念多Dify低代码Agent应用平台提供可视化工作流编排和大量现成插件产品、运营、非深度开发者低拖拽即可CrewAI专注于多Agent协作的轻量框架角色扮演式分工想快速体验多Agent协作场景的人中等MetaGPT模拟软件公司流水线的多Agent框架强调标准化流程对模拟组织协作感兴趣的人较高从这张表你应该能看出来它们解决的问题不太一样。LangChain是“乐高积木”灵活性最高代价是概念特别多Chain、Agent、Tool、Memory、OutputParser堆在一起新手很容易把注意力浪费在框架API上。Dify是“傻瓜相机”对新手友好但它帮你封装了太多东西你能快速做出东西却很难知道底层发生了什么。这就像会开车和会修车的区别——能用Dify做出Agent不代表你理解Agent。3.2 为什么我劝新手别一上来就啃框架我见过太多这样的案例一个转行做了三个月的同学简历上写着“熟练使用LangChain开发Agent”但你让他解释一下Agent循环里tool_calls是什么、为什么工具返回结果要单独作为tool消息而不是直接拼进用户消息他答不上来。这不是他的问题是学习顺序的问题——他被框架推着走框架替他把复杂的东西藏起来了他反而失去了理解底层的机会。框架有一个共性就是抽象。抽象本身是好事能把重复劳动屏蔽掉。但问题是AI Agent这个领域到今天都还没有真正稳定的标准LangChain的API都可能隔一个版本就变动你今天啃熟了过两个月可能又变了。如果你没有底层理解作为“压舱石”框架一变你等于重新学。所以我的建议非常明确入门阶段框架可以看、可以试用但不要把你全部精力压在某一个框架上。先用原生代码手写一个最小Agent你才会知道框架帮你解决了什么、又替你藏起了什么。这也是我常跟新手说的先学内功再看招式。3.3 什么阶段开始碰框架比较合适具体来说我会建议新手在满足下面几个条件后再系统学习框架一是已经手写过一遍ReAct循环能说清楚大模型、工具、上下文三者的关系二是至少做过一个能跑通的单Agent项目哪怕只是一个“天气查询小助手”三是对提示词工程已经有手感知道怎么引导模型行为。满足这三条之后学框架会非常快因为你带着问题和需求去学而不是因为焦虑去学。比如你用原生代码开发Agent时发现历史记忆管理特别繁琐这时候再去学LangChain的Memory模块你会秒懂它解决什么问题你发现编排多个子任务容易乱再去试CrewAI才能体会到它的价值在哪里。记住框架是工具不是知识。知识是Agent的底层原理工具是帮你省事的捷径。急着拥抱工具往往是因为不想面对知识。4. 从零手写一个最小可用的Agent——不装任何框架说了这么多理念不如直接动手。这一节我会带你手写一个不依赖任何框架的最小Agent用户随便问一句话Agent内部会判断要不要调用天气工具调用完再结合结果回复用户。这个例子我已经在很多社群分享过反馈是“比想象中简单也比想象中更接近本质”。4.1 准备工作API、环境、一个具体的任务先说环境。你需要一个能调用的LLM接口最方便的是OpenAI兼容接口市面上也有不少兼容服务商另外需要一个Python 3.9以上的环境。不需要装LangChain不需要装Dify只需要安装openai这个SDK就够了一条命令搞定pip install openai。任务设定很简单做一个“带天气查询功能的问答Agent”。用户可能会问“北京今天天气怎么样”“明天要不要带伞”这类话。Agent要能识别出用户想查天气把城市名提取出来调用一个假的天气查询函数然后把函数返回的结果组织成自然语言回复给用户。这里我故意用假的天气数据源而不是真的去调天气API因为重点在展示Agent的工作机制不在网络请求。你把假函数换成真实API请求即可逻辑完全一致。4.2 核心实现写一个带工具调用的ReAct循环完整代码如下代码不长但你认真读完它比看一百页框架文档都有用import json from openai import OpenAI # 模拟工具返回一个假天气数据 def get_weather(city: str) - str: data { 北京: 晴25°C湿度40%, 上海: 小雨20°C湿度85%, 深圳: 多云28°C湿度70%, } return data.get(city, f暂无{city}的天气数据) tools [ { type: function, function: { name: get_weather, description: 查询指定城市当天天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名称例如北京} }, required: [city] } } } ] functions_map {get_weather: get_weather} def run_agent(user_query: str, max_iterations: int 5) - str: client OpenAI() messages [ {role: system, content: 你是一个有用的助手。请根据工具返回结果生成友好的回复。}, {role: user, content: user_query} ] for i in range(max_iterations): response client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools, tool_choiceauto ) msg response.choices[0].message messages.append(msg) # 如果没有工具调用说明Agent认为可以给出最终回复了 if not msg.tool_calls: return msg.content # 依次执行每个工具调用并把结果以tool消息返回给大模型 for tc in msg.tool_calls: func_name tc.function.name args json.loads(tc.function.arguments) result functions_map[func_name](**args) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) }) return 达到最大迭代次数Agent任务未完成请检查提示词或工具定义。 if __name__ __main__: print(run_agent(北京今天天气怎么样我需要提前准备什么吗))仔细观察这段代码三个核心点都被你亲手实现了一是模型通过tools参数知道有哪些工具可用二是模型返回的tool_calls告诉你它想调用什么、参数是什么三是你把工具执行结果以role“tool”的消息回传给模型让模型看到结果并生成最终回复。这就是ReAct循环的最简形态全部加起来不到六十行。4.3 运行效果与关键细节这段代码跑起来可能的输出类似北京今天天气晴朗气温25°C左右湿度40%体感比较舒适没有明显降水概率。这种情况下不需要特别准备雨具但早晚温差可能略大建议带一件薄外套。看模型完成了“理解query→调用天气工具→拿到结果→生成建议”的完整链路。如果我不用工具只让语言模型直接硬答它能“编”出天气数据但有了工具调用它回答的依据是真实函数返回的结果从“猜”变成了“查”这就是Agent和普通聊天机器人的分水岭。这里有几个新手特别容易踩的细节。第一json.loads解析参数时要做异常处理因为模型生成的JSON偶尔会有缺引号、多逗号的情况我在示例里为了简洁没写try-except真实项目里一定要加。第二工具返回的content类型必须是字符串不能直接传dict代码里用json.dumps就是为了保证这一点。第三循环要有迭代上限防止模型陷入“无限调用工具”的循环烧钱我设了5次是一个保守值真实场景按需调整。5. 新手常见问题实录与避坑指南到了这一节我想把实际答疑过程中出现频率最高的问题整理一下希望能帮你在入门的路上少走弯路。5.1 高频问题速查表现象/问题原因分析排查/解决思路模型不调用工具直接瞎答工具描述不清晰或模型认为不需要工具检查工具的description和参数说明让指令更明确必要时在system prompt里强调“必须调用工具”模型频繁调用工具停不下来上下文没有让模型“收尾”的信号或迭代上限设置过高加迭代上限在system prompt中说明“确认信息足够后直接回答不要继续调用”工具执行结果没有被模型采用工具消息格式不对或结果内容太长被截断检查role是否为“tool”、tool_call_id是否正确匹配多轮对话后Agent开始胡言乱语上下文太长、历史消息未管理引入消息截断、摘要压缩或参考成熟的memory设计参数解析JSON报错模型生成的JSON不规范加try-except捕获提示模型按schema输出或使用强类型工具解析接口请求超时/限流并发过高或网络不稳定加retry重试机制控制并发把超时时间调大这张表不在于罗列全部问题而是想说明一个规律绝大多数Agent问题根源都在“工具定义、上下文管理、循环设计”这三点上。框架可以帮你减少其中的一部分工作量但框架不能替你理解问题出在哪里。这也是我反复建议先手写一版再上框架的原因。5.2 我的几点实操心得最后分享几条我在实际项目里打磨出来的经验不保证适合所有人但至少是很多人用真金白银换来的教训。第一给工具函数写docstring和description的时候要用“对模型友好的语言”不要用“对程序员友好的语言”。模型看不到你的函数内部实现只能看到工具名和描述所以你把“查询指定城市当天天气情况”这种描述写得越直白模型越容易正确调用。第二把工具划分得越细Agent越容易被模型“选错”。有时候你以为多提供几个工具是给模型更多选择实际上是在增加它的决策负担。新手阶段宁可使用少量、职责明确的工具也不要搞一堆参数复杂的万能工具。第三日志比想象中的重要。手写Agent的时候一定要把每一轮的messages、工具调用参数、返回结果都打印出来。很多新手问“为什么模型不按我的要求做”一看日志就发现是自己的上下文理解错了或者工具返回结果本身就不是期望的格式。留日志的习惯能帮你节省大量试错时间。第四别迷信“最新架构”。今天可能有人跟你说GraphRAG很火明天有人说多智能体是未来对新手来说这些都是噪音。先把最简单的循环玩明白再往复杂方向走你会发现所谓“新架构”说来说去核心还是那一套模型加工具加循环的底子。第五做项目时从“垂直小功能”切入不要一上来就做一个“万能助理”。我见过太多新手第一个Agent想做个什么都管的全能助手最后连需求文档都写不清楚。先把“查天气”“查快递”“记笔记”这些单一能力做到稳定再考虑组合。做得越小越容易出成果越容易建立正反馈。我个人带过不少人从零接触Agent一个明显的感受是那些走得最快的人几乎都不急着炫耀自己用了什么花哨框架而是愿意在一个最简示例上反复打磨两三天。新手阶段框架账面上省下的时间最后往往会在排查底层问题时加倍还回来。踩过这些坑之后我是真的觉得先手写一个循环比什么都管用。