2025年10月LangChain和LangGraph同步发布了1.0版本。这件事在技术圈没有引起太大轰动大多数人甚至没注意到。但如果你在关注AI Agent的开发框架这个时间点值得停下来想一想。LangChain从2022年底诞生到现在不过三年多。三年时间一个框架从0到1.0迭代了三个完整的版本。2023年火的是Chain和RAG2024年大家在聊Agent Workflow2025年开始谈的是Long-Horizon Agents和Agent Harness。变化的不是版本号变化的是整个AI应用开发的底层逻辑。很多人已经开始感觉到AI不再只是一个聊天窗口了。它在写代码、查日志、调API、跑流程。它开始像人一样“干活”了。但问题也来了你喊了半年AI Agent真正自己动手写过几行这篇文章要解决的核心问题就是帮你跨越“概念理解”和“动手实践”之间的鸿沟。我们不止要讲清楚LangChain Agent的核心工作机制更要带你从零开始亲手构建一个能自主搜索、思考并回答问题的智能研究助手。更重要的是我们会深入探讨如何让一个Agent从玩具级的Demo走向真正能在生产环境稳定运行的工程化系统。1. 这篇文章真正要解决的问题如果你是一名开发者最近可能被各种关于AI Agent的讨论包围。从AutoGPT到Devin从LangChain到CrewAI概念层出不穷但当你真正想动手时却常常陷入困惑我直接调用大模型API不行吗为什么需要框架Agent到底是怎么“思考”和“行动”的写出来的代码能稳定运行吗这篇文章要解决的正是这些从理论到实践的关键障碍认知障碍理解AI Agent从“对话”到“行动”的范式切换以及为什么裸调大模型API在构建复杂Agent时力不从心。实践障碍提供一个清晰、可复现的路径从环境搭建、工具定义到Agent创建和运行让你亲手体验Agent的完整工作流程。工程障碍揭示Demo与生产级应用之间的巨大鸿沟并提供循环控制、错误处理、可观测性等关键工程问题的解决方案。选型障碍厘清LangChain与LangGraph的关系与定位帮助你在不同场景下做出合适的技术选型。读完本文你将不仅理解LangChain Agent的ReAct循环、四大核心组件等原理更能获得一份可以直接运行的代码并掌握评估和优化一个Agent的工程化思维。这不仅仅是入门更是为后续构建更复杂的Agent系统打下坚实基础。2. 基础概念与核心原理在深入代码之前我们必须先统一语言理解几个核心概念。很多人混淆了AI、大模型、Agent和框架之间的关系。大语言模型LLM这是整个系统的“大脑”。它负责理解自然语言指令、进行逻辑推理、生成文本输出。例如GPT-4、Claude、Qwen等。它很聪明但本质上是一个“对话者”——你问它答仅此而已。工具Tool这是Agent的“手”和“脚”。工具是任何可以执行具体操作的函数或接口例如调用一个天气API、执行一条数据库查询、运行一段Python代码、进行一次网络搜索。工具让LLM的能力从“说”扩展到了“做”。智能体Agent这是整个系统的“调度员”或“指挥官”。Agent本身不直接回答问题也不直接执行操作。它的核心职责是协调根据用户的目标和当前掌握的信息决定下一步该“思考”什么以及该调用哪个“工具”。Agent LLM大脑 工具集手脚 调度逻辑。框架Framework如LangChain是构建Agent的“脚手架”和“工具箱”。它提供了一套标准化的组件如工具定义接口、记忆管理、执行循环和最佳实践让你无需从零开始处理状态管理、循环控制、错误处理等繁琐的工程问题。那么Agent的核心工作机制是什么答案是ReActReasoning Acting循环。想象一下你让一个人类助理去查“北京明天是否适合户外活动”。他不会直接给你答案而是会经历一个思考-行动的过程推理Reasoning“要判断是否适合户外我需要知道明天的天气。”行动Acting打开天气APP或网站查询“北京明天天气”。观察Observation看到结果“明天北京晴25-30度紫外线强”。推理Reasoning“天气很好但紫外线强需要防晒。所以适合户外但要做好防护。”最终回答Final Answer“明天北京天气晴朗温度适宜非常适合户外活动但请注意防晒。”LangChain Agent自动化了这个过程。它将LLM的思考过程格式化为固定的文本模式如Thought: ... Action: ...并循环执行“推理-选择工具-执行工具-观察结果-再推理”的步骤直到任务完成。这个循环的自动化管理正是框架的核心价值所在。没有框架你需要自己处理循环逻辑、状态维护、上下文拼接、工具调用编排等一系列复杂问题。3. 环境准备与前置条件在开始动手之前请确保你的开发环境已经就绪。本文将使用Python作为开发语言这是目前LangChain生态最成熟的选择。操作系统Windows、macOS 或 Linux 均可。本文示例在 macOS/Linux 环境下测试通过Windows用户请注意命令行的细微差别。Python版本建议使用 Python 3.8 至 3.11 版本。LangChain新版本对Python 3.12的支持可能尚在完善中。你可以使用以下命令检查python --version # 或 python3 --version包管理工具我们使用pip进行包管理。建议先升级pip到最新版本并考虑使用虚拟环境如venv或conda来隔离项目依赖避免包冲突。# 创建虚拟环境可选但推荐 python -m venv langchain-env # 激活虚拟环境 # On macOS/Linux: source langchain-env/bin/activate # On Windows: # langchain-env\Scripts\activate # 升级pip pip install --upgrade pip核心依赖安装我们将安装三个核心包。pip install langchain openai tavily-pythonlangchain: 核心框架提供了构建Agent所需的所有基础组件。openai: OpenAI官方SDK用于调用GPT模型。如果你使用其他模型如通义千问、智谱GLM则需要安装对应的SDK。tavily-python: Tavily搜索API的客户端。Tavily是一个为AI优化过的搜索引擎返回结构化的摘要信息非常适合Agent使用。你需要在其官网注册并获取一个免费的API Key。获取API密钥OpenAI API Key: 访问 OpenAI平台 创建。Tavily API Key: 访问 Tavily官网 注册获取。请将这两个密钥妥善保存我们将在代码中用到。切勿将密钥直接硬编码在提交到公开仓库的代码中最佳实践是使用环境变量。# 在终端中设置环境变量临时 export OPENAI_API_KEY你的-openai-api-key export TAVILY_API_KEY你的-tavily-api-key # 在代码中可以通过os.environ获取 import os openai_api_key os.environ.get(OPENAI_API_KEY)环境准备就绪接下来我们进入最激动人心的部分——动手构建。4. 核心流程拆解构建你的第一个智能研究助手我们的目标是构建一个“智能研究助手”。用户向它提出一个问题它能自动决定是否需要搜索网络信息然后调用搜索工具获取资料最后综合信息给出一个完整的答案。这个流程完美体现了Agent的“自主决策”能力我们不需要写if question_about_X: then search(X)这样的硬编码逻辑而是告诉Agent“你有一个搜索工具”由它自己决定何时使用。4.1 第一步定义工具——给Agent装上“搜索引擎”工具是Agent与外部世界交互的桥梁。在LangChain中定义一个工具非常简单只需要使用tool装饰器。创建一个新的Python文件例如research_agent.py并开始编写代码。# research_agent.py import os from langchain.tools import tool from tavily import TavilyClient # 从环境变量读取API密钥 tavily_api_key os.environ.get(TAVILY_API_KEY) # 初始化Tavily客户端 tavily_client TavilyClient(api_keytavily_api_key) tool def web_search(query: str) - str: 一个用于搜索最新网络信息的工具。当用户的问题涉及需要查询实时或事实性信息时使用此工具。 参数: query (str): 搜索查询词例如“LangChain 1.0 新特性”。 返回: str: 搜索结果的文本摘要。 try: # 调用Tavily搜索API获取最相关的3条结果 search_result tavily_client.search(queryquery, max_results3) # 从结果中提取‘content’字段并拼接成字符串 contents [result.get(content, ) for result in search_result.get(results, [])] combined_content \n---\n.join(contents) return f根据网络搜索关于 {query} 的信息如下\n{combined_content} except Exception as e: # 工具层进行异常处理返回错误信息避免异常抛给Agent导致崩溃 return f搜索工具执行时出错{str(e)}。请尝试重新提问或更换查询词。关键点解析tool装饰器这是LangChain的魔法。它自动将普通Python函数注册为一个LangChain可识别的工具并利用函数文档字符串作为工具的描述。这个描述至关重要LLM会阅读它来决定是否以及如何使用这个工具。清晰的工具描述在文档字符串中我们明确说明了工具的用途“搜索最新网络信息”和适用场景“涉及需要查询实时或事实性信息时”。这相当于给LLM的“工具说明书”。健壮性处理在工具内部我们使用try-except捕获可能出现的网络超时、API限流等异常并返回一个友好的错误信息。永远不要让未处理的异常从工具中抛出因为Agent无法理解复杂的异常堆栈这会导致整个执行中断。结构化返回我们将多条搜索结果用\n---\n分隔使返回内容更清晰便于LLM阅读和理解。4.2 第二步创建Agent——组装大脑、工具和指令有了工具我们需要一个“大脑”LLM和一个“调度员”Agent来使用它。这里我们使用LangChain的高阶APIcreate_agent它封装了底层的复杂逻辑。# research_agent.py (续) from langchain.agents import create_agent from langchain_openai import ChatOpenAI # 从环境变量读取OpenAI API Key openai_api_key os.environ.get(OPENAI_API_KEY) # 1. 初始化LLM大脑 # 使用ChatOpenAI类指定模型为gpt-3.5-turbo性价比高或gpt-4能力更强 llm ChatOpenAI( modelgpt-3.5-turbo, # 或 gpt-4 api_keyopenai_api_key, temperature0.1 # 降低随机性使Agent行为更稳定、可预测 ) # 2. 定义系统提示词给Agent的“工作职责说明书” system_prompt 你是一个专业、严谨的研究助手。你的职责是尽最大努力为用户提供准确、全面的信息。 工作流程 1. 仔细分析用户的问题。 2. 如果问题涉及你不知道的、需要最新信息的、或需要事实核查的内容你必须使用web_search工具进行查询。 3. 根据搜索工具返回的结果结合你已有的知识组织一个清晰、有条理的回答。 4. 如果搜索结果与你的知识有冲突以可靠的搜索结果为准。 5. 在回答中可以引用搜索到的信息并保持客观中立。 记住当你没有把握时优先使用搜索工具。不要凭空捏造信息。 # 3. 创建Agent agent create_agent( modelllm, # 指定使用哪个LLM tools[web_search], # 赋予Agent可用的工具列表 system_promptsystem_prompt, # 设定Agent的角色和行为准则 max_iterations5 # 安全措施限制最大循环次数防止死循环 )关键点解析ChatOpenAI这是LangChain封装的与OpenAI Chat模型交互的类。temperature参数设置为较低值如0.1是为了让Agent的决策过程更稳定、更少“天马行空”这对于需要可靠性的任务很重要。系统提示词System Prompt这是控制Agent行为的最重要杠杆。我们在这里详细规定了Agent的角色、工作流程和原则。一个好的提示词能极大提升Agent的可靠性和效果。注意我们明确指令它“当你没有把握时优先使用搜索工具”。create_agent这个函数是LangChain 1.0的简化API。它背后实际上构建了一个基于LangGraph的ReAct执行循环。我们传入了模型、工具和提示词它就返回一个可以执行的Agent对象。max_iterations5是一个关键的安全设置强制Agent在5轮思考-行动循环后必须停止避免陷入无限循环。4.3 第三步运行与交互——让Agent开始工作Agent创建好后我们就可以向它提问了。LangChain Agent的输入输出通常围绕messages这个列表进行。# research_agent.py (续) def ask_agent(question: str): 向Agent提问并打印结果 print(f\n[用户提问]: {question}) print(- * 50) # 构造输入格式符合LangChain Agent的预期 input_messages [{role: user, content: question}] # 调用Agent try: # agent.invoke 是触发Agent执行的方法 result agent.invoke({messages: input_messages}) # 从结果中提取最后一条消息即Agent的最终回答 final_message result[messages][-1] print(f[助手回答]: {final_message.content}) except Exception as e: print(fAgent执行过程中出现错误: {e}) if __name__ __main__: # 测试几个问题 test_questions [ LangChain 1.0 版本主要带来了哪些新特性, Python 3.12 在性能上有哪些改进, 帮我总结一下机器学习中过拟合的概念。, ] for q in test_questions: ask_agent(q) print( * 70)关键点解析输入格式Agent期望的输入是一个字典其中包含一个messages列表列表中的每个元素是一个包含role如user,assistant,system和content的字典。这遵循了常见的Chat API格式。agent.invoke这是启动Agent执行的方法。它会触发内部的ReAct循环。输出提取invoke方法返回的结果是一个包含执行状态和消息历史的字典。我们通常取result[messages][-1]来获取Agent生成的最终回答。异常处理在调用层也进行try-except可以捕获网络、鉴权等更上层的错误。4.4 第四步运行你的第一个Agent在终端中确保已激活虚拟环境并设置好环境变量然后运行脚本python research_agent.py你将看到类似以下的输出具体内容因搜索实时结果和模型输出而异[用户提问]: LangChain 1.0 版本主要带来了哪些新特性 -------------------------------------------------- [助手回答]: 根据网络搜索LangChain 1.0 版本与 LangGraph 1.0 同步发布标志着框架进入稳定生产就绪阶段。其主要新特性包括 1. **统一的简化API**引入了 create_agent 等高阶函数大幅降低了构建基础Agent的代码复杂度。 2. **与LangGraph深度集成**核心执行引擎默认基于LangGraph提供了更强大、可观测的状态管理和工作流编排能力。 3. **改进的工具调用**对工具的描述、调用和错误处理进行了标准化和强化。 4. **增强的可观测性**与LangSmith的集成更紧密为调试和监控Agent工作流提供了更好的支持。 5. **模块化与稳定性**许多核心组件进行了重构提高了稳定性和性能为长期维护奠定了基础。 总的来说1.0版本的重点是从“实验性框架”转向“工程化平台”强调开发者体验和生产环境下的可靠性。 恭喜你的第一个AI Agent已经成功运行。它自动判断第一个问题需要搜索调用了web_search工具获取信息后给出了综合回答。对于第三个关于“过拟合”的概念性问题它可能直接利用内置知识进行回答而无需搜索。5. 深入原理ReAct循环与四大组件剖析通过上面的实践我们已经感受到了Agent的自动化能力。现在让我们深入LangChain内部看看create_agent背后究竟发生了什么。理解下图所示的ReAct循环和四大组件是掌握Agent开发的关键。用户输入任务 | v LLM推理: 思考下一步 | v 决策 / \ 需要工具 任务完成 | | v v 选择工具 生成参数 - 生成最终答案 | v 执行工具调用 | v 观察结果 (Observation) | v 循环回到LLM推理1. LLM大脑在每一轮循环中LLM接收当前的“状态”包含对话历史、之前的工具观察结果等并输出一个格式化的文本。这个文本必须遵循框架约定的格式例如Thought: 用户想了解LangChain 1.0的新特性这是一个需要最新信息的问题。 Action: web_search Action Input: LangChain 1.0 new features框架会解析这个输出提取出Action和Action Input。2. Agent调度员这是LangChain框架的核心逻辑。它负责解析LLM输出判断LLM是想调用工具Action还是直接回答Final Answer。管理循环根据解析结果决定是进入工具执行分支还是结束循环返回答案。维护状态将工具执行的结果Observation添加到对话历史中为下一轮LLM推理提供上下文。3. Tool工具箱当调度员解析出Action为web_search时它会找到我们之前用tool装饰的函数并将Action Input(“LangChain 1.0 new features”) 作为参数传入执行该函数。4. Memory记忆体在我们的简单示例中记忆是隐式的存在于循环传递的messages列表中。更复杂的场景下LangChain提供了短期记忆如ConversationBufferMemory和长期记忆如向量数据库来帮助Agent记住跨轮次甚至跨会话的信息。这个循环会一直持续直到LLM输出Final Answer:开头的文本或者达到max_iterations限制。6. 从Demo到生产必须面对的工程化挑战让一个Agent在笔记本里跑起来是一回事让它在你公司的服务器上7x24小时稳定运行是另一回事。以下是四个最常见的工程化挑战及其应对策略。6.1 挑战一循环失控与超时问题Agent可能陷入“思考-搜索-再思考-再搜索”的死循环或者因为某个工具响应慢而卡住。解决方案设置硬性限制如我们之前所做的max_iterations是必须的保险丝。超时控制为工具调用和整个Agent执行设置超时。设计更好的提示词在系统提示中明确要求Agent“在获得足够信息后应果断给出最终答案”。# 更健壮的Agent配置示例 from langchain.agents import create_react_agent # 另一种创建方式 from langchain.agents import AgentExecutor # 使用更低级别的API获得更多控制权 agent_executor AgentExecutor( agentagent, # 之前用create_agent创建的agent对象 toolstools, max_iterations5, max_execution_time30, # 整体最长执行时间30秒 early_stopping_methodgenerate, # 提前停止策略 handle_parsing_errorsTrue, # 处理LLM输出解析错误 verboseTrue # 打印详细执行日志用于调试 )6.2 挑战二工具调用失败问题网络波动、API限流、参数错误都可能导致工具调用失败。解决方案工具层容错如前所述在工具函数内部进行try-except返回错误信息而非抛出异常。重试机制为工具配置自动重试。LangChain的tool装饰器可以结合tenacity等重试库。后备方案设计降级逻辑例如当主要搜索API失败时切换至备用API或返回缓存数据。6.3 挑战三上下文管理与Token消耗问题每次循环都将全部历史对话和工具结果送入LLM几轮之后token数会急剧增长导致成本上升、速度变慢甚至超出模型上下文长度限制。解决方案摘要记忆使用ConversationSummaryMemory或ConversationSummaryBufferMemory将冗长的历史对话总结成一段摘要而非全部保留。向量记忆将重要的历史信息存入向量数据库在需要时进行相似性检索召回而不是全部送入上下文。LangGraph的状态管理对于复杂Agent使用LangGraph可以更精细地控制状态流转避免不必要的上下文重复。6.4 挑战四可观测性与调试问题Agent的决策过程是个黑盒出了问题很难排查。解决方案启用详细日志创建Agent时设置verboseTrue可以在控制台看到每一步的Thought,Action,Observation。使用LangSmith这是LangChain官方推出的可观测性平台。将你的Agent与LangSmith集成后可以在网页上可视化整个执行轨迹Trace查看每一轮LLM的输入输出、工具调用的参数和结果、token消耗等。这对于调试和优化至关重要。结构化日志将Agent的执行日志包括用户输入、最终输出、中间步骤、耗时、token数记录到你的ELK或类似系统中用于监控和告警。7. LangChain vs. LangGraph如何选择这是初学者最容易混淆的一点。从网络热词也能看出大家很关心它们的区别。LangChain是一个高级框架High-level Framework。它提供了大量开箱即用的组件Models, Prompts, Chains, Agents, Memory, Indexes等和简化API如create_agent。它的目标是让开发者快速构建常见的AI应用。你可以把它想象成“乐高套装”提供了很多预制好的模块。LangGraph是一个底层运行时和编排引擎Low-level Orchestration Engine。它基于有向图Graph的概念让你可以精确地定义和控制复杂的工作流Workflow其中包含循环、条件分支、多Agent协作等。它的目标是构建复杂、稳定、长时运行的生产级系统。你可以把它想象成“乐高底板和连接器”让你可以自由设计任何结构。关系与选型建议包含关系LangChain的高级组件如Agent其底层执行引擎就是LangGraph。当你调用create_agent时LangChain在后台为你创建了一个LangGraph图来运行ReAct循环。使用场景使用LangChain当你需要快速验证一个想法构建一个标准化的聊天机器人、检索增强生成RAG系统或简单Agent时。它上手快代码简洁。使用LangGraph当你需要构建一个具有复杂状态、自定义循环逻辑、多步骤审批、或需要与现有系统深度集成的工作流时。例如一个客户服务流程先由分类Agent分流再由专业Agent处理最后需要人工审核。简单类比LangChain像Django快速构建Web应用LangGraph像Celery定义和管理复杂的后台任务工作流。在实际项目中它们经常结合使用。8. 常见问题与排查思路在开发过程中你一定会遇到各种问题。下表总结了一些典型问题及其解决方法。问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named langchain依赖未安装或虚拟环境未激活。1. 运行pip list | grep langchain检查。2. 确认终端处于正确的虚拟环境中。1. 激活虚拟环境。2. 执行pip install langchain。AuthenticationError或Invalid API KeyAPI密钥未设置或错误。1. 检查环境变量名是否正确OPENAI_API_KEY,TAVILY_API_KEY。2. 在代码中打印os.environ.get(KEY)查看是否为空。1. 在终端正确设置环境变量。2. 前往对应平台检查API密钥是否有效、是否有余额。Agent一直循环不输出最终答案1. 提示词未引导其给出Final Answer。2. 工具返回结果格式让LLM困惑。3. 达到了max_iterations限制但未完成。1. 设置verboseTrue查看每轮输出。2. 检查LLM最后的Thought看它是否在等待更多信息。1. 强化系统提示词明确结束条件。2. 优化工具返回格式使其更清晰。3. 适当增加max_iterations或检查工具是否总能返回有效信息。Agent从不调用工具1. 工具描述不清晰LLM不理解其用途。2. 系统提示词未鼓励使用工具。3. LLM的temperature过低过于保守。1. 检查工具的文档字符串是否准确描述了功能和适用场景。2. 查看verbose日志看LLM的Thought是否考虑了工具。1. 重写工具描述使用更直白的语言。2. 在系统提示词中强调“当你需要最新或不确定的信息时务必使用搜索工具”。3. 微调temperature(如调到0.3)。工具调用报错TypeError工具函数的参数定义与LLM生成的Action Input不匹配。1. 查看verbose日志中的Action Input内容。2. 检查tool装饰函数的参数类型。1. 确保工具函数参数是简单的字符串str类型LLM最容易生成。2. 在工具函数内部对输入进行清洗和类型转换。响应速度非常慢1. 网络问题。2. LLM模型较大如GPT-4。3. 上下文过长导致模型处理慢。1. 检查网络连接。2. 使用time模块记录各步骤耗时。3. 查看每次请求的token数量。1. 对于简单任务可换用更快/更便宜的模型如gpt-3.5-turbo。2. 实现记忆摘要功能压缩上下文。3. 为工具调用设置超时。9. 最佳实践与下一步探索方向构建一个稳定的Agent系统除了解决上述问题还需要遵循一些最佳实践提示词工程化将系统提示词和维护指令从代码中分离出来存放在配置文件或数据库中。便于迭代优化和A/B测试。工具设计的原子性每个工具应只做一件事并做好它。避免设计功能过于复杂、容易失败的工具。复杂的操作可以通过多个Agent协作或工作流来分解。测试与评估为你的Agent建立测试集。不仅测试最终答案的准确性还要测试其决策过程如是否在应该调用工具时调用了。考虑使用LangSmith的测试功能。成本与性能监控记录每次调用的token消耗、耗时和费用。设置告警防止意外的高消耗。人的参与Human-in-the-loop对于关键任务设计审批节点。当Agent置信度低或触及敏感操作时应能暂停并请求人工确认。你的探索不应止步于此。基于这个“智能研究助手”你可以尝试增加更多工具如计算器 (llm-math)、维基百科查询 (wikipedia)、代码执行等。引入记忆使用ConversationBufferWindowMemory让Agent记住最近几轮对话。尝试多Agent协作使用LangGraph创建两个Agent一个负责研究一个负责总结润色。接入实际业务将工具替换为查询公司数据库、调用内部API、发送邮件通知等打造真正的业务自动化助手。AI Agent的开发是一场关于“如何将不确定性封装成确定性服务”的工程实践。LangChain等框架提供的正是将LLM的“智能”与软件的“可靠”结合起来的桥梁。从今天开始不再只是谈论Agent动手去构建、去调试、去观察它如何工作。你遇到的每一个错误都是理解这个新范式的最佳入口。