LangChain 1.3实战：从零构建可调用工具的AI Agent

如果你正在学习 LangChain 和 Agent 开发可能已经发现官方文档虽然全面但过于抽象网上教程要么太浅要么太散真正能让你从零跑通一个可用 Agent 的实战指南少之又少。更让人困惑的是LangChain 版本更新频繁1.x 系列的变化尤其大很多旧教程里的 API 在新版本中已经失效。你照着做很可能卡在环境配置或工具调用这一步然后陷入无休止的排错。这篇文章不会只讲“LangChain 是什么”而是聚焦一个明确目标用最新的 LangChain 1.3.x手把手带你构建一个真正可用的 Agent并解释每个环节的设计原理和常见坑点。你将学会如何让 LLM 调用工具、处理复杂任务、管理对话状态并理解背后的工作机制。本文代码基于 LangChain 1.3.11 和 LangChain-Community 0.3.8 验证所有示例均可运行。无论你是想快速上手项目还是为面试准备这篇文章都会帮你少走弯路。1. 为什么你需要关注 LangChain 1.3 和 Agent 开发LangChain 不是又一个“包装 LLM 调用的库”它的核心价值在于提供了构建 LLM 应用的标准组件和设计模式。尤其是在 Agent 领域它帮你解决了三个关键问题第一工具调用Tool Calling的标准化。没有 LangChain 之前如果你想让 ChatGPT 帮你查天气、搜资料、写文件需要自己设计提示词、解析 LLM 的输出、处理各种边界情况。LangChain 把这种“LLM 决定做什么、调用工具、处理结果”的流程抽象成了可复用的 Agent 框架。第二状态管理和记忆Memory的封装。简单的单轮对话很容易但多轮对话中如何保持上下文如何让 Agent 记住之前的对话和操作结果LangChain 提供了多种 Memory 方案从简单的缓冲区到基于向量数据库的长期记忆。第三复杂工作流的编排。当任务需要多个步骤或多个 Agent 协作时LangChain 通过 LangGraph 提供了可视化的工作流设计能力。这对于实现审核流程、多专家协作等场景至关重要。现在正是学习 LangChain 1.3 的好时机API 趋于稳定社区生态成熟而且企业中对 Agent 开发的需求正在快速增长。下面我们就从环境准备开始一步步构建你的第一个 Agent。2. LangChain 1.3 环境准备与版本兼容性操作系统要求Windows 10/11, macOS 10.15, 或 Linux (Ubuntu 18.04)Python 3.8-3.11推荐 3.9核心依赖版本# 创建并激活虚拟环境 python -m venv langchain_env source langchain_env/bin/activate # Linux/macOS # 或 langchain_env\Scripts\activate # Windows # 安装核心包 pip install langchain1.3.11 pip install langchain-community0.3.8 pip install openai1.51.0 # 可选用于示例中的工具调用 pip install requests2.32.3 pip install duckduckgo-search3.9.9版本兼容性说明LangChain 1.3.x 与 LangChain-Community 0.3.x 是官方推荐的搭配。如果你遇到导入错误很可能是版本不匹配。社区工具如搜索引擎、API 封装现在都移到 langchain-community 中这是与旧版本最大的区别之一。LLM 配置本文使用 OpenAI GPT-4 作为示例但你也可以替换为其他模型import os from langchain_openai import ChatOpenAI # 设置 API 密钥 os.environ[OPENAI_API_KEY] 你的OpenAI密钥 # 创建 LLM 实例 llm ChatOpenAI( modelgpt-4, temperature0.7 # 控制创造性Agent 任务建议 0.5-0.8 )如果你使用本地模型或其他云服务只需替换为对应的 ChatModel 即可Agent 的构建逻辑完全一致。3. Agent 的核心概念不只是工具调用很多人误以为 Agent 就是“让 LLM 调用工具”其实这只是表面。一个完整的 Agent 包含三个核心组件工具Tools: Agent 可以调用的函数或 API。比如搜索引擎、计算器、数据库查询等。代理Agent: 决策大脑根据当前输入和上下文决定下一步行动。记忆Memory: 存储对话历史和工具执行结果保持上下文连贯。更重要的是理解 Agent 的执行循环接收用户输入结合记忆中的上下文决定是否调用工具、调用哪个工具执行工具并获取结果将结果整合到响应中更新记忆状态这种模式让 LLM 从单纯的文本生成器变成了可以主动采取行动的智能体。下面我们通过实际代码来理解这个过程。4. 构建你的第一个实用 Agent天气查询助手让我们从一个实际可用的例子开始创建一个能查询实时天气的 Agent。4.1 定义天气查询工具首先我们需要一个获取天气数据的工具。这里使用免费的 OpenWeatherMap APIimport requests from langchain.tools import tool tool def get_weather(city: str) - str: 获取指定城市的当前天气情况。 api_key 你的OpenWeatherMap密钥 # 免费注册获取 base_url http://api.openweathermap.org/data/2.5/weather params { q: city, appid: api_key, units: metric, # 摄氏温度 lang: zh_cn } try: response requests.get(base_url, paramsparams) data response.json() if response.status_code 200: weather_desc data[weather][0][description] temp data[main][temp] humidity data[main][humidity] return f{city}的天气{weather_desc}温度{temp}°C湿度{humidity}% else: return f无法获取{city}的天气信息{data.get(message, 未知错误)} except Exception as e: return f天气查询失败{str(e)} # 测试工具 print(get_weather.invoke(北京))4.2 创建 Agent 并集成工具现在我们将这个工具集成到 Agent 中from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate # 定义工具列表 tools [get_weather] # 构建提示词模板 prompt ChatPromptTemplate.from_messages([ (system, 你是一个有用的天气助手。请根据用户需求使用可用工具查询天气信息。 可用工具 {tools} 请严格按照以下规则执行 1. 只有当用户询问天气相关信息时才使用工具 2. 如果用户没有指定城市请主动询问 3. 回复要友好、简洁、包含所有关键信息), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ]) # 创建 Agent agent create_tool_calling_agent(llm, tools, prompt) # 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 测试 Agent result agent_executor.invoke({input: 上海今天天气怎么样}) print(result[output])4.3 运行结果分析当你运行上面的代码时应该看到类似这样的输出 进入新的 AgentExecutor 链... 我应该使用 get_weather 工具来查询上海的天气情况。 行动get_weather 行动输入{city: 上海} 观察上海的天气多云温度23°C湿度65% 思考我已经获取到了上海的天气信息现在可以给用户回复了。 链结束。 上海今天多云温度23°C湿度65%天气比较舒适。这个简单的例子展示了 Agent 的核心工作流程理解用户意图 → 选择合适工具 → 执行工具 → 整合结果。接下来我们深入探讨更复杂的场景。5. 多工具 Agent让 LLM 真正成为你的助手单一工具的 Agent 实用性有限现实中的助手需要多种能力。让我们扩展天气助手加入搜索和计算功能。5.1 添加更多实用工具from langchain_community.tools import DuckDuckGoSearchRun from langchain.tools import Tool # 搜索工具 search DuckDuckGoSearchRun() tool def calculate(expression: str) - str: 计算数学表达式支持加减乘除和括号。 try: # 安全评估只允许基本数学运算 allowed_chars set(0123456789-*/(). ) if not all(c in allowed_chars for c in expression): return 表达式包含不安全字符 result eval(expression) # 生产环境应使用更安全的评估方式 return f{expression} {result} except Exception as e: return f计算错误{str(e)} # 工具列表 tools [get_weather, search, calculate]5.2 设计智能的提示词策略多工具 Agent 需要更精细的提示词设计prompt ChatPromptTemplate.from_messages([ (system, 你是一个多功能助手可以帮用户查询天气、搜索信息和进行数学计算。 可用工具 {tools} 请根据问题类型选择合适的工具 - 天气相关问题 → get_weather - 需要最新信息或知识检索 → search - 数学计算 → calculate - 复杂问题可能需要组合多个工具 请先思考用户意图再选择工具。如果工具执行结果不完整可以继续追问或补充搜索。), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ])5.3 测试复杂任务处理# 创建增强版 Agent advanced_agent create_tool_calling_agent(llm, tools, prompt) advanced_executor AgentExecutor(agentadvanced_agent, toolstools, verboseTrue) # 测试组合任务 tasks [ 北京和上海的温度差多少度, # 需要多次天气查询计算 帮我找一下最新的机器学习会议信息然后计算如果注册费是300美元人民币需要多少, # 搜索计算 今天的天气适合出门散步吗 # 需要推理判断 ] for task in tasks: print(f用户问题{task}) result advanced_executor.invoke({input: task}) print(f助手回复{result[output]}\n)这种多工具协作展示了 Agent 的真正威力LLM 不仅生成文本还协调多个外部工具完成复杂任务。6. 记忆管理让 Agent 记住对话上下文没有记忆的 Agent 就像金鱼每次对话都是新的开始。LangChain 提供了多种记忆方案我们来实践最常用的对话缓冲区记忆。6.1 配置对话记忆from langchain.memory import ConversationBufferMemory # 创建带记忆的执行器 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) agent_executor_with_memory AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue )6.2 测试多轮对话能力# 模拟连续对话 conversation [ 我叫张三来自北京, 你觉得我家乡的天气怎么样, # 这里应该能记住北京 那上海呢, # 继续比较 帮我计算一下两地的平均温度 # 结合之前的信息 ] context {} for i, message in enumerate(conversation): print(f第{i1}轮{message}) result agent_executor_with_memory.invoke({input: message}, context) print(f回复{result[output]}\n)6.3 记忆的底层原理LangChain 的记忆本质上是将对话历史存储在特定结构中并在每次调用时自动注入到提示词中。上面的ConversationBufferMemory会将所有历史对话都保存适合短对话。对于长对话可以考虑ConversationSummaryMemory或ConversationEntityMemory。7. 常见问题与排查指南在实际开发中你几乎一定会遇到下面这些问题。这里提供详细的排查方案。7.1 工具调用失败问题现象Agent 决定调用工具但执行失败或返回错误。排查步骤单独测试工具函数是否正常工作检查工具的参数格式是否符合 LLM 的输出规范验证 API 密钥和网络连接查看 verbose 日志中的具体错误信息解决方案# 添加工具调用异常处理 tool def robust_get_weather(city: str) - str: try: # 原有逻辑 return result except requests.exceptions.RequestException as e: return f网络错误{str(e)} except KeyError as e: return f数据解析错误{str(e)} except Exception as e: return f未知错误{str(e)}7.2 LLM 不调用工具问题现象Agent 直接回答而不是使用可用工具。可能原因提示词没有明确要求使用工具工具描述不够清晰temperature 参数过高导致创造性过强解决方案# 优化提示词 prompt ChatPromptTemplate.from_messages([ (system, 你必须使用提供的工具来回答问题。不要凭空猜测或依赖已有知识。 当用户问及以下类型问题时请使用对应工具 - 实时信息使用搜索工具 - 天气数据使用天气工具 - 数学计算使用计算工具 如果不确定如何使用工具请先确认用户意图。), # ... 其他消息 ])7.3 版本兼容性问题问题现象导入错误或 API 不兼容。解决方案矩阵错误信息可能原因解决方式ImportError: cannot import name ToolLangChain 版本过旧pip install langchain --upgradeAttributeError: module langchain has no attribute agents版本混乱重新安装指定版本pip install langchain1.3.11ValidationError: field required工具参数格式错误检查工具函数的类型注解和默认值7.4 性能优化建议设置合理的超时时间agent_executor AgentExecutor( agentagent, toolstools, max_iterations5, # 防止无限循环 max_execution_time30, # 超时设置 verboseTrue )使用更便宜的模型进行开发# 开发阶段使用 gpt-3.5-turbo 节省成本 dev_llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.7)8. 生产环境最佳实践当你的 Agent 准备上线时需要考虑以下工程化问题。8.1 错误处理与重试机制from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def robust_agent_invoke(question): try: return agent_executor.invoke({input: question}) except Exception as e: logger.error(fAgent执行失败{str(e)}) return {output: 抱歉服务暂时不可用请稍后重试。}8.2 日志与监控import logging from datetime import datetime # 配置结构化日志 logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) class MonitoredAgentExecutor: def __init__(self, agent_executor): self.executor agent_executor def invoke(self, input_data): start_time datetime.now() try: result self.executor.invoke(input_data) duration (datetime.now() - start_time).total_seconds() logger.info(fAgent执行成功 | 时长{duration}s | 输入{input_data}) return result except Exception as e: duration (datetime.now() - start_time).total_seconds() logger.error(fAgent执行失败 | 时长{duration}s | 错误{str(e)}) raise8.3 安全考虑工具调用权限控制# 根据用户权限过滤可用工具 def get_user_tools(user_role): base_tools [calculate] if user_role premium: base_tools.extend([get_weather, search]) return base_tools输入验证与 sanitizationdef sanitize_input(user_input): # 移除潜在的危险字符 cleaned user_input.replace(\x00, ).replace(../, ) # 限制长度 return cleaned[:1000] if len(cleaned) 1000 else cleaned9. 从单 Agent 到多 Agent 协作当任务复杂度增加时单个 Agent 可能不够用。LangChain 通过 LangGraph 支持多 Agent 协作。9.1 设计专家 Agent 团队# 定义专业化的 Agent def create_specialist_agent(name, specialty, tools): prompt ChatPromptTemplate.from_messages([ (system, f你是{specialty}专家。只回答专业领域内的问题。), (human, {input}) ]) return create_tool_calling_agent(llm, tools, prompt) # 创建专家团队 weather_agent create_specialist_agent(气象专家, 天气分析, [get_weather]) research_agent create_specialist_agent(研究助理, 信息检索, [search]) math_agent create_specialist_agent(数学专家, 计算, [calculate])9.2 使用 LangGraph 编排工作流from langgraph.graph import StateGraph, END from typing import TypedDict, List class AgentState(TypedDict): messages: List next_agent: str def route_to_agent(state: AgentState): last_message state[messages][-1] content last_message.content.lower() if any(word in content for word in [天气, 气温, 气候]): return weather_agent elif any(word in content for word in [搜索, 查找, 信息]): return research_agent elif any(word in content for word in [计算, 数学, 等于]): return math_agent else: return general_agent这种架构适合复杂的企业应用比如客服系统路由 Agent → 专业 Agent → 审核 Agent或数据分析流水线。10. 学习路径与进阶资源掌握了基础 Agent 开发后你可以沿着以下路径深入短期1-2周熟练使用 LangChain 常用工具搜索引擎、文件处理、API 集成掌握不同的 Memory 策略和应用场景学会调试和优化 Agent 性能中期1-2月学习 LangGraph 进行复杂工作流编排集成向量数据库实现长期记忆掌握 Agent 评估和测试方法长期3月研究多模态 Agent图像、音频处理学习 Agent 安全性和对齐技术参与开源项目或构建生产级应用推荐学习资源LangChain 官方文档关注 API 变更LangChain Cookbook 实战示例相关论文《ReAct: Synergizing Reasoning and Acting in Language Models》记住Agent 开发的核心不是记住所有 API而是理解 LLM 与工具协作的设计模式。开始构建你的第一个实用 Agent在实践中遇到问题、解决问题这才是最快的学习路径。最好的学习方式是立即动手。从今天介绍的天气查询助手开始逐步添加更多功能很快你就能构建出真正智能的 AI 助手。