30款热门AI模型一站整合DeepSeek/GLM/Claude 随心用限时 5 折。 点击领海量免费额度这次我们来看一个能让你从“只会喊AI Agent”到“自己动手造一个”的实战项目。LangChain这个在AI应用开发领域绕不开的框架到底怎么用它的核心机制ReAct循环是什么更重要的是如何用几行代码快速搭建一个能自主搜索、思考并回答问题的智能研究助手这篇文章不讲空泛的概念直接带你从环境搭建、代码编写到工程落地完整走一遍构建AI Agent的流程。如果你关心如何将大模型从“聊天窗口”变成“能干活”的智能体想知道LangChain和LangGraph的区别以及如何避免Agent在循环中“跑飞”那么这篇文章就是为你准备的。1. 核心能力速览在深入代码之前我们先快速了解LangChain Agent的核心能力和定位这决定了它适合解决什么问题以及你需要准备什么。能力项说明项目类型AI应用开发框架专注于构建基于大语言模型LLM的智能体Agent。核心机制ReAct循环Reasoning Acting实现推理与行动的交替执行是Agent自主决策的基石。主要功能1.工具调用将API、数据库、代码等封装为Agent可用的工具。2.状态管理通过Memory管理对话历史和任务状态。3.工作流编排支持复杂、多步骤的长时任务Long-Horizon Tasks。4.可观测性与LangSmith集成追踪Agent的每一步决策和工具调用。硬件门槛无特定GPU要求。Agent的核心是逻辑编排推理能力依赖底层LLM。使用云端API如OpenAI则对本地硬件无要求若本地部署大模型则需相应GPU资源。启动方式通过Python包安装以代码库形式集成到你的应用中并非独立的桌面应用或服务。是否支持API本身是开发框架用于构建提供API的服务。可轻松与FastAPI、Flask等Web框架结合对外提供Agent服务接口。是否支持批量任务支持。可以通过脚本并发调用或多个Agent实例来处理批量任务但需要自行管理任务队列和状态隔离。适合场景快速构建智能助手、自动化研究、客服机器人、内部流程自动化等需要LLM自主调用工具完成任务的场景。关键版本LangChain与LangGraph已同步发布1.0版本分别侧重开箱即用和底层运行时控制。2. 适用场景与使用边界理解一个工具的边界和知道它能做什么同样重要。LangChain Agent 最适合这些场景信息检索与整合如智能研究助手自动搜索网络信息并总结。自动化流程根据自然语言指令自动执行一系列操作如发送邮件、查询数据库、生成报告。决策支持系统在特定规则和工具辅助下提供分析建议例如基于天气数据建议出行方案。复杂对话系统超越简单问答能记住上下文、调用知识库、执行操作的多轮对话机器人。需要谨慎或不适用的场景简单单轮问答如果只是简单的“输入-输出”直接调用大模型API更简单高效。对确定性要求极高的场景Agent的决策路径具有一定非确定性不适合金融交易、工业控制等要求100%确定性的环节。无工具调用的纯文本生成如写小说、润色文案单独使用LLM或LangChain的Chain可能更合适。资源极度受限的环境ReAct循环会产生多次LLM调用Token消耗和延迟比单次调用高。合规与安全边界工具权限Agent能调用你赋予它的任何工具。务必严格审查工具权限避免赋予其删除文件、发送敏感信息等高危操作权限。内容审核对Agent生成的内容特别是涉及对外发布或交互的应建立审核机制。数据隐私确保通过Agent工具查询和处理的数据符合隐私法规避免泄露敏感信息。依赖管理Agent的稳定性依赖于底层LLM和各类工具API的稳定性需要设计降级和熔断策略。3. 环境准备与前置条件开始动手前确保你的环境已经就绪。基础软件环境操作系统Windows 10/11, macOS, 或 Linux (如Ubuntu 20.04)均可。本文以通用命令为主。Python版本 3.8 至 3.11。推荐使用 3.10 以获得最佳兼容性。使用python --version检查。包管理工具pip已安装并更新至最新版。网络与API准备科学上网环境可选但推荐用于稳定访问OpenAI API、下载Python包。请自行确保开发环境的网络合规性与稳定性。API密钥OpenAI API Key我们将使用GPT-4作为Agent的“大脑”。你需要一个有效的OpenAI账户并获取API密钥。Tavily API Key (可选)为了演示工具调用我们会使用Tavily这个AI专用搜索引擎。你可以去其官网注册免费获取API额度。开发环境建议代码编辑器VS Code、PyCharm等均可。虚拟环境强烈建议使用venv或conda创建独立的Python环境避免包冲突。# 创建虚拟环境 python -m venv langchain-env # 激活虚拟环境 # Windows: langchain-env\Scripts\activate # macOS/Linux: source langchain-env/bin/activate4. 安装部署与启动方式LangChain的“启动”就是安装包并导入你的代码中。第一步安装核心库在激活的虚拟环境中运行以下命令安装必要依赖pip install langchain langchain-openai langchain-communitylangchain: 核心框架。langchain-openai: 官方维护的OpenAI集成。langchain-community: 社区贡献的大量第三方工具和集成。第二步安装可选工具库为了接下来的实战我们安装一个搜索工具库pip install tavily-python第三步验证安装创建一个简单的Python脚本test_import.py来验证import langchain import langchain_openai print(fLangChain version: {langchain.__version__}) print(All packages imported successfully!)运行python test_import.py如果没有报错说明环境配置成功。这不是一个“一键启动”的桌面软件而是一个需要你编写代码来“组装”和“启动”Agent的框架。5. 功能测试与效果验证构建你的第一个智能研究助手理论说再多不如跑通一行代码。我们现在就构建一个能自动联网搜索并回答问题的智能研究助手。5.1 测试目标创建一个具备web_search工具的Agent当用户提出一个需要最新信息的问题时它能自动调用搜索工具获取信息并整合成最终答案。5.2 代码实现与分步解析步骤1导入库并设置API密钥创建一个名为research_agent.py的新文件。import os from langchain.agents import create_agent from langchain.tools import tool from langchain_openai import ChatOpenAI from tavily import TavilyClient # 请替换为你自己的API密钥 os.environ[OPENAI_API_KEY] sk-your-openai-api-key-here os.environ[TAVILY_API_KEY] tvly-your-tavily-api-key-here # 初始化Tavily客户端 tavily_client TavilyClient(api_keyos.environ[TAVILY_API_KEY])步骤2定义工具Tool工具是Agent的手臂。我们用tool装饰器将一个普通Python函数转化为LangChain能识别的工具。tool def web_search(query: str) - str: 一个用于搜索最新网络信息的工具。输入是一个搜索查询字符串返回是搜索结果的摘要文本。 try: # 调用Tavily搜索API获取前3条结果 search_result tavily_client.search(queryquery, max_results3) # 从结果中提取内容字段并用换行符连接 contents [result[content] for result in search_result.get(results, [])] return \n\n.join(contents) if contents else 未找到相关信息。 except Exception as e: return f搜索工具执行出错: {str(e)}关键点tool装饰器和文档字符串...至关重要LangChain会利用它们来让LLM理解这个工具的功能。步骤3创建Agent使用LangChain提供的create_agent函数这是最快捷的构建方式。# 初始化LLM这里使用gpt-4你也可以换成gpt-3.5-turbo llm ChatOpenAI(modelgpt-4, temperature0) # 创建Agent传入模型、工具列表和系统提示词 agent create_agent( modelllm, tools[web_search], # 将我们定义的工具传入 system_prompt你是一个专业的研究助手。当用户提问时你应该优先考虑使用搜索工具获取最新、最准确的信息然后基于信息进行总结和回答。如果你已经拥有足够的知识来回答也可以直接回答。, )关键点system_prompt用于设定Agent的角色和行为准则引导其决策逻辑。步骤4运行Agent并提问现在让我们向Agent提一个需要最新信息的问题。# 定义用户问题 question LangChain 1.0 和 LangGraph 1.0 的主要区别是什么它们分别适用于什么场景 # 调用Agent。输入格式需符合LangChain消息格式。 response agent.invoke({ messages: [{role: user, content: question}] }) # 打印Agent的最终回答 final_answer response[messages][-1].content print(*50) print(用户问题, question) print(*50) print(助手回答\n, final_answer) print(*50)5.3 运行与效果验证在终端运行脚本python research_agent.py预期成功结果脚本开始运行没有报错。你会看到程序有短暂的停顿正在调用OpenAI和Tavily API。终端最终会打印出类似以下的结构化回答 用户问题 LangChain 1.0 和 LangGraph 1.0 的主要区别是什么它们分别适用于什么场景 助手回答 根据搜索得到的信息LangChain 1.0 和 LangGraph 1.0 虽然同期发布但定位不同 **LangChain 1.0** 侧重于**开箱即用**和**开发者体验**。它提供了高级别的抽象和封装让开发者能够通过简单的函数调用如create_agent快速构建起一个可工作的智能体。它适合标准化场景和快速原型验证。 **LangGraph 1.0** 则更侧重于**底层运行时控制**和**复杂状态管理**。它暴露了更多的底层节点、边和状态控制接口允许开发者精细地定义工作流的每一个步骤和状态转换。它适用于需要构建复杂、长时运行、有严格状态管理需求的生产级智能体应用。 **简单比喻**LangChain 像是组装好的智能家电如咖啡机按按钮就能用LangGraph 像是给你提供了电机、水泵、加热模块让你可以自己设计一台符合特殊需求的咖啡机。 **适用场景** - 如果你想快速验证一个Agent想法或构建一个相对标准的助手选择 **LangChain**。 - 如果你需要构建一个涉及多步骤审批、复杂业务逻辑编排、或需要持久化中断/恢复状态的企业级工作流选择 **LangGraph**。 实际上两者常结合使用例如LangChain的create_agent其底层运行时就是由LangGraph驱动的。 成功标准Agent自动识别出问题需要最新信息成功调用了web_search工具并将搜索结果整合成了有条理、有洞察的回答。这证明了ReAct循环在工作思考(需要搜索) - 行动(调用搜索工具) - 观察(获取结果) - 思考(整合信息) - 最终回答。5.4 常见失败原因排查ModuleNotFoundError: 检查是否在正确的虚拟环境中以及pip install是否成功。OpenAI API认证错误检查OPENAI_API_KEY环境变量或代码中的密钥是否正确是否有余额。Tavily API错误同样检查密钥并确认网络能访问其服务。Agent陷入循环或无响应可能是初始system_prompt引导不足或工具返回内容格式让LLM困惑。可以尝试增加max_iterations参数限制循环次数。agent create_agent( modelllm, tools[web_search], system_prompt..., max_iterations5 # 防止无限循环 )6. 接口API与批量任务让Agent在本地脚本运行只是第一步。要集成到应用中需要将其服务化。6.1 使用FastAPI封装Agent为HTTP服务我们将上面的研究助手封装成一个简单的Web API。安装FastAPI和Uvicornpip install fastapi uvicorn创建agent_api.pyfrom fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import List import asyncio # 导入之前写好的Agent创建逻辑 from research_agent import agent # 假设之前的agent对象可以通过导入使用 # 注意实际项目中应将agent的初始化逻辑封装成函数避免全局状态问题。 app FastAPI(title智能研究助手API) class AgentRequest(BaseModel): API请求体模型 message: str conversation_id: str None # 可选用于支持多轮对话 class AgentResponse(BaseModel): API响应体模型 answer: str conversation_id: str None app.post(/chat, response_modelAgentResponse) async def chat_with_agent(request: AgentRequest): 与智能研究助手对话的端点。 try: # 调用Agent。注意agent.invoke在异步环境中可能需要特殊处理。 # 这里为简化使用同步调用。生产环境应考虑使用LangChain的异步接口或线程池。 loop asyncio.get_event_loop() response await loop.run_in_executor( None, lambda: agent.invoke({ messages: [{role: user, content: request.message}] }) ) final_answer response[messages][-1].content return AgentResponse(answerfinal_answer, conversation_idrequest.conversation_id) except Exception as e: raise HTTPException(status_code500, detailfAgent处理失败: {str(e)}) if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)启动服务python agent_api.py服务将在http://127.0.0.1:8000启动。访问http://127.0.0.1:8000/docs可以看到自动生成的交互式API文档。使用curl测试APIcurl -X POST http://127.0.0.1:8000/chat \ -H Content-Type: application/json \ -d {message: FastAPI的最新版本有什么特性}6.2 批量任务处理Agent本身不直接管理队列但可以轻松集成到批量处理流程中。示例使用线程池处理一批问题import concurrent.futures from research_agent import agent # 导入之前创建的agent questions [ 什么是RAG, 机器学习中过拟合如何解决, Python的GIL是什么, ] def ask_agent(q): 包装Agent调用的函数 try: response agent.invoke({messages: [{role: user, content: q}]}) return q, response[messages][-1].content, None except Exception as e: return q, None, str(e) # 使用线程池并发执行注意API速率限制 with concurrent.futures.ThreadPoolExecutor(max_workers3) as executor: future_to_question {executor.submit(ask_agent, q): q for q in questions} for future in concurrent.futures.as_completed(future_to_question): question future_to_question[future] try: q, answer, error future.result() if error: print(f问题 {q} 处理失败: {error}) else: print(fQ: {q}\nA: {answer[:200]}...\n{-*40}) except Exception as exc: print(f问题 {question} 生成了异常: {exc})批量任务建议速率限制如果使用付费API如OpenAI务必控制并发请求速率避免超额费用。错误处理与重试网络和API调用可能失败必须实现重试机制和健壮的错误处理。状态隔离确保每个批量任务使用独立的Agent实例或会话避免状态污染。结果持久化将问题和答案及时保存到数据库或文件防止丢失。7. 资源占用与性能观察LangChain Agent作为编排框架其资源消耗主要来自两部分LLM调用和工具执行。1. LLM调用主要成本与延迟来源Token消耗ReAct循环每次迭代都会产生新的LLM调用消耗输入和输出的Token。一个简单的“搜索-回答”任务Token消耗可能是单轮问答的2-3倍。观察方法使用OpenAI API的响应头或LangSmith可以查看每次调用的Token使用详情。优化建议使用更高效的提示词减少不必要的上下文。为工具返回结果设置长度限制避免过长的内容挤占上下文窗口。考虑使用更经济或更快的模型如gpt-3.5-turbo进行初步决策。2. 工具执行网络I/O如果工具是调用外部API如搜索、数据库网络延迟是主要性能瓶颈。优化建议为工具调用设置合理的超时时间。对可缓存的工具结果进行缓存例如使用tool装饰器的args_schema配合缓存库。异步调用工具如果支持。3. 内存与CPULangChain框架本身内存占用很小。主要内存消耗在于加载的模型如果本地部署和运行时的Python对象。CPU消耗通常不是瓶颈除非工具涉及大量本地计算。性能监控关键点循环迭代次数通过max_iterations限制并监控平均迭代次数异常增多可能提示提示词或工具设计有问题。工具调用成功率监控每个工具的调用失败率。端到端延迟从用户提问到收到最终回答的总时间。使用LangSmith这是LangChain官方的可观测性平台可以可视化追踪整个Agent执行的完整轨迹Trace包括每一步的Thought、Action、Observation是调试和优化性能的利器。8. 常见问题与排查方法在开发和运行Agent过程中你肯定会遇到各种问题。下表列出了典型问题及解决思路。问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named langchain未安装LangChain包或不在正确的Python环境中。在终端执行 pip listgrep langchain。OpenAI API报错 (AuthenticationError,RateLimitError)API密钥错误、过期、余额不足或达到速率限制。检查环境变量OPENAI_API_KEY登录OpenAI平台查看用量和余额。更换正确的密钥充值降低请求频率或升级套餐。Agent对简单问题也调用工具响应慢系统提示词 (system_prompt) 可能过度强调使用工具。检查system_prompt内容。在LangSmith中查看Agent的思考过程。调整提示词明确告知“如果知识库中已有信息可直接回答”。Agent陷入循环不停调用工具1. 工具返回结果未能满足LLM的终止条件。2. 缺少循环次数限制。查看LangSmith Trace观察每次Observation后Thought是否合理。1. 优化工具返回信息的质量和格式。2. 在create_agent中设置max_iterations参数如max_iterations5。工具调用失败Agent卡住或报错工具函数本身抛出异常如网络错误、API格式变化。在工具函数内部添加详细的try-except和日志。在工具函数中实现健壮的错误处理返回明确的错误信息给Agent而不是抛出异常。上下文长度超限错误多轮对话或工具返回内容过长导致总Token数超过模型限制。计算输入Token数。使用LangSmith查看上下文构建情况。1. 使用具有更长上下文窗口的模型。2. 使用ConversationSummaryMemory等记忆组件来压缩历史。3. 限制工具返回内容的长度。Agent的决策不符合预期提示词不够清晰或工具描述 (docstring) 不准确。通过LangSmith仔细分析每次推理 (Thought) 的依据。迭代优化system_prompt和工具的文档字符串使其对LLM的指导更明确。create_agent函数找不到LangChain版本过旧。执行pip show langchain查看版本。升级到最新版本pip install -U langchain。1.0版本后推荐使用此高阶函数。9. 最佳实践与使用建议为了让你的Agent项目从玩具走向生产请遵循以下建议从简单开始逐步复杂化先用一个工具、一个明确的提示词构建最小可行AgentMVA。跑通后再逐步增加工具复杂度、优化提示词。提示词工程是核心Agent的行为极大程度由system_prompt和工具描述决定。花时间精心设计它们明确Agent的角色、目标和约束例如“你必须先使用搜索工具”。必须实施可观测性在开发阶段就集成LangSmith。它是你理解Agent“脑子里在想什么”的唯一窗口能极大提升调试效率。为工具调用添加护栏输入验证在工具函数内部验证参数防止非法输入。输出过滤对工具返回的内容进行清洗或截断避免垃圾信息进入上下文。异常处理工具必须捕获所有异常并返回对LLM友好的错误信息而不是崩溃。管理上下文长度对于长对话使用ConversationBufferWindowMemory或ConversationSummaryMemory来避免历史消息无限增长。区分开发和生产配置开发使用max_iterations10开启详细日志和LangSmith追踪。生产设置更严格的max_iterations如5关闭调试日志使用异步调用提高吞吐并实施API速率限制和熔断。安全与合规前置权限最小化只授予Agent完成目标所必需的最小权限。内容过滤对用户输入和Agent输出考虑添加内容安全过滤层。审计日志记录所有用户交互、工具调用和决策轨迹以满足合规要求。10. 总结与下一步通过本文的实战你已经完成了从零构建一个功能完整的AI Agent的关键步骤理解了ReAct循环的核心机制用create_agent快速组装了一个智能研究助手并将其封装成了API服务。最重要的是你接触到了Agent开发中最实际的问题——工具定义、提示词编写、循环控制和错误处理。最值得尝试的下一步增加更多工具尝试集成数据库查询、计算器、文件读写、发送邮件等工具打造更强大的个人助理。探索LangGraph当你需要更精细地控制工作流如并行执行、条件分支、人工审核节点时是时候学习LangGraph了。用它来构建一个多Agent协作的复杂流程。集成本地模型将OpenAI API替换为本地部署的Ollama运行Llama 3、Qwen等、vLLM或Xinference服务实现完全自主可控。深入RAG检索增强生成将Agent与你自己的知识库文档、数据库结合打造专属领域的专家系统。这将是另一个能力飞跃。最容易踩的坑提醒不要忽视提示词一个模糊的提示词会让Agent行为失控。持续迭代和测试你的提示词。一定要设max_iterations这是防止无限循环和API费用爆表的安全绳。工具要健壮脆弱的工具是Agent系统中最常见的故障点。做好错误处理和超时管理。AI Agent的开发是一个“设计系统”而非“编写脚本”的过程。你的角色从编写每一步逻辑的工程师转变为定义目标、提供工具和设定规则的“管理者”。现在你已经拿到了入场券。建议收藏本文在动手实践中反复查阅祝你构建出第一个真正能替你“干活”的智能体。 30款热门AI模型一站整合DeepSeek/GLM/Claude 随心用限时 5 折。 点击领海量免费额度