最近在尝试将大语言模型LLM与外部工具和数据进行深度集成时你是否感到无从下手面对 LangChain、MCP、LangGraph 这些新兴框架和协议网上资料要么过于零散要么版本陈旧很难找到一个从零开始、手把手带你完成一个完整 AI Agent 项目的实战指南。本文将为你彻底解决这个问题整合一套基于最新版 LangChain 生态的闭环实操方案。无论你是刚接触 AI 应用开发的新手还是希望将 Agent 能力落地到具体业务场景的开发者都能通过本文掌握从环境搭建、核心概念理解到代码实战开发的全流程并避开那些常见的“坑”。1. 背景与核心概念为什么需要 LangChain 与 MCP在深入代码之前我们有必要厘清这几个核心组件分别解决了什么问题以及它们如何协同工作。这能帮助你在后续开发中做出更合理的技术选型。1.1 LangChainAI 应用的“脚手架”LangChain本质上是一个用于开发由语言模型驱动的应用程序的框架。你可以把它想象成构建 AI 应用的“脚手架”或“工具箱”。它本身不提供大模型而是提供了一套标准化的接口和组件让你能更方便地连接不同的 LLM如 OpenAI GPT、 Anthropic Claude、本地部署的 Llama 等、处理各种格式的数据文本、PDF、网页、调用外部工具搜索、计算、API并管理复杂的对话或任务流程。在没有 LangChain 之前开发者需要手动处理提示词Prompt拼接、上下文管理、工具调用解析等繁琐且易错的逻辑。LangChain 将这些通用模式抽象成可复用的模块如LLMChain、Agent、Memory、Retriever等极大地提升了开发效率。1.2 MCPModel Context Protocol工具的“统一插座”MCPModel Context Protocol是 LangChain 生态中一个相对较新但至关重要的协议。它旨在解决 AI 应用与外部工具、数据源集成时的标准化问题。你可以把 MCP 理解为一套标准的“插座”和“插头”规范。任何工具或数据源如数据库、API、文件系统只要实现了 MCP Server就可以像一个标准的“电器”一样被任何支持 MCP Client 的 AI 应用如基于 LangChain 构建的 Agent“即插即用”。它的核心价值在于解耦对工具开发者只需按照 MCP 协议实现一次就能让所有兼容 MCP 的 AI 框架使用。对 AI 应用开发者无需为每一个新工具编写特定的集成代码只需通过 MCP 客户端发现和调用工具。例如一个“查询天气”的 MCP 服务器可以被 LangChain Agent、Claude Desktop 或其他任何支持 MCP 的客户端同时使用。1.3 LangGraph构建复杂、有状态的 Agent 工作流LangGraph是 LangChain 的一个库用于构建具有循环和状态的多步骤工作流。如果说基础的 LangChain Agent 是“单次决策-执行”那么 LangGraph 就是为 Agent 设计了“流程图”。它允许你明确定义 Agent 的步骤节点、步骤之间的流转条件边并持久化整个工作流的状态。这使得构建以下复杂应用成为可能具备长期记忆的对话助手能记住跨多轮对话的上下文和用户偏好。多步骤任务规划与执行例如“分析数据-生成报告-发送邮件”这样的流水线。具备检查和重试机制的鲁棒 Agent当某一步失败时可以自动回退或尝试其他路径。LangGraph 引入了StateGraph和Checkpointer等核心概念是开发现实中实用 AI Agent 的强力工具。1.4 Agent自主决策与执行的智能体在 LangChain 语境下Agent是一个核心概念它指的是一个由 LLM 驱动、能够根据目标自主决定调用哪些工具Tools并执行动作的系统。Agent LLM大脑 Tools手脚 决策逻辑。一个典型的 Agent 工作流程是感知接收用户输入或环境状态。规划LLM 分析目标决定下一步该做什么是直接回答还是调用工具A或工具B。执行调用选定的工具并获取结果。反思根据工具结果决定任务是否完成或是否需要进一步规划。本文的实战目标就是综合运用 LangChain、MCP 和 LangGraph构建一个功能完整、可扩展的 AI Agent。2. 环境准备与版本说明工欲善其事必先利其器。为了避免版本冲突和环境问题请严格按照以下步骤配置你的开发环境。2.1 基础环境要求操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04 推荐)。本文示例在 macOS/Linux 环境下编写Windows 用户请注意命令的细微差别如使用dir而非ls。Python 版本Python 3.10 或 3.11。LangChain 新版本对 Python 3.12 的支持可能仍在完善中为避免兼容性问题建议使用 3.10 或 3.11。可使用python --version检查。包管理工具推荐使用pip和venv创建虚拟环境。也可使用conda或poetry。2.2 创建并激活虚拟环境使用虚拟环境是 Python 开发的最佳实践可以隔离项目依赖。# 1. 创建项目目录并进入 mkdir langchain-mcp-agent-tutorial cd langchain-mcp-agent-tutorial # 2. 创建虚拟环境以 python3.10 为例 python3.10 -m venv venv # 3. 激活虚拟环境 # 在 macOS/Linux 上 source venv/bin/activate # 在 Windows 上 # venv\Scripts\activate # 激活后命令行提示符前应显示 (venv)2.3 安装核心依赖我们将安装 LangChain 全家桶、MCP 相关库以及一个本地 LLM 运行环境Ollama来模拟完整的离线/在线开发场景。# 升级 pip 确保安装顺利 pip install --upgrade pip # 安装 LangChain 核心及社区工具注意安装 langchain-community 而非旧版的 langchain pip install langchain langchain-community # 安装 LangGraph 用于构建工作流 pip install langgraph # 安装 LangChain 的 MCP 集成包 pip install langchain-mcp # 安装 OpenAI 库我们将使用其兼容的 API 与 Ollama 交互 pip install openai # 安装用于示例的额外工具库 pip install requests duckduckgo-search # 安装 Jupyter 笔记本可选用于交互式实验 pip install jupyter重要版本说明langchain和langchain-community的拆分是较新的变化许多旧教程直接安装langchain即可但现在工具类多位于langchain-community中。我们同时安装以确保兼容。langchain-mcp是专门为 MCP 协议集成提供的包。2.4 安装并配置本地 LLM (Ollama)为了完全本地化运行和演示我们使用Ollama来运行开源大模型。它提供了类似 OpenAI API 的接口方便替换。安装 Ollama访问 Ollama 官网 下载并安装对应操作系统的版本。或者通过命令行安装Linux/macOScurl -fsSL https://ollama.com/install.sh | sh拉取一个模型Ollama 启动后拉取一个轻量级模型例如llama3.2或qwen2.5:7b。ollama pull llama3.2 # 或 # ollama pull qwen2.5:7b验证 Ollama 服务ollama run llama3.2 “你好”如果能看到模型回复说明服务正常。Ollama 默认会在http://localhost:11434提供 API 服务。2.5 项目结构预览在开始编码前先规划一下我们的项目结构langchain-mcp-agent-tutorial/ ├── venv/ # Python 虚拟环境.gitignore ├── requirements.txt # 项目依赖列表 ├── .env # 环境变量API Keys等.gitignore ├── simple_agent.py # 基础 Agent 示例 ├── mcp_agent_demo.py # 集成 MCP 的 Agent 示例 ├── langgraph_agent.py # 使用 LangGraph 的复杂 Agent ├── tools/ # 自定义工具目录 │ └── custom_tools.py ├── mcp_servers/ # 自定义 MCP 服务器示例可选 │ └── simple_server.py └── README.md接下来我们将一步步填充这些文件。3. 核心语法与组件拆解让我们先熟悉 LangChain 中最常用的几个“积木块”这是构建复杂应用的基础。3.1 连接 LLMChatModelsLangChain 通过ChatModel抽象与各种 LLM 的交互。以下是如何连接 OpenAI 格式的 API包括 Ollama。# 文件simple_agent.py 的开头部分 import os from langchain_openai import ChatOpenAI from langchain_community.chat_models import ChatOllama # 方式1连接 OpenAI需要 API Key # 假设你的 OpenAI API Key 存储在环境变量 OPENAI_API_KEY 中 # llm ChatOpenAI(modelgpt-4o-mini, temperature0.7) # 方式2连接本地 Ollama 服务无需 API Key推荐用于学习和测试 llm ChatOllama( base_urlhttp://localhost:11434, # Ollama 默认地址 modelllama3.2, # 你拉取的模型名 temperature0.7, # 控制创造性0-1越高越随机 ) # 测试连接 from langchain_core.messages import HumanMessage response llm.invoke([HumanMessage(content你好请用中文介绍你自己。)]) print(response.content)关键参数解释model: 指定使用的模型名称。temperature: 采样温度影响输出的随机性。0表示确定性输出每次相同1表示高度随机。对于需要稳定性的任务如代码生成建议调低如 0.2对于创意任务可以调高如 0.8。base_url: 当使用非 OpenAI 官方端点时如 Ollama、本地部署的模型通过此参数指定 API 地址。3.2 构建提示词PromptTemplate 与 ChatPromptTemplate直接拼接字符串构造提示词容易出错且难以维护。LangChain 提供了模板工具。from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder # 一个简单的提示词模板 simple_template ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的AI助手名字叫{assistant_name}。), MessagesPlaceholder(variable_namechat_history), # 预留位置给历史消息 (human, {user_input}), ]) # 填充模板 prompt simple_template.format_messages( assistant_name小链, chat_history[], # 当前没有历史 user_input今天的天气怎么样 ) print(prompt) # 输出类似[SystemMessage(content你是一个乐于助人的AI助手名字叫小链。), HumanMessage(content今天的天气怎么样)] # 将模板与 LLM 连接起来形成一个链Chain from langchain.chains import LLMChain chain LLMChain(llmllm, promptsimple_template) result chain.run(assistant_name小链, chat_history[], user_inputPython中如何反转列表) print(result)ChatPromptTemplate支持更复杂的消息结构包括系统消息、AI消息、人类消息和工具消息是构建对话系统的核心。3.3 创建与使用工具Tools工具是 Agent 的“手脚”。一个工具本质上是一个函数附带清晰的名称和描述供 LLM 理解和调用。# 文件tools/custom_tools.py from langchain.tools import tool import requests import math tool def get_weather(city: str) - str: 根据城市名获取当前天气情况。这是一个模拟工具。 # 注意这是一个模拟函数。真实场景应调用如 OpenWeatherMap 的 API。 weather_map { 北京: 晴15°C, 上海: 多云18°C, 深圳: 阵雨22°C, 纽约: 阴10°C, } return weather_map.get(city, f未找到{city}的天气信息。) tool def calculate_circle_area(radius: float) - float: 计算给定半径的圆的面积。 return math.pi * radius * radius # 工具列表 tools [get_weather, calculate_circle_area] # 在另一个文件中使用 # from tools.custom_tools import toolstool装饰器会自动将函数转换为 LangChain 可识别的工具对象。函数的文档字符串 ... 至关重要LLM 依靠它来决定是否以及如何调用该工具。3.4 构建基础 Agent将 LLM、工具和提示词组合起来就形成了一个能自主使用工具的 Agent。# 文件simple_agent.py 的后续部分 from langchain.agents import create_react_agent, AgentExecutor from langchain import hub # 1. 准备工具使用我们自定义的工具 from tools.custom_tools import tools # 2. 从 LangChain Hub 拉取一个高效的提示词模板ReAct 格式 # ReAct: Reasoning Acting一种让 LLM 边思考边行动的经典模式 prompt hub.pull(hwchase17/react-chat) # 3. 创建 ReAct Agent agent create_react_agent(llm, tools, prompt) # 4. 创建 Agent 执行器它负责处理与 Agent 的交互循环 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 开启详细日志方便观察 Agent 的思考过程 handle_parsing_errorsTrue, # 处理解析错误避免因 LLM 输出格式不对而崩溃 ) # 5. 运行 Agent try: result agent_executor.invoke({ input: 请问北京和上海的天气怎么样然后计算一个半径为5的圆的面积。, chat_history: [] # 初始无历史 }) print(\n 最终结果 ) print(result[output]) except Exception as e: print(fAgent 执行出错: {e})运行python simple_agent.py你会看到类似以下的详细输出verboseTrue的效果 Entering new AgentExecutor chain... 我需要回答用户关于北京、上海天气和计算圆面积的问题。我有两个工具get_weather 用于查询天气calculate_circle_area 用于计算圆面积。 首先我需要查询北京的天气。 Action: get_weather Action Input: {city: 北京} Observation: 晴15°C Thought: 现在查询上海的天气。 Action: get_weather Action Input: {city: 上海} Observation: 多云18°C Thought: 现在计算半径为5的圆的面积。 Action: calculate_circle_area Action Input: {radius: 5} Observation: 78.53981633974483 Thought: 我现在有了所有信息可以给出最终答案了。 Final Answer: 北京的天气是晴15°C上海的天气是多云18°C。半径为5的圆的面积大约是78.54。 Finished chain. 最终结果 北京的天气是晴15°C上海的天气是多云18°C。半径为5的圆的面积大约是78.54。这个输出清晰地展示了 ReAct Agent 的“思考Thought-行动Action-观察Observation”循环。4. 完整实战案例一集成 MCP 工具的智能 Agent现在我们来升级 Agent让它能够使用通过MCP 协议提供的工具。我们将使用一个现成的 MCP 服务器modelcontextprotocol/server-filesystem来让 Agent 拥有读取本地文件列表的能力。4.1 安装 MCP 服务器首先我们需要安装一个 MCP 服务器。这里我们使用一个官方提供的文件系统服务器。# 使用 npm 全局安装确保已安装 Node.js npm install -g modelcontextprotocol/server-filesystem # 或者使用 npx 直接运行无需安装 # npx modelcontextprotocol/server-filesystem安装后你可以通过命令mcp-server-filesystem启动这个服务器它会在后台运行并通过标准输入输出stdio与客户端通信。4.2 编写集成 MCP 的 Agent 代码我们将创建一个新的 Python 文件使用langchain-mcp来连接这个 MCP 服务器并将其工具暴露给我们的 Agent。# 文件mcp_agent_demo.py import asyncio import os from langchain.agents import create_react_agent, AgentExecutor from langchain import hub from langchain_community.chat_models import ChatOllama from langchain_mcp import McpServer, McpTool async def main(): print(启动 MCP 文件系统服务器并创建 Agent...) # 1. 初始化 LLM (Ollama) llm ChatOllama(base_urlhttp://localhost:11434, modelllama3.2, temperature0.1) # 2. 创建并启动 MCP 服务器客户端 # 这里我们通过子进程启动之前安装的文件系统 MCP 服务器。 # stdioTrue 表示通过标准输入输出与服务器通信。 async with McpServer.from_binary( commandnpx, # 使用 npx 运行 args[modelcontextprotocol/server-filesystem, .], # 服务器命令及参数. 表示当前目录 stdioTrue, ) as server: # 3. 获取 MCP 服务器提供的所有工具 mcp_tools [] for tool in server.tools: # 将 MCP 工具包装成 LangChain 能识别的 Tool 对象 langchain_tool McpTool.from_mcp_tool(tool) mcp_tools.append(langchain_tool) print(f已加载 MCP 工具: {langchain_tool.name} - {langchain_tool.description}) # 4. 也可以结合我们之前自定义的工具 from tools.custom_tools import get_weather all_tools mcp_tools [get_weather] # 5. 创建 Agent使用 ReAct 模式 prompt hub.pull(hwchase17/react-chat) agent create_react_agent(llm, all_tools, prompt) agent_executor AgentExecutor( agentagent, toolsall_tools, verboseTrue, handle_parsing_errorsTrue ) # 6. 运行一个查询示例 print(\n *50) print(示例 1: 查询当前目录下的文件) result1 await agent_executor.ainvoke({ input: 列出当前目录下所有的 Python 文件。, chat_history: [] }) print(f结果: {result1[output]}) print(\n *50) print(示例 2: 结合 MCP 工具和自定义工具) result2 await agent_executor.ainvoke({ input: 先看看当前目录有什么然后告诉我北京的天气。, chat_history: [] }) print(f结果: {result2[output]}) if __name__ __main__: asyncio.run(main())4.3 运行与结果分析在项目根目录下运行这个脚本python mcp_agent_demo.py你会看到程序首先启动 MCP 服务器并加载其提供的工具例如list_directoryread_file等。然后 Agent 开始工作对于第一个查询Agent 会识别出需要使用list_directory这个 MCP 工具调用它获取当前目录列表然后筛选出.py文件最后组织语言回答。对于第二个查询Agent 会先规划使用list_directory执行后获得观察结果再规划使用get_weather工具最终将两个结果合并回答。这个 demo 的关键意义在于我们并没有为“列出文件”这个功能写任何具体的 Python 代码。我们只是启动了一个标准的 MCP 服务器然后通过langchain-mcp库自动将其功能“转换”成了 LangChain Agent 可以直接使用的工具。这就是 MCP 协议带来的“即插即用”威力。5. 完整实战案例二使用 LangGraph 构建有状态的对话 Agent基础 Agent 和 MCP Agent 在单次任务中表现良好但缺乏记忆和复杂的流程控制。现在我们使用LangGraph来构建一个更强大的 Agent它能够记住整个对话历史。在工具调用失败时进行优雅处理或重试。实现多轮对话的复杂逻辑。5.1 设计 Agent 状态LangGraph 的核心是定义和管理状态State。我们首先定义一个描述我们 Agent 状态的数据结构。# 文件langgraph_agent.py from typing import TypedDict, Annotated, List from langchain_core.messages import BaseMessage import operator class AgentState(TypedDict): 定义 Agent 工作流的状态。 # 消息历史记录所有对话 messages: Annotated[List[BaseMessage], operator.add] # 用户的最新输入 user_input: str # Agent 的下一步动作由 LLM 决定 next_action: str # 工具调用的结果 tool_output: strAnnotated[List[BaseMessage], operator.add]是一个高级用法它告诉 LangGraph当多个节点修改messages字段时使用operator.add即列表的操作来合并它们这非常适合追加消息。5.2 定义工作流节点Nodes节点是工作流中的步骤每个节点是一个函数接收当前状态返回更新后的状态。from langchain_core.messages import HumanMessage, AIMessage, ToolMessage from langgraph.graph import END # 1. 判断节点决定下一步该做什么 def should_use_tool(state: AgentState): 根据对话历史和最新输入判断是否需要调用工具。 from langchain_community.chat_models import ChatOllama from langchain_core.prompts import ChatPromptTemplate llm ChatOllama(base_urlhttp://localhost:11434, modelllama3.2, temperature0) # 构建一个分类提示词 prompt ChatPromptTemplate.from_messages([ (system, 你是一个决策助手。根据对话历史和用户最新输入判断是否需要调用工具来回答问题。如果需要回复 TOOL如果可以直接回答回复 ANSWER。只回复一个单词。), (human, 历史对话{history}\n\n用户最新输入{input}), ]) # 格式化历史消息 history_text \n.join([f{m.type}: {m.content} for m in state[messages]]) chain prompt | llm decision chain.invoke({history: history_text, input: state[user_input]}).content.strip() if TOOL in decision.upper(): return {next_action: call_tool} else: return {next_action: generate_answer} # 2. 工具调用节点 def call_tool_node(state: AgentState): 执行工具调用。 from tools.custom_tools import get_weather, calculate_circle_area import json # 简单的工具路由逻辑实际应用中可以用更智能的方式如让LLM选择 tool_name None tool_input {} # 这里简化处理如果输入包含“天气”调用天气工具包含“面积”调用计算工具。 if 天气 in state[user_input]: tool_name get_weather # 简单提取城市名实际应用需要更复杂的NLP city 北京 # 默认应改进 for c in [北京, 上海, 深圳]: if c in state[user_input]: city c break tool_input {city: city} tool_func get_weather elif 面积 in state[user_input] or 圆 in state[user_input]: tool_name calculate_circle_area # 简单提取数字实际应用需要更复杂的NLP import re numbers re.findall(r\d, state[user_input]) radius float(numbers[0]) if numbers else 5.0 tool_input {radius: radius} tool_func calculate_circle_area else: # 没有匹配的工具返回错误信息 return { tool_output: 未找到匹配的工具来处理此请求。, next_action: generate_answer } # 调用工具 try: output tool_func.invoke(tool_input) tool_result f工具 {tool_name} 调用成功输入为 {tool_input}输出为{output} except Exception as e: tool_result f工具 {tool_name} 调用失败错误{str(e)} # 将工具执行结果作为一条 ToolMessage 加入历史 tool_message ToolMessage(contenttool_result, tool_call_idfake_id) return { tool_output: tool_result, messages: [tool_message], next_action: generate_answer } # 3. 答案生成节点 def generate_answer_node(state: AgentState): 根据对话历史和工具结果生成最终答案。 from langchain_community.chat_models import ChatOllama from langchain_core.prompts import ChatPromptTemplate llm ChatOllama(base_urlhttp://localhost:11434, modelllama3.2, temperature0.7) # 构建包含完整上下文的提示词 prompt ChatPromptTemplate.from_messages([ (system, 你是一个智能助手。请根据以下对话历史和工具调用结果回应用户的最后一条消息。如果使用了工具请将工具结果自然地整合到回答中。), (human, {history}\n\n工具调用结果{tool_output}\n\n请回答用户的最新问题{input}), ]) history_text \n.join([f{m.type}: {m.content} for m in state[messages]]) chain prompt | llm response chain.invoke({ history: history_text, tool_output: state.get(tool_output, 无), input: state[user_input] }) # 将 AI 的回答加入历史 ai_message AIMessage(contentresponse.content) return { messages: [ai_message], next_action: END # 表示本轮对话结束工作流可以停止 }5.3 构建并运行 LangGraph 工作流现在我们将这些节点连接起来形成一个有向图。# 文件langgraph_agent.py (续) from langgraph.graph import StateGraph, END # 创建状态图 workflow StateGraph(AgentState) # 添加节点 workflow.add_node(should_use_tool, should_use_tool) # 这个节点同时做判断和返回路由 workflow.add_node(call_tool, call_tool_node) workflow.add_node(generate_answer, generate_answer_node) # 设置入口点 workflow.set_entry_point(should_use_tool) # 定义边路由逻辑 # 从判断节点出发根据 next_action 的值路由到不同节点 workflow.add_conditional_edges( should_use_tool, # 路由函数根据状态中的 next_action 字段决定下一个节点 lambda state: state[next_action], { call_tool: call_tool, generate_answer: generate_answer, } ) # 从工具调用节点到答案生成节点是固定的 workflow.add_edge(call_tool, generate_answer) # 答案生成节点指向 END workflow.add_edge(generate_answer, END) # 编译图 app workflow.compile() # 可视化图需要安装 graphviz try: from IPython.display import Image, display display(Image(app.get_graph().draw_mermaid_png())) except: print(无法显示图形但图已构建成功。) # 运行工作流 def run_conversation(): 运行一个简单的对话循环。 print(LangGraph 对话 Agent 已启动。输入 退出 或 quit 结束。) # 初始化状态 initial_state AgentState( messages[], # 初始为空 user_input, next_action, tool_output ) current_state initial_state while True: user_input input(\n你: ) if user_input.lower() in [退出, quit, exit]: print(对话结束。) break # 将用户输入添加到状态中 current_state[user_input] user_input current_state[messages].append(HumanMessage(contentuser_input)) # 执行工作流 print(Agent 正在思考...) final_state app.invoke(current_state) # 获取最新的 AI 回复 ai_messages [m for m in final_state[messages] if isinstance(m, AIMessage)] if ai_messages: latest_ai_msg ai_messages[-1] print(f助手: {latest_ai_msg.content}) # 更新当前状态保留历史以进行下一轮对话 current_state final_state if __name__ __main__: run_conversation()5.4 运行与体验运行python langgraph_agent.py你将进入一个交互式对话。尝试以下输入“北京天气怎么样” - Agent 会调用天气工具并回答。“计算半径10的圆的面积。” - Agent 会调用计算工具并回答。“谢谢你” - Agent 会直接生成礼貌回答而不调用工具。这个工作流虽然简单但清晰地展示了 LangGraph 的核心优势状态持久化和流程可控。所有的消息Human, AI, Tool都保存在state[‘messages’]中可以被后续节点使用实现了真正的多轮对话记忆。你可以在此基础上扩展增加错误处理节点、人工审核节点等构建极其复杂的 Agent 逻辑。6. 常见问题与排查思路在开发过程中你可能会遇到以下典型问题。这里提供排查思路和解决方案。问题现象可能原因排查步骤与解决方案ModuleNotFoundError: No module named ‘langchain_community’依赖安装不完整或版本过旧。1. 确保使用pip install langchain-community安装。2. 检查pip list确认langchain和langchain-community版本较新如 0.1.x 以上。3. 考虑使用pip install langchain[all]安装常用全家桶。Ollama 连接失败(ConnectionError)Ollama 服务未启动或地址端口不对。1. 在终端运行ollama serve查看服务状态。2. 确认代码中base_url为http://localhost:11434。3. 运行curl http://localhost:11434/api/tags测试 API 是否可达。Agent 不调用工具总是直接回答1. 工具描述不清晰。2. LLM 能力不足或温度设置过高。3. 提示词Prompt未优化。1.检查工具描述确保函数文档字符串清晰描述了工具的功能和输入参数。2.调整 LLM尝试能力更强的模型如llama3.1:8b或降低temperature如设为 0。3.优化 Prompt使用 LangChain Hub 上经过验证的 Agent Prompt如hwchase17/react-chat。MCP 服务器启动失败或超时1. Node.js/npm 未安装。2. 服务器包名错误或网络问题。3. 命令路径问题。1. 运行node --version和npm --version确认环境。2. 尝试直接运行npx modelcontextprotocol/server-filesystem .看能否独立启动。3. 在McpServer.from_binary中尝试使用shellTrue参数Windows 可能需此。4. 考虑使用async with McpServer.from_binary(... , timeout30)增加超时时间。LangGraph 工作流陷入循环或状态错误1. 条件边add_conditional_edges的路由逻辑有误。2. 状态更新逻辑operator.add使用不当。1.打印调试在节点函数中打印state观察状态变化。2.简化图先构建一个只有两个节点的简单图确保基础流程正确。3.检查路由函数确保它返回的键值存在于目标节点映射中。4.审查状态结构确保Annotated修饰器正确使用对于列表追加operator.add通常是正确的。处理速度慢1. 本地 LLM 推理速度慢。2. 网络延迟调用外部 API。3. 工具调用耗时。1.模型层面换用更小的模型如llama3.2:3b或使用量化版本。2.代码层面使用异步调用 (ainvoke)并行处理独立任务。3.缓存对重复查询使用 LangChain 的缓存组件 (InMemoryCache,SQLiteCache)。handle_parsing_errorsTrue仍崩溃LLM 的输出格式完全无法被解析。1. 将verboseTrue打开查看 LLM 输出的原始内容检查是否格式混乱。2. 使用更强大的模型。3. 实现自定义的output_parser或错误处理中间件。7. 最佳实践与工程建议将原型转化为稳定、可维护的生产级应用需要遵循以下实践。7.1 项目管理与依赖管理使用requirements.txt或pyproject.toml精确锁定所有依赖包及其版本避免环境不一致。# requirements.txt langchain0.1.20 langchain-community0.0.29 langgraph0.0.57 langchain-mcp0.1.0 openai1.30.1 requests2.31.0分离配置与环境变量永远不要将 API Keys、数据库密码等敏感信息硬编码在代码中。使用.env文件和python-dotenv库管理。# .env OPENAI_API_KEYsk-... MCP_SERVER_PATH/usr/local/bin/mcp-server# config.py import os from dotenv import load_dotenv load_dotenv() OPENAI_API_KEY os.getenv(OPENAI_API_KEY)7.2 提示词工程模板化与外部存储将复杂的提示词存储在单独的.txt或.yaml文件中或使用 LangChain Hub。便于版本管理和 A/B 测试。提供清晰示例在提示词中包含少量示例Few-shot Learning能显著提升 Agent 使用工具的准确率。结构化输出要求 LLM 以 JSON 等固定格式输出便于后续解析。LangChain 的PydanticOutputParser是很好的工具。7.3 Agent 与工具设计工具职责单一每个工具应只做一件事。例如search_web和get_weather分开而不是一个query_external工具。详细的工具描述工具的name和description是 LLM 选择工具的主要依据务必准确、清晰。工具输入验证在工具函数内部对输入参数进行类型和有效性校验返回友好的错误信息。设置超时与重试对于调用外部 API 的工具务必设置超时并考虑实现重试逻辑可使用tenacity库。7.4 使用 LangGraph 构建复杂流程从简单开始先用几个节点实现核心流程再逐步增加错误处理、人工审核、条件分支等复杂逻辑。状态设计精简只把需要跨节点共享的数据放入 State。避免状态过大影响性能。利用检查点对于长时运行的工作流使用Checkpointer持久化状态实现断点续跑。可视化调试充分利用app.get_graph().draw_mermaid_png()生成流程图帮助理解和调试工作流。7.5 测试与监控单元测试为每个工具函数、节点函数编写单元测试。集成测试模拟用户输入测试完整的 Agent 工作流验证其是否按预期调用工具并返回结果。日志记录在关键节点如工具调用前后、LLM 调用前后添加详细日志使用logging模块而非print。性能监控记录每个步骤的耗时特别是 LLM 调用和工具调用以便发现瓶颈。7.6 安全与合规权限控制MCP 服务器或自定义工具可能访问敏感系统文件、数据库、API。务必遵循最小权限原则在生产环境中严格限制其访问范围。用户输入净化对所有传入 LLM 或工具的用户输入进行验证和净化防止提示词注入或命令注入攻击。内容过滤对 LLM 生成的内容根据应用场景考虑添加后处理过滤层。数据隐私明确告知用户数据如何被使用避免将敏感用户数据发送至不可信的第三方 LLM API。通过本文的梳理你应该已经掌握了使用新版 LangChain、MCP 和 LangGraph 构建 AI Agent 的完整路径。从核心概念的理解到环境的搭建再到基础 Agent、MCP Agent 和 LangGraph 工作流的逐级实战我们覆盖了一个智能体系统从雏形到具备复杂流程和记忆能力的关键演进步骤。真正的掌握源于动手实践建议你以本文的代码为起点尝试改造工具、设计新的工作流或将其集成到你自己的业务场景中。
