30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度这次我们来看一个能让你从“喊口号”到“真动手”的AI Agent开发项目。如果你对AI Agent的概念已经听腻了但一提到自己动手写代码就犯怵那这篇文章就是为你准备的。我们将聚焦于LangChain这个目前最流行的AI应用开发框架通过一个完整的实战案例带你理解AI Agent的核心工作机制并亲手构建一个能自主搜索、思考并回答问题的智能研究助手。LangChain不是一个新概念但它的1.0版本标志着AI应用开发从“对话”到“行动”的范式切换。它不再仅仅是把大模型API包装一下而是提供了一套完整的框架来处理复杂的、多步骤的、需要自主决策的任务。简单说它帮你把大模型从一个“聊天高手”变成一个“能干活”的数字员工。本文将重点拆解LangChain Agent的核心机制——ReAct循环并通过一个“智能研究助手”的实例让你在十分钟内跑通第一个Agent。我们会关注环境搭建、代码实现、工程化落地中的常见坑点以及如何判断你的Agent是否真的“好用”。1. 核心能力速览在深入代码之前我们先快速了解LangChain Agent能做什么以及你需要准备什么。能力项说明项目类型AI Agent 开发框架 (Python库)核心功能构建具备自主推理和工具调用能力的智能体Agent实现多步骤任务自动化。核心机制ReAct (Reasoning Acting) 循环让LLM自主决定何时调用何种工具并基于结果进行下一步推理。关键组件LLM (大脑)理解任务、决策。Agent (调度员)决定行动步骤。Tools (工具箱)执行具体操作搜索、计算、API调用等。Memory (记忆体)管理对话状态和历史。硬件门槛无特殊要求。框架本身是Python库计算负载取决于你集成的LLM如OpenAI API调用无需本地GPU使用本地模型则需相应资源。启动/运行方式通过Python脚本或Jupyter Notebook运行可轻松集成到Web服务如FastAPI中。是否支持API是。Agent本身可作为服务暴露API也支持调用外部API作为工具。是否支持批量任务是。可通过脚本或任务队列如Celery轻松实现批量处理。适合场景1.自动化研究自动搜索、汇总信息。2.智能客服结合知识库和业务API回答问题。3.数据查询与分析连接数据库执行复杂查询并解释结果。4.工作流自动化编排多个步骤如生成报告、发送邮件、更新工单。2. 适用场景与使用边界LangChain Agent非常适合那些规则模糊、需要多步骤决策和信息整合的任务。它把“怎么做”的决策权交给了模型你只需要定义“有什么工具”和“目标是什么”。它擅长解决以下问题信息整合型任务例如“帮我研究一下LangChain 1.0的新特性并总结成一份要点文档”。Agent可以自动调用搜索工具获取信息然后调用文本总结工具生成报告。流程决策型任务例如“监控服务器日志如果发现错误关键词‘OutOfMemory’则查询最近部署记录并给运维团队发一封告警邮件”。Agent需要判断条件、选择工具、执行动作。交互式对话增强在聊天机器人中根据用户问题动态决定是查数据库、调用计算API还是进行常规对话。它不擅长或需要谨慎处理的场景对确定性要求极高的任务Agent的决策路径是非确定性的同一问题在不同时间可能走不同路径。对于要求输出100%一致、零误差的场景如金融交易核心逻辑需设计严格的校验和兜底机制。简单单步任务如果任务只是“调用一次API并返回结果”直接写函数调用更简单高效引入Agent反而增加了复杂度。安全与合规边界Agent可以调用任何你赋予它的工具。必须严格限制其工具权限避免其执行危险操作如删除文件、发送未经审核的信息。所有涉及用户隐私、版权素材、敏感数据的处理都必须在前置环节做好授权验证和内容过滤。3. 环境准备与前置条件开始构建你的第一个Agent之前确保你的开发环境已经就绪。操作系统Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04) 均可。本文以通用命令行操作为例。Python 版本推荐使用 Python 3.8 至 3.11 版本。避免使用过新或过旧的版本以免遇到依赖兼容性问题。包管理工具使用pip进行包安装。建议先升级pip。python -m pip install --upgrade pip网络环境由于需要安装Python包并可能调用OpenAI等在线API请确保网络通畅。API密钥可选但推荐为了体验完整的工具调用我们后续示例会使用一个搜索工具它需要Tavily的API Key。你可以去 Tavily官网 免费注册获取。同时如果你打算使用OpenAI的模型也需要准备OpenAI API Key。4. 安装部署与启动方式LangChain的“启动”就是安装Python包并运行你的脚本。它没有常驻的“服务”需要启动其运行态就是你的Python进程。第一步创建虚拟环境强烈推荐为了避免包冲突建议使用虚拟环境。# 创建虚拟环境 python -m venv langchain-env # 激活虚拟环境 # Windows (PowerShell) .\langchain-env\Scripts\Activate.ps1 # Windows (CMD) .\langchain-env\Scripts\activate.bat # macOS/Linux source langchain-env/bin/activate第二步安装核心依赖我们将安装LangChain的核心库、OpenAI库用于调用GPT模型以及Tavily库用于搜索工具。pip install langchain langchain-openai tavily-pythonlangchain: LangChain核心框架。langchain-openai: OpenAI模型与LangChain的集成。tavily-python: 一个为AI优化的搜索引擎API客户端非常适合作为Agent的工具。第三步准备API密钥在代码中我们需要设置API密钥。一种安全的方式是使用环境变量。# 在命令行中设置临时关闭终端后失效 # Windows (PowerShell) $env:TAVILY_API_KEYyour_tavily_api_key_here $env:OPENAI_API_KEYyour_openai_api_key_here # macOS/Linux export TAVILY_API_KEYyour_tavily_api_key_here export OPENAI_API_KEYyour_openai_api_key_here更推荐的做法是创建一个.env文件来管理密钥并使用python-dotenv加载。这里为了简化我们先在代码中直接设置仅用于测试生产环境切勿硬编码。5. 功能测试与效果验证构建智能研究助手现在我们来动手构建并测试一个“智能研究助手”Agent。它的功能是当你提出一个需要研究的问题时它能自动调用搜索工具查找信息并整理出答案。5.1 定义工具让Agent有“手”可用工具Tool是Agent与外部世界交互的桥梁。我们先定义一个网络搜索工具。创建一个名为research_agent.py的文件写入以下代码# research_agent.py import os from langchain.tools import tool from tavily import TavilyClient from langchain_openai import ChatOpenAI from langchain.agents import create_agent # 注意在实际项目中请使用环境变量或配置文件管理API密钥不要硬编码。 os.environ[TAVILY_API_KEY] 你的Tavily API Key os.environ[OPENAI_API_KEY] 你的OpenAI API Key # 初始化Tavily客户端 tavily_client TavilyClient(api_keyos.environ[TAVILY_API_KEY]) # 使用 tool 装饰器定义一个工具 tool def web_search(query: str) - str: 使用Tavily搜索引擎进行网络搜索。 输入搜索查询词字符串。 输出搜索结果的摘要文本字符串。 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: # 工具调用失败时返回错误信息Agent可以处理 return f搜索工具调用失败{str(e)} # 测试工具是否正常工作 if __name__ __main__: # 简单测试工具函数 test_result web_search.invoke(LangChain是什么) print(工具测试结果前500字符:, test_result[:500])运行这个脚本测试工具是否能返回搜索结果python research_agent.py如果看到返回了关于“LangChain”的搜索结果文本说明工具定义成功且API密钥有效。5.2 创建Agent组装大脑和工具箱接下来我们创建LLM模型实例并将工具装配给Agent。在research_agent.py文件中继续添加以下代码接在工具定义之后# 创建LLM实例这里使用OpenAI的gpt-3.5-turbo模型成本较低适合测试 # 如果你想使用gpt-4将模型名改为gpt-4 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 创建Agent # create_agent 是LangChain 1.0中一个高级的、开箱即用的创建方法 agent create_agent( modelllm, # 指定使用哪个LLM作为“大脑” tools[web_search], # 将我们定义的搜索工具放入“工具箱” system_prompt你是一个专业的研究助手。当用户提问时你应该优先考虑使用搜索工具获取最新、最准确的信息然后基于这些信息给出清晰、有条理的回答。如果搜索不到相关信息请如实告知。, # 系统提示词指导Agent的行为 max_iterations5 # 安全限制最多进行5轮思考-行动循环防止无限循环 ) print(智能研究助手Agent创建成功)5.3 运行与验证看Agent如何工作现在让我们向Agent提问观察它完整的ReAct循环过程。在research_agent.py文件中继续添加运行代码# 定义一个研究问题 research_question LangChain 1.0 版本相比于之前的主要改进有哪些 print(f\n用户提问{research_question}) print(*50) print(Agent开始思考并执行...\n) # 调用Agent。输入格式需符合LangChain的Message格式。 try: response agent.invoke({ messages: [{role: user, content: research_question}] }) # 从响应中提取最终的答案 final_answer response[messages][-1].content print(\n *50) print(Agent最终答案) print(final_answer) except Exception as e: print(f\nAgent运行出错{e})保存文件并运行整个脚本python research_agent.py预期结果与过程观察启动脚本会先测试工具然后创建Agent。运行当你看到“Agent开始思考并执行...”后程序会稍有停顿。此时背后发生了以下几步虽然控制台默认不显示但你可以通过配置LangSmith来观察第一轮思考LLM大脑看到问题根据系统提示判断“用户问的是版本特性我需要最新信息应该使用搜索工具。”第一轮行动Agent调度员调用web_search工具参数为“LangChain 1.0 版本改进”。观察结果工具返回搜索到的文本。第二轮思考LLM收到搜索结果分析信息判断“信息已经足够可以组织答案了。”最终回答LLM生成最终答案循环终止。输出你将在控制台看到Agent整理出的关于LangChain 1.0新特性的答案。成功标准脚本无报错正常执行完毕。控制台输出了包含LangChain 1.0相关信息的文本段落。关键验证点答案中的信息例如提到LangGraph、Agent Harness等明显来自于网络搜索而不是模型固有的知识因为GPT-3.5的知识截止日期早于2025年10月。这证明Agent确实成功调用了工具。6. 接口API与批量任务将Agent封装成API服务或处理批量任务是工程化落地的关键。6.1 将Agent封装为FastAPI服务我们可以用FastAPI快速创建一个HTTP接口让其他应用能调用我们的研究助手。创建一个新文件agent_api.py# agent_api.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from research_agent import agent, llm, web_search # 导入之前定义的组件 import asyncio from typing import List, Optional app FastAPI(title智能研究助手API) class QuestionRequest(BaseModel): 请求体模型 question: str max_iterations: Optional[int] 5 # 允许客户端覆盖最大循环次数 class QuestionResponse(BaseModel): 响应体模型 answer: str status: str app.post(/research, response_modelQuestionResponse) async def research_question(request: QuestionRequest): 研究问题接口。 接收一个问题返回Agent研究后的答案。 try: # 注意为了演示这里每次调用都重新创建了一个带参数的Agent。 # 在生产环境中可以考虑Agent池或更高效的方式。 current_agent create_agent( modelllm, tools[web_search], system_prompt你是一个专业的研究助手。, max_iterationsrequest.max_iterations ) # 调用Agent。使用asyncio.to_thread避免阻塞事件循环。 result await asyncio.to_thread( current_agent.invoke, {messages: [{role: user, content: request.question}]} ) answer result[messages][-1].content return QuestionResponse(answeranswer, statussuccess) except Exception as e: raise HTTPException(status_code500, detailfAgent处理失败: {str(e)}) if __name__ __main__: import uvicorn # 启动服务监听本地7860端口 uvicorn.run(app, host127.0.0.1, port7860)安装FastAPI和Uvicornpip install fastapi uvicorn启动API服务python agent_api.py服务启动后访问http://127.0.0.1:7860/docs可以看到自动生成的API文档。你可以直接在浏览器中测试/research接口。使用curl命令测试curl -X POST http://127.0.0.1:7860/research \ -H Content-Type: application/json \ -d {question: 什么是LangGraph它和LangChain有什么区别}6.2 处理批量研究任务对于需要处理多个问题的场景我们可以编写一个简单的批量脚本。创建batch_research.py# batch_research.py import asyncio import aiohttp import json from typing import List from research_agent import agent, llm, web_search from langchain.agents import create_agent async def research_one_question(question: str, session: aiohttp.ClientSession None): 处理单个研究问题 try: # 为每个任务创建独立的Agent实例或使用线程安全的客户端 task_agent create_agent( modelllm, tools[web_search], system_prompt你是一个专业的研究助手。, max_iterations5 ) result task_agent.invoke( {messages: [{role: user, content: question}]} ) answer result[messages][-1].content return {question: question, answer: answer, status: success} except Exception as e: return {question: question, answer: None, status: failed, error: str(e)} async def batch_research(questions: List[str]): 批量处理问题列表 tasks [] for q in questions: task asyncio.create_task(research_one_question(q)) tasks.append(task) results await asyncio.gather(*tasks, return_exceptionsTrue) # 输出结果 for i, r in enumerate(results): if isinstance(r, Exception): print(f问题 {i1} 处理异常: {r}) else: print(f\n问题: {r[question]}) print(f状态: {r[status]}) if r[status] success: print(f答案摘要: {r[answer][:200]}...) # 打印前200字符 # 也可以保存到文件 with open(batch_results.json, w, encodingutf-8) as f: json.dump([r for r in results if not isinstance(r, Exception)], f, ensure_asciiFalse, indent2) print(\n详细结果已保存至 batch_results.json) if __name__ __main__: question_list [ FastAPI的主要特点是什么, 什么是RAG检索增强生成, PyTorch 2.0 带来了哪些重要更新 ] asyncio.run(batch_research(question_list))运行批量脚本python batch_research.py这个脚本会异步处理所有问题并将结果输出到控制台和JSON文件中。关键点在实际生产环境中你需要考虑任务队列如Celery、速率限制、错误重试和更完善的日志记录。7. 资源占用与性能观察LangChain框架本身是轻量级的资源消耗主要来自两方面LLM API调用成本与延迟如果你使用OpenAI、Anthropic等云端API主要成本是Token消耗性能瓶颈是网络延迟和API速率限制。监控你的API使用量和响应时间。本地计算资源如果你集成本地部署的大模型如通过Ollama、vLLM则需要关注GPU显存模型加载和推理消耗显存。使用nvidia-smi命令监控。内存处理长上下文或复杂工作流时会消耗较多系统内存。CPU文本预处理、工具函数执行会消耗CPU。性能优化建议设置max_iterations这是最重要的安全阀防止Agent陷入死循环无谓消耗资源和API额度。优化工具设计工具函数应高效、健壮。避免在工具内进行耗时过长的同步操作考虑异步或队列。使用流式响应对于Web应用考虑使用LangChain的流式输出提升用户体验。缓存对频繁且结果不变的查询如某些知识库检索引入缓存机制。监控与可观测性强烈建议集成LangSmith。它能可视化Agent的每一步思考Thought、行动Action和观察Observation是分析性能瓶颈、调试错误和优化提示词的利器。8. 常见问题与排查方法在开发和运行LangChain Agent时你可能会遇到以下问题问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named ‘langchain’依赖未安装或虚拟环境未激活。检查当前Python环境pip list | grep langchain。激活正确的虚拟环境并运行pip install langchain langchain-openai。Agent运行后无响应或报错InvalidRequestErrorOpenAI API密钥错误、额度不足、或模型名称错误。检查OPENAI_API_KEY环境变量登录OpenAI平台检查额度和模型权限。设置正确的API密钥更换为有权限的模型如gpt-3.5-turbo。工具调用失败Agent卡住工具函数内部抛出异常网络问题导致API调用失败。在工具函数内部添加try-except并打印日志单独测试工具函数。完善工具函数的错误处理返回明确的错误信息供Agent处理。确保网络连通。Agent陷入无限循环不输出最终答案系统提示词引导性不强max_iterations设置过大或未设置。使用LangSmith查看每一步的Thought判断模型是否在重复无意义的思考。优化系统提示词明确任务终止条件。务必设置max_iterations如5-10。上下文长度超限错误多轮对话和工具返回内容过长导致发送给LLM的token数超限。计算输入token数。使用LangSmith观察状态积累。1. 使用具有更长上下文窗口的模型。2. 在Memory中启用摘要功能压缩历史。3. 优化工具返回只提取关键信息。create_agent函数找不到LangChain版本过旧。运行pip show langchain查看版本。LangChain 1.0 后推荐使用create_agent。确保安装最新版pip install -U langchain。无法导入TavilyClienttavily-python包未安装或版本不兼容。运行pip show tavily-python。重新安装pip install -U tavily-python。9. 最佳实践与使用建议为了让你的Agent项目从Demo走向生产请遵循以下建议从简单开始逐步复杂化先用1-2个工具验证核心流程思考-行动循环是否跑通。成功后再逐步添加更多工具和复杂逻辑。提示词工程是核心Agent的行为极大程度受系统提示词system_prompt影响。清晰地定义Agent的角色、可用工具、目标以及输出格式。迭代优化提示词是提升Agent表现的关键。工具设计要健壮工具是Agent的手脚。确保工具函数有完善的输入验证、异常处理和超时机制。不要让工具内部的崩溃导致整个Agent失败。必须实施安全限制循环限制始终设置max_iterations。权限隔离Agent不应拥有过高系统权限。工具函数应在沙箱或受限环境中执行危险操作。输入过滤对用户输入进行清洗防止提示词注入攻击。集成可观测性在开发初期就接入LangSmith。它提供的Trace视图能让你清晰看到Agent的决策路径是调试和优化不可或缺的工具。区分LangChain和LangGraphLangChain高阶API开箱即用适合快速构建标准Agent。LangGraph底层运行时提供对状态和流程的精细控制适合构建复杂、长周期、多Agent协作的工作流。建议从LangChain的create_agent开始当需要更复杂的循环、状态持久化或分支逻辑时再深入学习LangGraph。管理好依赖和配置使用requirements.txt或pyproject.toml精确管理包版本。使用.env文件或配置中心管理API密钥等敏感信息。10. 总结与下一步通过本文的实战你已经完成了从零构建一个具备工具调用能力的AI Agent的关键步骤。我们明确了LangChain Agent的核心是ReAct循环其价值在于将“如何做”的决策权交给了大模型开发者只需定义“有什么工具”。这个“智能研究助手”虽然简单但它清晰地展示了Agent的工作范式感知用户问题→ 思考规划步骤→ 行动调用工具→ 观察获取结果→ 再思考……→ 最终回答。你最应该立刻尝试的下一步增加更多工具尝试为Agent添加一个计算器工具calculator和一个获取当前时间的工具get_current_time然后问它“现在北京时间的平方根是多少”。观察它如何组合使用多个工具。接入本地模型将代码中的ChatOpenAI替换为ChatOllama需本地运行Ollama体验完全本地化的Agent。接入LangSmith注册LangSmith账户设置追踪亲眼看看Agent内部的思考过程。这是理解并优化Agent行为的最有效方式。AI Agent的开发不再是纸上谈兵。LangChain这样的框架已经将基础设施搭建完善。真正的挑战和乐趣在于你如何设计工具、编写提示词并将这个“数字员工”安全、可靠地融入到真实的业务流中。现在就从你手头那个重复、枯燥、但又需要一点判断力的任务开始试着让Agent帮你完成吧。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度