AI Agent入门指南：从Dify到LangChain的实战学习路线

1. 别急着打开IDE先搞清楚AI Agent到底在解决什么问题我见过太多人学AI Agent的路径是这样的刷到一条用Coze三分钟搭建智能客服的短视频热血上头当晚就去注册账号、拉代码、装Docker结果卡在环境配置上折腾了三天最后连一个能跑通的Demo都没做出来热情直接归零。这个场景太常见了常见到我每次在社群里看到有人问LangChain和Dify到底学哪个的时候都想先反问一句你能不能用一句话说清楚你要做的这个东西输入是什么、输出是什么、中间需要做哪几步判断如果答不上来那问题不在框架选型在于你还没理解Agent的本质。1.1 从对话到行动Agent和普通Chatbot的分水岭普通Chatbot的工作模式是你问我答它的能力边界就是模型本身的知识和推理能力。你问它今天天气怎么样它只能告诉你我无法获取实时信息。而Agent的核心区别在于它多了三个东西工具调用能力、任务规划能力、记忆与状态管理。用生活化的类比来说普通Chatbot像一个博学的朋友你问他什么他都能聊但他坐在房间里出不去。Agent则像给这个朋友配了手机、电脑、记事本和一双腿——他可以打电话查天气、上网搜资料、把重要信息记在本子上、然后根据查到的结果决定下一步做什么。这个决定下一步做什么的过程就是Agent的灵魂。具体到技术层面一个最小可用的Agent循环是这样的接收用户目标比如帮我查一下北京明天适不适合户外跑步规划步骤模型自己拆解——需要查天气、查空气质量、综合判断调用工具调用天气API获取温度、湿度、风力调用空气质量API获取PM2.5观察结果拿到返回数据判断是否完成如果信息够了就生成回答不够就回到第2步继续规划输出最终结果给出适合/不适合的结论和理由这个循环在学术上叫ReActReasoning Acting模式是目前绝大多数Agent框架的底层逻辑。你去看LangChain的AgentExecutor、Dify的工作流引擎、Coze的Bot编排本质上都是在实现这个循环只是封装程度和侧重点不同。1.2 为什么新手容易在框架选择上卡住框架选择困难的根源是市面上这些工具根本不在同一个抽象层级上。我把它们分成三类你一看就明白了层级代表工具面向人群核心特点可视化编排层Coze、Dify产品经理、运营、非技术背景拖拽式搭建无需写代码快速验证想法代码框架层LangChain、LangGraph有编程基础的开发者灵活度高可深度定制学习曲线陡底层基础设施模型API、向量数据库、工具协议架构师、高级开发者关注性能、成本、可扩展性新手最容易犯的错误是跳过第一层直接啃第三层。你连Agent的基本工作流程都没跑通过就去研究LangGraph的状态图怎么设计、Checkpointer怎么做持久化这不是学习这是自虐。我的建议很直接如果你是完全的新手或者转行者先从Coze或Dify这类可视化平台入手用拖拽的方式把一个完整的Agent跑通建立起对规划-调用-观察-输出这个循环的肌肉记忆。等你觉得可视化平台的灵活性不够用了再往下钻代码框架。1.3 一个判断标准你什么时候该换工具很多人问我什么时候该从Dify换到LangChain我的判断标准很简单当你发现你需要实现一个逻辑而在当前工具里找不到对应的节点或配置项时就是该换的时候了。举个例子你在Dify里搭了一个知识库问答机器人跑得挺好。但有一天产品经理说用户问完问题之后如果知识库里没有匹配的内容要自动去调用外部搜索API搜到的结果要先经过一个敏感词过滤过滤通过后再让模型总结总结的时候要带上用户的历史对话记录。这时候你会发现Dify的工作流虽然能做条件分支但那个敏感词过滤的步骤要么得自己写代码节点要么得外挂一个服务——这时候你就该考虑用LangChain或者LangGraph来实现了。但注意这个判断的前提是你已经在Dify里把能做的都做了而不是一上来就觉得可视化平台太low我要写代码。2. 可视化平台实战用Dify跑通你的第一个Agent理论说再多不如动手跑一遍。这一章我带你用Dify从零搭一个能用的Agent过程中会把每个决策背后的原因讲清楚。选Dify而不是Coze作为入门首选原因有两个一是Dify支持本地部署数据在自己手里学习过程中不用担心额度限制二是Dify的工作流编排更接近底层逻辑你在这里建立的心智模型后面迁移到LangChain会顺畅很多。2.1 部署方式的选择Docker还是云端Dify提供两种使用方式云端版和本地部署。新手我强烈建议先用云端版把功能跑通再考虑本地部署。原因很简单——本地部署Dify需要Docker环境而Docker在Windows上的安装和配置本身就是一道坎很多人还没开始学Agent就先被Docker的网络问题劝退了。但如果你确实需要本地部署比如数据不能出内网Docker Compose是最省事的方案。基本流程是# 克隆仓库 git clone https://github.com/langgenius/dify.git cd dify/docker # 复制环境变量文件 cp .env.example .env # 启动服务 docker compose up -d启动之后访问http://localhost:3000就能看到界面。这里有几个新手必踩的坑我提前说端口冲突Dify默认用80和3000端口如果你本机已经跑了Nginx或者其他服务需要改.env文件里的EXPOSE_NGINX_PORT和EXPOSE_NGINX_SSL_PORT镜像拉取慢配置国内镜像加速这个不多说搜一下就有数据库初始化失败多半是.env里的数据库密码包含特殊字符导致的换成纯字母数字组合试试实测经验如果你只是学习用云端版完全够用而且省去了所有运维烦恼。本地部署留到你需要做二次开发或者数据合规要求高的时候再折腾。2.2 模型接入本地模型还是APIDify本身不提供模型你需要接入外部模型。这里有两个选择接APIOpenAI、通义千问、DeepSeek等或者接本地模型通过Ollama。对于新手我的建议是先用API。原因很实际本地跑模型对硬件有要求7B参数的模型至少需要8GB显存才能跑得比较流畅13B以上就需要专业显卡了。而且本地模型的推理速度和质量在入门阶段可能会让你对Agent的能力产生误判——你以为是Agent设计得不好其实是模型本身能力不够。如果你确实想用本地模型Ollama是目前最省心的方案。安装好Ollama之后拉一个模型ollama pull qwen2.5:7b然后在Dify的模型设置里选择Ollama作为提供商Base URL填http://host.docker.internal:11434注意如果你用的是Docker部署的Dify这里不能填localhost因为容器内的localhost指向的是容器本身不是宿主机。这个host.docker.internal的坑我见过至少几十个人踩过现象就是模型列表加载不出来一直报连接错误。记住这个地址能省你两个小时。2.3 第一个工作流从能跑到好用的关键配置假设我们要搭一个技术文章摘要生成器用户输入一篇文章的链接或者正文Agent自动抓取内容、生成摘要、提取关键词。在Dify的工作流里节点是这样串的开始节点接收用户输入的article_textLLM节点摘要生成Prompt写请对以下文章生成200字以内的摘要保留核心观点和关键数据LLM节点关键词提取Prompt写从以下文章中提取5-8个关键词用逗号分隔结束节点输出摘要和关键词看起来很简单对吧但这里有几个决定输出质量的关键细节Prompt里的变量引用格式。Dify用{{变量名}}来引用上游节点的输出但新手经常忘记在LLM节点的上下文里添加变量导致模型根本看不到输入内容。这个配置项在LLM节点的设置面板里叫上下文变量必须手动添加。温度参数的设置。摘要生成任务需要稳定、忠实的输出温度设0.1-0.3比较合适。关键词提取可以稍微高一点0.3-0.5让模型有一定的灵活性。如果你做的是创意类任务比如起标题温度可以拉到0.7-0.9。输出格式的控制。如果你希望摘要和关键词以JSON格式输出方便后续程序处理需要在Prompt里明确要求并且给出示例。比如请以JSON格式输出格式如下 { summary: 摘要内容, keywords: [关键词1, 关键词2] }实测下来给出具体示例的Prompt格式遵从率能从60%提升到95%以上。这个技巧在所有Agent框架里都通用。2.4 知识库的坑为什么你的RAG效果不好Dify的知识库功能是很多人入坑的原因但也是失望最多的地方。典型场景是上传了十几份PDF兴冲冲地去问问题结果要么答非所问要么直接说根据知识库内容无法回答。问题通常出在三个地方分段策略。Dify默认的分段是固定长度分段每段500字符。这个策略对结构清晰的文档还行但对那种一段就是好几页的技术文档切出来的片段语义不完整检索效果自然差。我的经验是技术文档用按段落分段或者自定义分段标识符比如按Markdown的二级标题切分效果会好很多。索引方式。Dify提供高质量索引和经济索引两种。高质量索引会调用模型对每个片段生成向量检索精度高但消耗Token经济索引用关键词匹配不消耗Token但精度差。学习阶段用高质量索引生产环境根据预算权衡。检索参数。TopK设多少、相似度阈值设多少这两个参数直接决定检索结果的质量。TopK太大会引入不相关的片段干扰模型判断太小可能漏掉关键信息。我的起步配置是TopK3相似度阈值0.5然后根据实际效果微调。一个容易被忽略的细节Dify知识库的召回测试功能一定要用。上传完文档后别急着去对话先在召回测试里输入几个你预期的问题看看实际召回的片段是不是你想要的。这一步能帮你快速定位是分段问题还是检索参数问题。3. 代码框架入门LangChain的核心抽象其实就四个当你在Dify里把工作流玩明白了开始觉得这个逻辑我想用代码控制的时候就可以进入LangChain了。但我要先给你打个预防针LangChain的文档质量参差不齐版本迭代快网上很多教程已经过时了。你搜到的LangChain入门教程可能是基于0.0.x版本的而现在已经到0.3.x了API变化很大。所以学LangChain我的建议是直接看官方文档的Concept部分把核心抽象搞清楚然后动手写。不要一上来就啃源码也不要跟着那些半年前的博客教程走。3.1 LangChain的四个核心概念LangChain的抽象很多但真正核心的就四个Model模型统一了各种大模型的调用接口。不管是OpenAI、Anthropic还是本地模型在LangChain里都通过ChatModel接口调用。这个抽象的价值在于你换模型的时候不需要改业务代码只需要换一个初始化参数。Prompt提示词模板把提示词从代码里抽出来变成可复用的模板。支持变量插值、Few-shot示例、输出格式指定。这个抽象的价值在于提示词可以独立迭代不需要改代码逻辑。Chain链把多个步骤串起来。最简单的链是Prompt → Model → Output Parser复杂的链可以包含条件分支、循环、并行执行。LangChain Expression LanguageLCEL是现在推荐的链式写法用管道符|连接各个组件。Memory记忆管理对话历史。LangChain提供了多种记忆策略从最简单的保留最近N轮对话到复杂的对历史对话做摘要压缩。这个抽象的价值在于你不需要自己管理对话状态的存储和截断逻辑。把这四个概念理解了LangChain的80%功能你就能看懂了。剩下的Agent、Tool、Retriever这些都是在这四个基础上的扩展。3.2 用LCEL写一个最小可用的Agent下面这段代码是一个完整的、能跑通的Agent示例功能是根据用户问题决定是否调用计算器工具from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.tools import tool from langchain.agents import AgentExecutor, create_tool_calling_agent # 1. 定义工具 tool def calculator(expression: str) - str: 计算数学表达式输入应该是合法的Python数学表达式 try: result eval(expression) return str(result) except Exception as e: return f计算错误: {e} # 2. 初始化模型 llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 3. 定义Prompt prompt ChatPromptTemplate.from_messages([ (system, 你是一个数学助手可以使用计算器工具来计算数学表达式。), (human, {input}), (placeholder, {agent_scratchpad}), ]) # 4. 创建Agent tools [calculator] agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 5. 运行 result agent_executor.invoke({input: 计算 (23 * 47) 156 等于多少}) print(result[output])这段代码虽然短但包含了Agent的所有核心要素模型、工具、提示词、执行循环。verboseTrue打开之后你能看到Agent的完整思考过程——它先判断需要调用计算器然后生成工具调用请求拿到结果后再生成最终回答。注意agent_scratchpad这个占位符它是Agent循环的草稿纸用来记录中间步骤的思考和工具调用结果。如果你忘了加这个占位符Agent会报错或者陷入死循环。这是新手最容易漏掉的一行。3.3 从LangChain到LangGraph什么时候需要状态图LangChain的AgentExecutor能处理大部分线性流程但当你需要以下能力时就该考虑LangGraph了循环和条件分支比如如果检索结果不相关就重新改写查询再检索一次人工介入比如在执行敏感操作前暂停等待人工确认多Agent协作比如一个Agent负责规划一个负责执行一个负责审核状态持久化比如用户中断对话后下次可以从中断点继续LangGraph的核心思想是把Agent的执行过程建模成一个状态图每个节点是一个处理步骤边定义了步骤之间的流转条件。相比LangChain的链式结构LangGraph更灵活但也更复杂。我的建议是先用LangChain把线性流程跑通遇到LangChain表达不了的逻辑时再迁移到LangGraph。不要一上来就用LangGraph它的学习曲线会让你怀疑人生。4. 转行者的学习路线三个月从零到能干活如果你是从其他行业转过来的没有编程基础或者编程基础薄弱下面这条路线是我带过的人里验证有效的。前提是每天能投入2-3小时。4.1 第一个月建立体感不碰代码第一个月的目标不是学会什么技术而是建立对Agent能力的体感。你需要知道Agent能做什么、不能做什么、做得好什么、做得差什么。具体做法第一周注册Coze和Dify各搭三个Bot。一个知识库问答、一个工作流自动化、一个带工具调用的助手。不要看教程自己摸索遇到问题再搜。第二周把Dify的官方文档从头到尾读一遍重点看工作流节点说明和知识库配置。然后把你第一周搭的Bot重新优化一遍对比优化前后的效果差异。第三周找一个真实的需求来做。比如帮你自动整理每周的工作周报或者做一个能回答你所在行业常见问题的助手。真实需求会逼你解决各种边界情况。第四周复盘。把你踩过的坑、解决的问题、还没搞懂的地方列出来。这份清单就是你第二个月的学习重点。这个阶段的关键是不要追求完美。你的Bot回答不准、流程有bug都很正常重要的是你亲手跑通了整个流程知道了每个环节大概是怎么回事。4.2 第二个月补编程基础从Python开始如果你已经有编程基础这个月可以直接跳到LangChain。如果没有老老实实花两周学Python基础。不需要学完整个Python教程你只需要掌握变量、数据类型、条件判断、循环函数定义和调用列表和字典的基本操作类的概念知道怎么用就行不需要会写复杂的类异常处理try/except虚拟环境和pip安装包这些内容每天两小时两周足够。推荐的学习方式是边学边用——不要光看教程每学一个概念就用它写一个小脚本。比如学了函数就写一个输入文章输出摘要的函数调用模型API。第三周开始接触LangChain。先跑通官方文档里的Quickstart然后把你上个月在Dify里搭的工作流用LangChain重新实现一遍。这个过程会让你深刻理解可视化编排和代码实现的对应关系。第四周学LangGraph的基础概念把LangChain实现的那个流程改成LangGraph版本。不用追求优雅能跑就行。4.3 第三个月做项目积累作品前两个月是输入第三个月必须输出。找2-3个真实场景做成完整的项目。项目选择的原则有真实用户哪怕用户就是你自己。比如自动整理我的收藏夹、帮我回复常见客户咨询有明确的输入输出不要做那种什么都能聊的通用助手做垂直场景能展示技术能力最好能覆盖RAG、工具调用、工作流编排这几个核心能力每个项目做完之后写一篇复盘文档记录需求是什么、技术方案怎么选的、遇到了什么问题、怎么解决的、还有什么可以优化的。这份文档比项目本身更有价值面试的时候拿出来比说我学过LangChain有说服力一百倍。5. 那些没人告诉你但一定会踩的坑这一章是我自己踩过的、以及带人过程中看到最高频的坑。每一个都真实发生过每一个都有解。5.1 Token消耗失控你的Agent可能在偷偷烧钱Agent和普通Chatbot最大的成本差异在于Agent的每一次循环都会把完整的对话历史发给模型。一个需要5步才能完成的任务Token消耗可能是单次对话的5-10倍。我见过最夸张的案例是一个做文档分析的Agent因为Prompt里塞了完整的文档内容每次调用消耗几万Token跑一天下来账单几百块。控制Token消耗的几个实用手段对话历史截断只保留最近N轮对话或者对历史对话做摘要压缩工具返回结果精简工具返回的数据不要原封不动塞给模型先做过滤和提取Prompt优化去掉不必要的示例和说明用更简洁的表达设置最大循环次数AgentExecutor的max_iterations参数一定要设防止死循环一个监控技巧在开发阶段把每次调用的Token消耗打印出来。LangChain的ChatOpenAI支持通过get_num_tokens_from_messages方法估算Token数。养成这个习惯能帮你及时发现异常消耗。5.2 工具调用的幻觉模型说它调了其实没调这是Agent开发中最隐蔽的坑之一。模型在回答里说我已经帮你查了天气今天北京晴25度但实际上它根本没有调用天气API那个数据是它编的。这个问题的根源在于模型被训练成尽量给出完整回答所以当它不确定要不要调用工具时倾向于直接编一个答案。解决方案在Prompt里明确要求如果问题需要实时数据必须先调用工具不能凭记忆回答用tool_choice参数强制调用OpenAI的API支持tool_choicerequired强制模型必须调用工具在输出解析层做校验检查模型的回答里是否包含工具调用的痕迹如果没有就重新执行实测下来Prompt约束输出校验的组合能把工具调用幻觉降到可接受的水平。5.3 知识库的排队中Dify索引卡住怎么办Dify知识库上传文档后状态一直显示排队中或者索引中半天不动。这个问题在社区里问的人特别多。常见原因和排查顺序模型API额度用完了高质量索引需要调用Embedding模型如果API额度耗尽索引任务会卡住。去模型提供商后台确认额度。文档太大单个文档超过10MB或者页数超过500页索引时间会很长。拆分成小文档再上传。向量数据库连接问题如果你用的是外部向量数据库比如Weaviate、Qdrant检查连接配置是否正确。Dify服务资源不足本地部署的Dify如果服务器内存不够索引任务可能被系统杀掉。看Docker日志确认。排查顺序建议从1到4因为前两个原因占了80%的情况。5.4 上下文超长Dify工作流的隐形杀手Dify工作流里如果上游节点的输出内容很长比如一篇文章的全文直接传给下游LLM节点很容易触发模型的上下文长度限制报context length exceeded错误。解决方案有三种在中间加一个摘要节点先用一个LLM节点把长文本压缩成摘要再传给下游用文本分割节点把长文本切成小块分批处理在LLM节点里设置最大Token数Dify的LLM节点有最大标记数参数限制输出长度但注意这限制的是输出不是输入最稳妥的方案是第一种在流程设计的时候就考虑好每个节点的输入长度不要等到报错了再改。6. 框架选型的最终建议别问哪个好问你要做什么回到最开始的问题LangChain、Dify、Coze、LangGraph到底学哪个我的答案从来都是看你要做什么而不是看哪个火。如果你要做的是快速验证一个想法或者给非技术团队做一个内部工具Dify和Coze是最优解。它们的可视化编排能让你在几小时内看到效果试错成本极低。如果你要做的是需要深度定制、要和现有系统集成的产品LangChain是绕不开的。它的灵活性是可视化平台给不了的但代价是更高的学习成本和更长的开发周期。如果你要做的是复杂的多步骤、多Agent协作、需要人工介入的流程LangGraph是目前最成熟的方案。但前提是你已经把LangChain用熟了。至于基于Rust语言的AI Agent这类新兴方向我的建议是保持关注但不要急着投入。Rust在性能和并发上有优势但生态成熟度还差得远现在入场大概率是给社区做贡献而不是做产品。学Agent这件事最怕的就是用战术上的勤奋掩盖战略上的懒惰——花大量时间比较框架、配置环境、追新工具但从来没有完整地解决过一个真实问题。选一个工具扎进去做出东西来比什么都重要。我在带人的过程中发现一个规律那些进步最快的人往往不是最聪明的而是最能忍受不完美的。他们用一个不完美的工具做出一个能跑的东西然后在迭代中慢慢优化。而那些一直在等最好的工具的人半年后还在问新手该学什么。所以别再问了。打开Dify注册账号搭你的第一个Bot。遇到问题就搜搜不到就问问不到就换个方式试。这个过程本身就是最好的学习。