1. 先搞清楚 LangChain、MCP、LangGraph 和 Agent 到底能帮你做什么如果你刚开始接触 AI 应用开发看到 LangChain、MCP、LangGraph、Agent 这些词第一反应可能是“概念好多无从下手”。这很正常因为每个词都代表一个不同的层次和工具。别急着去背定义我们先从最实际的问题出发它们合在一起能帮你解决什么具体问题简单来说这套组合能让你用代码快速搭建一个能“思考”和“行动”的 AI 应用。这里的“思考”指的是让大语言模型比如 GPT、Claude 或本地部署的模型理解你的指令、规划步骤“行动”指的是让模型能调用外部工具比如查数据库、读文件、调用 API、执行计算。而 LangChain、MCP、LangGraph 就是帮你把“思考”和“行动”组织起来的脚手架。LangChain是基础框架。它提供了和大模型对话、管理对话历史记忆、以及连接各种工具Tools的标准方法。你可以把它想象成乐高积木的底板和基础连接件。MCPModel Context Protocol是工具连接协议。它定义了一种标准方式让你开发的 AI 应用能安全、规范地调用外部工具比如一个查询天气的 API或者一个读取本地文件的函数。MCP 解决了“如何让模型安全地使用工具”这个核心问题。LangGraph是高级流程控制器。当你的 AI 应用逻辑变复杂需要根据模型输出的结果决定下一步做什么比如先查天气再根据天气决定推荐室内还是室外活动这种带“分支”和“循环”的流程用基础的 LangChain 链Chain写起来会很别扭。LangGraph 允许你用“图”的方式来定义这种有状态的、多步骤的工作流让复杂 Agent 的逻辑变得清晰可控。Agent是最终呈现的智能体。它是基于以上所有组件构建出来的、能够自主理解目标、规划并执行一系列工具调用以完成任务的 AI 程序。一个强大的 Agent 背后通常离不开 LangGraph 的流程编排和 MCP 的工具支持。所以这个教程的核心价值是从零开始手把手教你用这些业界主流工具搭建一个真正能跑起来的、功能清晰的 AI Agent而不仅仅是跑通一个“Hello World”的对话示例。你会学到如何组织代码、如何连接工具、如何控制执行流程以及如何排查那些让新手头疼的典型错误。2. 环境准备别在依赖和版本上踩第一个坑在写第一行业务代码之前把环境理顺能避免 80% 的莫名报错。我们不追求最新版本而是追求一个稳定、兼容的起步环境。2.1 基础 Python 环境我强烈建议使用Python 3.10 或 3.11。Python 3.12 对一些库的兼容性可能还在完善中新手先避开。使用conda或venv创建独立的虚拟环境是必须的。# 使用 conda 创建环境推荐 conda create -n langchain-demo python3.11 conda activate langchain-demo # 或者使用 venv python -m venv venv # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate2.2 核心库安装通过 pip 安装核心库。注意langchain是一个元包我们通常需要安装更具体的子包和社区集成包。pip install langchain langchain-community langchain-core关键解释langchain-core: 包含最核心的抽象基类和运行时。大部分情况下你通过其他包间接使用它。langchain: 包含标准接口、链和基础工具的实现。langchain-community: 这是非常重要的包包含了大量第三方工具的集成比如与各种数据库、API 的连接器。很多教程里提到的工具Tool都来自这里。接下来安装 LangGraph它是构建复杂 Agent 工作流的关键pip install langgraph对于 MCP目前它更像一个协议标准和一套开发工具集。你可能需要安装mcp客户端库或相关 SDK 来创建或连接 MCP 服务器。由于 MCP 生态在快速演进一个稳妥的起步方式是关注 LangChain 官方对 MCP 的支持。通常你可以通过langchain社区工具来调用符合 MCP 协议的工具。2.3 模型访问准备你需要一个能够访问的大语言模型。有两种主要路径使用云端 API如 OpenAI, Anthropic最简单快捷适合学习和原型开发。pip install openai langchain-openai然后需要设置环境变量OPENAI_API_KEY。export OPENAI_API_KEY你的sk-...密钥 # Windows: set OPENAI_API_KEY你的sk-...密钥使用本地模型如通过 Ollama更注重隐私和成本控制适合深入研究和生产部署。# 首先安装并启动 Ollama从官网下载安装包 # 然后拉取一个模型例如 Llama 3.1 ollama pull llama3.1:8b # 安装 LangChain 的 Ollama 集成 pip install langchain-ollama新手建议为了减少环境变量和网络问题的干扰我强烈建议初学者先从本地 Ollama 模型开始。它能让你立刻聚焦于 LangChain 和 LangGraph 的代码逻辑本身而不是卡在 API 密钥配置或网络连通性上。2.4 初始化一个清晰的项目目录不要把所有代码扔在一个文件里。建立清晰的目录结构有助于后续管理工具、工作流和配置。your_agent_project/ ├── tools/ # 存放自定义工具类或 MCP 服务器文件 │ └── weather_tool.py ├── workflows/ # 存放 LangGraph 工作流定义 │ └── travel_agent.py ├── config.py # 配置文件存放模型、API密钥等设置 ├── main.py # 主入口文件 └── requirements.txt在requirements.txt中记录依赖langchain0.1.0 langchain-community0.0.10 langgraph0.0.17 langchain-ollama0.1.03. 从核心概念到第一个能跑的 Agent现在我们跳过理论深水区直接通过代码来理解这几个核心组件是如何协作的。我们会构建一个简单的“旅行建议助手”Agent。3.1 第一步创建一个简单的工具Tool工具是 Agent 的手和脚。我们先创建一个模拟的“获取天气”工具。在tools/weather_tool.py中from langchain.tools import tool from typing import Optional tool def get_weather(city: str, date: Optional[str] None) - str: 根据城市和日期查询天气信息。 如果没有提供日期则返回当前天气。 Args: city: 城市名称例如 北京。 date: 日期格式为 YYYY-MM-DD。可选。 Returns: 返回该城市的天气描述字符串。 # 这是一个模拟函数真实场景会调用天气API if date: return f{city}在{date}的天气是晴朗温度25°C。 else: return f{city}当前天气是多云温度22°C。关键点使用tool装饰器LangChain 能自动将其识别为一个可用的工具。文档字符串非常重要大语言模型会根据它来决定何时以及如何调用这个工具。输入参数要有明确的类型提示和说明。3.2 第二步初始化模型和工具列表在main.py中我们开始组装 Agent。import os from langchain_ollama import ChatOllama from tools.weather_tool import get_weather # 1. 初始化模型使用本地 Ollama model ChatOllama(modelllama3.1:8b, temperature0) # 2. 准备工具列表 tools [get_weather] # 3. 将工具绑定到模型创建一个“具备工具调用能力”的模型 model_with_tools model.bind_tools(tools) print(模型和工具初始化完成。)运行一下python main.py如果没有报错说明基础环境 OK。3.3 第三步创建你的第一个简单 Agent使用 LangChain 内置 AgentExecutor在main.py中继续from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain.prompts import ChatPromptTemplate # 4. 定义提示词模板告诉 Agent 它的角色和能力 prompt ChatPromptTemplate.from_messages([ (system, 你是一个有用的旅行助手。请根据用户的问题使用工具来获取信息并给出回答。), (placeholder, {chat_history}), # 预留对话历史的位置 (human, {input}), # 用户输入 (placeholder, {agent_scratchpad}), # Agent 思考过程暂存处 ]) # 5. 创建 Agent agent create_tool_calling_agent( llmmodel_with_tools, promptprompt, toolstools, ) # 6. 创建 Agent 执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 7. 运行 Agent try: response agent_executor.invoke({input: 北京明天天气怎么样}) print(\n--- Agent 回答 ---) print(response[output]) except Exception as e: print(f执行出错: {e})运行并观察 执行python main.py。如果一切正常你应该在控制台看到详细的verbose日志。它会展示类似这样的过程Agent 接收到输入“北京明天天气怎么样”Agent模型思考后决定调用get_weather工具。日志会显示它准备传入的参数city“北京” date“明天对应的日期”。工具被执行返回模拟的天气结果。Agent 将工具结果整合生成最终回答“北京在YYYY-MM-DD的天气是晴朗温度25°C。”恭喜你已经创建了一个最基本的、能根据问题自动选择并调用工具的 AI Agent。这个 Agent 的核心是 LangChain 的AgentExecutor它帮你处理了“模型思考 - 决定调用工具 - 执行工具 - 将结果返回给模型 - 模型生成最终回答”的循环。3.4 第四步当简单链不够用引入 LangGraph上面的AgentExecutor对于线性任务很好用。但如果任务复杂呢比如用户问“我想去一个温暖的海边城市度假预算不高有什么推荐吗并告诉我那里下周的天气。”这个任务需要1) 查询符合“温暖”、“海边”、“预算低”条件的城市可能需调用一个“城市推荐”工具。2) 对推荐出的每个城市调用“获取天气”工具。这是一个有条件分支和潜在循环的任务。这时AgentExecutor的线性控制流就显得力不从心。我们需要LangGraph。LangGraph 核心思想将工作流定义为一个“图”Graph图中的节点Node是执行步骤可以是调用模型、运行工具、判断条件边Edge决定了步骤之间的流转逻辑。我们来构建一个简化版的“旅行规划”工作流。在workflows/travel_agent.py中from typing import TypedDict, Annotated, List import operator from langgraph.graph import StateGraph, END from langchain_ollama import ChatOllama from langchain.prompts import ChatPromptTemplate # 1. 定义工作流的“状态”State。这是一个全局共享的数据结构。 class AgentState(TypedDict): # 用户原始问题 user_query: str # 模型/工具链产生的消息列表 messages: Annotated[List, operator.add] # 用于存储中间结果如推荐的城市列表 recommended_cities: List[str] # 最终收集的天气信息 weather_info: List[str] # 2. 初始化模型和工具这里复用之前的工具假设我们还有一个 recommend_city 工具 model ChatOllama(modelllama3.1:8b, temperature0) # ... 假设已定义 get_weather 和 recommend_city 工具 ... # 3. 定义各个节点Node函数 def recommend_city_node(state: AgentState): 节点调用工具推荐城市 prompt ChatPromptTemplate.from_messages([ (system, 你是一个旅行规划助手。根据用户需求推荐城市。), (human, {query}), ]) chain prompt | model.bind_tools([recommend_city_tool]) response chain.invoke({query: state[user_query]}) # 这里需要解析 response提取出推荐的城市列表放入 state # 为简化我们模拟结果 state[recommended_cities] [三亚, 厦门] state[messages].append(response) return state def fetch_weather_node(state: AgentState): 节点为每个推荐城市获取天气 weather_results [] for city in state[recommended_cities]: # 调用天气工具 weather get_weather.invoke({city: city, date: 下周}) # 简化日期 weather_results.append(f{city}: {weather}) state[weather_info] weather_results state[messages].append((assistant, f已获取天气信息: {weather_results})) return state def generate_final_answer_node(state: AgentState): 节点整合信息生成最终回答 final_prompt f 用户问题{state[user_query]} 推荐城市{state[recommended_cities]} 这些城市下周天气{state[weather_info]} 请生成一份友好的旅行建议总结。 chain ChatPromptTemplate.from_messages([(human, final_prompt)]) | model final_response chain.invoke({}) state[messages].append((assistant, final_response.content)) return state # 4. 构建图Graph workflow StateGraph(AgentState) # 添加节点 workflow.add_node(recommend_city, recommend_city_node) workflow.add_node(fetch_weather, fetch_weather_node) workflow.add_node(generate_answer, generate_final_answer_node) # 设置边的流转逻辑 workflow.set_entry_point(recommend_city) # 从推荐城市开始 workflow.add_edge(recommend_city, fetch_weather) # 推荐完就去查天气 workflow.add_edge(fetch_weather, generate_answer) # 查完天气就生成答案 workflow.add_edge(generate_answer, END) # 生成答案后结束 # 编译图 app workflow.compile() # 5. 运行这个 LangGraph 工作流 if __name__ __main__: initial_state { user_query: 我想去一个温暖的海边城市度假预算不高有什么推荐吗并告诉我那里下周的天气。, messages: [], recommended_cities: [], weather_info: [] } final_state app.invoke(initial_state) for message in final_state[messages]: if isinstance(message, tuple): print(f{message[0]}: {message[1]}) else: print(message.content if hasattr(message, content) else message)这个例子展示了 LangGraph 如何将复杂任务分解为清晰的步骤节点并控制执行流。你可以看到它比单一的AgentExecutor更灵活可以轻松扩展例如增加一个“判断预算是否足够”的条件节点根据结果决定是继续推荐还是直接结束。4. 深入实战连接 MCP 工具与处理常见错误4.1 如何理解和使用 MCPMCP 的目标是标准化工具调用。在实践中你可能会遇到两种角色MCP 服务器Server提供工具的一方。它将工具的功能通过 MCP 协议暴露出来。MCP 客户端Client使用工具的一方。你的 LangChain Agent 可以作为客户端去连接 MCP 服务器。对于初学者一个更实用的切入点是许多符合 MCP 协议的工具已经可以通过langchain-community中的集成来方便地使用。你不需要从零开始搭建 MCP 服务器。例如假设有一个公开的“天气 MCP 服务器”你可能可以这样连接示例代码具体取决于工具实现# 伪代码展示概念 from langchain_community.tools.mcp import MCPTool # 配置连接到 MCP 服务器的信息 weather_mcp_tool MCPTool( server_urlhttp://weather-mcp-server:8000, tool_nameget_weather ) tools.append(weather_mcp_tool)然后这个weather_mcp_tool就可以像我们之前自定义的get_weather工具一样被bind_tools绑定并被 Agent 调用。现阶段建议先掌握如何创建和使用自定义的tool理解工具调用的流程。当需要集成更复杂、更标准化的外部服务时再去深入研究如何部署或连接特定的 MCP 服务器。4.2 你必须知道的常见错误与排查清单在开发过程中你几乎一定会遇到下面这些错误。别慌按顺序排查。错误1Agent stopped due to iteration limit or time limit.或Agent execution terminated due to error.原因这是最常见的问题。Agent 陷入了“思考-调用-思考”的循环或者在某一步出错了。排查开启verboseTrue这是最重要的调试手段查看 Agent 每一步的思考和工具调用输出。检查工具描述模型的“思考”完全依赖于工具的文档字符串。确保你的tool函数下的描述清晰、准确地说明了工具的功能、输入和输出。描述不清会导致模型错误调用或反复调用。简化问题用一个最简单的问题如“今天天气如何”测试看是否能走通单次工具调用。检查模型输出在verbose日志中看模型是否输出了一个格式正确的tool_calls对象。如果没有可能是提示词Prompt不够清晰没有“教会”模型使用工具。错误2Context size exceeded...上下文过长原因对话历史chat_history或中间过程太长超过了模型的最大上下文长度。排查与解决使用verbose确认看看是不是每次调用都把大量历史信息传给了模型。精简历史对于 LangGraph确保你的State设计是高效的只保留必要信息。对于AgentExecutor可以考虑使用ConversationBufferWindowMemory来只保留最近几轮对话。总结历史对于长对话可以实现一个“总结”节点在 LangGraph 中定期将冗长的历史压缩成摘要。错误3工具调用失败返回非预期结果或异常原因工具函数本身执行出错或者返回的数据格式让模型无法理解。排查独立测试工具在 Agent 之外直接调用你的工具函数传入各种参数看它是否能正确返回。检查输入参数在verbose日志中查看模型传给工具的参数值是否正确。类型错误、格式错误是常见原因。工具返回需为字符串tool装饰的函数必须返回字符串或可转换为字符串的对象。如果返回复杂字典或对象模型可能无法处理。错误4ModuleNotFoundError: No module named langchain_xxx原因包没安装对。LangChain 生态的包名经常变化。解决使用pip list | grep langchain查看已安装的包。仔细核对官方文档或教程中使用的包名。langchain-communitylangchain-openailangchain-ollama等都是独立的包。错误5LangGraph 工作流卡住或不按预期执行原因图的边Edge逻辑定义有误或者某个节点函数没有正确修改或返回state。排查可视化你的图LangGraph 支持将工作流导出为图片这是调试的神器。from langgraph.graph import StateGraph # ... 构建你的 workflow ... app workflow.compile() # 导出为 PNG app.get_graph().draw_mermaid_png(output_file_pathmy_workflow.png)检查节点返回值每个节点函数都必须返回更新后的state字典。检查条件边如果你使用了add_conditional_edges确保你的条件函数返回的下一个节点名称是图中存在的。5. 从 Demo 到项目架构与进阶思考当你跑通第一个 Agent 后下一步就是思考如何把它变成一个可维护、可扩展的项目。5.1 项目结构优化回顾第 2.4 节的目录并进一步细化agents/存放不同功能的 Agent 定义使用create_tool_calling_agent创建的部分。chains/存放一些可复用的简单链Prompt Model。tools/按领域分类存放工具如tools/weather/,tools/search/。复杂的工具可以考虑封装成简单的 MCP 服务器。config/使用pydantic或python-dotenv管理配置区分开发和生产环境。tests/为你的工具和关键工作流节点编写单元测试。5.2 生产环境考量稳定性错误处理与重试在工具调用和模型调用层添加重试逻辑如使用tenacity库。超时控制为每个工具调用和模型调用设置超时避免单个步骤卡死整个 Agent。降级方案当核心工具如天气 API失败时是否有备用数据源或友好的默认回复可观测性结构化日志不要只依赖verboseTrue。集成像structlog这样的库将 Agent 的执行步骤、工具调用参数和结果、耗时等信息以 JSON 格式记录下来方便后续监控和分析。追踪Tracing使用 LangSmithLangChain 官方平台或 OpenTelemetry 来可视化整个 Agent 的调用链这对于调试复杂工作流至关重要。性能缓存对模型响应和工具结果进行适当缓存例如相同城市一小时内不再重复查询天气减少开销和延迟。异步如果工作流中多个步骤可以并行例如为多个城市同时查询天气考虑使用 LangGraph 的异步支持或asyncio来提升效率。5.3 关于 MCP 的深入方向当你需要让 Agent 使用公司内部系统、特定数据库或复杂 API 时MCP 的价值就凸显了。开发 MCP 服务器你可以用任何语言Python, JavaScript, Go 等编写一个符合 MCP 协议的服务器将内部能力“工具化”。安全性MCP 协议设计时考虑了安全性比如工具调用的权限控制、输入输出审计。在生产中这是连接企业内部工具时必须评估的。动态工具发现高级的 Agent 可以在运行时从 MCP 服务器动态发现可用的新工具而无需重启应用。5.4 持续学习路径官方文档是第一位docs.langchain.com和langchain-ai.github.io/langgraph/是核心资料。先看概念指南Concepts再查 API 参考。从模板和案例入手LangChain 和 LangGraph 的 GitHub 仓库有大量示例cookbook。克隆下来运行并修改它们比从头开始写更快。加入社区遇到具体错误时在 LangChain Discord 或相关 GitHub Issues 中搜索很多坑已经有人踩过。关注演进这个领域迭代极快。关注核心库的 Release Notes了解新特性和不兼容的变更。最后也是最关键的建议不要试图一次性构建一个全能的超级 Agent。从一个具体、微小但完整的问题开始比如“查询天气并建议是否带伞”把它做透跑通“用户输入 - 模型思考 - 工具调用 - 结果整合 - 输出回答”的完整闭环。在这个小闭环中你会遇到并解决 90% 的基础问题。之后再逐步增加工具、引入 LangGraph 处理复杂流程、考虑连接 MCP 服务器你的 AI 应用开发之路就会清晰而扎实。 从零构建AI Agent：LangChain、LangGraph与MCP实战指南
1. 先搞清楚 LangChain、MCP、LangGraph 和 Agent 到底能帮你做什么如果你刚开始接触 AI 应用开发看到 LangChain、MCP、LangGraph、Agent 这些词第一反应可能是“概念好多无从下手”。这很正常因为每个词都代表一个不同的层次和工具。别急着去背定义我们先从最实际的问题出发它们合在一起能帮你解决什么具体问题简单来说这套组合能让你用代码快速搭建一个能“思考”和“行动”的 AI 应用。这里的“思考”指的是让大语言模型比如 GPT、Claude 或本地部署的模型理解你的指令、规划步骤“行动”指的是让模型能调用外部工具比如查数据库、读文件、调用 API、执行计算。而 LangChain、MCP、LangGraph 就是帮你把“思考”和“行动”组织起来的脚手架。LangChain是基础框架。它提供了和大模型对话、管理对话历史记忆、以及连接各种工具Tools的标准方法。你可以把它想象成乐高积木的底板和基础连接件。MCPModel Context Protocol是工具连接协议。它定义了一种标准方式让你开发的 AI 应用能安全、规范地调用外部工具比如一个查询天气的 API或者一个读取本地文件的函数。MCP 解决了“如何让模型安全地使用工具”这个核心问题。LangGraph是高级流程控制器。当你的 AI 应用逻辑变复杂需要根据模型输出的结果决定下一步做什么比如先查天气再根据天气决定推荐室内还是室外活动这种带“分支”和“循环”的流程用基础的 LangChain 链Chain写起来会很别扭。LangGraph 允许你用“图”的方式来定义这种有状态的、多步骤的工作流让复杂 Agent 的逻辑变得清晰可控。Agent是最终呈现的智能体。它是基于以上所有组件构建出来的、能够自主理解目标、规划并执行一系列工具调用以完成任务的 AI 程序。一个强大的 Agent 背后通常离不开 LangGraph 的流程编排和 MCP 的工具支持。所以这个教程的核心价值是从零开始手把手教你用这些业界主流工具搭建一个真正能跑起来的、功能清晰的 AI Agent而不仅仅是跑通一个“Hello World”的对话示例。你会学到如何组织代码、如何连接工具、如何控制执行流程以及如何排查那些让新手头疼的典型错误。2. 环境准备别在依赖和版本上踩第一个坑在写第一行业务代码之前把环境理顺能避免 80% 的莫名报错。我们不追求最新版本而是追求一个稳定、兼容的起步环境。2.1 基础 Python 环境我强烈建议使用Python 3.10 或 3.11。Python 3.12 对一些库的兼容性可能还在完善中新手先避开。使用conda或venv创建独立的虚拟环境是必须的。# 使用 conda 创建环境推荐 conda create -n langchain-demo python3.11 conda activate langchain-demo # 或者使用 venv python -m venv venv # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate2.2 核心库安装通过 pip 安装核心库。注意langchain是一个元包我们通常需要安装更具体的子包和社区集成包。pip install langchain langchain-community langchain-core关键解释langchain-core: 包含最核心的抽象基类和运行时。大部分情况下你通过其他包间接使用它。langchain: 包含标准接口、链和基础工具的实现。langchain-community: 这是非常重要的包包含了大量第三方工具的集成比如与各种数据库、API 的连接器。很多教程里提到的工具Tool都来自这里。接下来安装 LangGraph它是构建复杂 Agent 工作流的关键pip install langgraph对于 MCP目前它更像一个协议标准和一套开发工具集。你可能需要安装mcp客户端库或相关 SDK 来创建或连接 MCP 服务器。由于 MCP 生态在快速演进一个稳妥的起步方式是关注 LangChain 官方对 MCP 的支持。通常你可以通过langchain社区工具来调用符合 MCP 协议的工具。2.3 模型访问准备你需要一个能够访问的大语言模型。有两种主要路径使用云端 API如 OpenAI, Anthropic最简单快捷适合学习和原型开发。pip install openai langchain-openai然后需要设置环境变量OPENAI_API_KEY。export OPENAI_API_KEY你的sk-...密钥 # Windows: set OPENAI_API_KEY你的sk-...密钥使用本地模型如通过 Ollama更注重隐私和成本控制适合深入研究和生产部署。# 首先安装并启动 Ollama从官网下载安装包 # 然后拉取一个模型例如 Llama 3.1 ollama pull llama3.1:8b # 安装 LangChain 的 Ollama 集成 pip install langchain-ollama新手建议为了减少环境变量和网络问题的干扰我强烈建议初学者先从本地 Ollama 模型开始。它能让你立刻聚焦于 LangChain 和 LangGraph 的代码逻辑本身而不是卡在 API 密钥配置或网络连通性上。2.4 初始化一个清晰的项目目录不要把所有代码扔在一个文件里。建立清晰的目录结构有助于后续管理工具、工作流和配置。your_agent_project/ ├── tools/ # 存放自定义工具类或 MCP 服务器文件 │ └── weather_tool.py ├── workflows/ # 存放 LangGraph 工作流定义 │ └── travel_agent.py ├── config.py # 配置文件存放模型、API密钥等设置 ├── main.py # 主入口文件 └── requirements.txt在requirements.txt中记录依赖langchain0.1.0 langchain-community0.0.10 langgraph0.0.17 langchain-ollama0.1.03. 从核心概念到第一个能跑的 Agent现在我们跳过理论深水区直接通过代码来理解这几个核心组件是如何协作的。我们会构建一个简单的“旅行建议助手”Agent。3.1 第一步创建一个简单的工具Tool工具是 Agent 的手和脚。我们先创建一个模拟的“获取天气”工具。在tools/weather_tool.py中from langchain.tools import tool from typing import Optional tool def get_weather(city: str, date: Optional[str] None) - str: 根据城市和日期查询天气信息。 如果没有提供日期则返回当前天气。 Args: city: 城市名称例如 北京。 date: 日期格式为 YYYY-MM-DD。可选。 Returns: 返回该城市的天气描述字符串。 # 这是一个模拟函数真实场景会调用天气API if date: return f{city}在{date}的天气是晴朗温度25°C。 else: return f{city}当前天气是多云温度22°C。关键点使用tool装饰器LangChain 能自动将其识别为一个可用的工具。文档字符串非常重要大语言模型会根据它来决定何时以及如何调用这个工具。输入参数要有明确的类型提示和说明。3.2 第二步初始化模型和工具列表在main.py中我们开始组装 Agent。import os from langchain_ollama import ChatOllama from tools.weather_tool import get_weather # 1. 初始化模型使用本地 Ollama model ChatOllama(modelllama3.1:8b, temperature0) # 2. 准备工具列表 tools [get_weather] # 3. 将工具绑定到模型创建一个“具备工具调用能力”的模型 model_with_tools model.bind_tools(tools) print(模型和工具初始化完成。)运行一下python main.py如果没有报错说明基础环境 OK。3.3 第三步创建你的第一个简单 Agent使用 LangChain 内置 AgentExecutor在main.py中继续from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain.prompts import ChatPromptTemplate # 4. 定义提示词模板告诉 Agent 它的角色和能力 prompt ChatPromptTemplate.from_messages([ (system, 你是一个有用的旅行助手。请根据用户的问题使用工具来获取信息并给出回答。), (placeholder, {chat_history}), # 预留对话历史的位置 (human, {input}), # 用户输入 (placeholder, {agent_scratchpad}), # Agent 思考过程暂存处 ]) # 5. 创建 Agent agent create_tool_calling_agent( llmmodel_with_tools, promptprompt, toolstools, ) # 6. 创建 Agent 执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 7. 运行 Agent try: response agent_executor.invoke({input: 北京明天天气怎么样}) print(\n--- Agent 回答 ---) print(response[output]) except Exception as e: print(f执行出错: {e})运行并观察 执行python main.py。如果一切正常你应该在控制台看到详细的verbose日志。它会展示类似这样的过程Agent 接收到输入“北京明天天气怎么样”Agent模型思考后决定调用get_weather工具。日志会显示它准备传入的参数city“北京” date“明天对应的日期”。工具被执行返回模拟的天气结果。Agent 将工具结果整合生成最终回答“北京在YYYY-MM-DD的天气是晴朗温度25°C。”恭喜你已经创建了一个最基本的、能根据问题自动选择并调用工具的 AI Agent。这个 Agent 的核心是 LangChain 的AgentExecutor它帮你处理了“模型思考 - 决定调用工具 - 执行工具 - 将结果返回给模型 - 模型生成最终回答”的循环。3.4 第四步当简单链不够用引入 LangGraph上面的AgentExecutor对于线性任务很好用。但如果任务复杂呢比如用户问“我想去一个温暖的海边城市度假预算不高有什么推荐吗并告诉我那里下周的天气。”这个任务需要1) 查询符合“温暖”、“海边”、“预算低”条件的城市可能需调用一个“城市推荐”工具。2) 对推荐出的每个城市调用“获取天气”工具。这是一个有条件分支和潜在循环的任务。这时AgentExecutor的线性控制流就显得力不从心。我们需要LangGraph。LangGraph 核心思想将工作流定义为一个“图”Graph图中的节点Node是执行步骤可以是调用模型、运行工具、判断条件边Edge决定了步骤之间的流转逻辑。我们来构建一个简化版的“旅行规划”工作流。在workflows/travel_agent.py中from typing import TypedDict, Annotated, List import operator from langgraph.graph import StateGraph, END from langchain_ollama import ChatOllama from langchain.prompts import ChatPromptTemplate # 1. 定义工作流的“状态”State。这是一个全局共享的数据结构。 class AgentState(TypedDict): # 用户原始问题 user_query: str # 模型/工具链产生的消息列表 messages: Annotated[List, operator.add] # 用于存储中间结果如推荐的城市列表 recommended_cities: List[str] # 最终收集的天气信息 weather_info: List[str] # 2. 初始化模型和工具这里复用之前的工具假设我们还有一个 recommend_city 工具 model ChatOllama(modelllama3.1:8b, temperature0) # ... 假设已定义 get_weather 和 recommend_city 工具 ... # 3. 定义各个节点Node函数 def recommend_city_node(state: AgentState): 节点调用工具推荐城市 prompt ChatPromptTemplate.from_messages([ (system, 你是一个旅行规划助手。根据用户需求推荐城市。), (human, {query}), ]) chain prompt | model.bind_tools([recommend_city_tool]) response chain.invoke({query: state[user_query]}) # 这里需要解析 response提取出推荐的城市列表放入 state # 为简化我们模拟结果 state[recommended_cities] [三亚, 厦门] state[messages].append(response) return state def fetch_weather_node(state: AgentState): 节点为每个推荐城市获取天气 weather_results [] for city in state[recommended_cities]: # 调用天气工具 weather get_weather.invoke({city: city, date: 下周}) # 简化日期 weather_results.append(f{city}: {weather}) state[weather_info] weather_results state[messages].append((assistant, f已获取天气信息: {weather_results})) return state def generate_final_answer_node(state: AgentState): 节点整合信息生成最终回答 final_prompt f 用户问题{state[user_query]} 推荐城市{state[recommended_cities]} 这些城市下周天气{state[weather_info]} 请生成一份友好的旅行建议总结。 chain ChatPromptTemplate.from_messages([(human, final_prompt)]) | model final_response chain.invoke({}) state[messages].append((assistant, final_response.content)) return state # 4. 构建图Graph workflow StateGraph(AgentState) # 添加节点 workflow.add_node(recommend_city, recommend_city_node) workflow.add_node(fetch_weather, fetch_weather_node) workflow.add_node(generate_answer, generate_final_answer_node) # 设置边的流转逻辑 workflow.set_entry_point(recommend_city) # 从推荐城市开始 workflow.add_edge(recommend_city, fetch_weather) # 推荐完就去查天气 workflow.add_edge(fetch_weather, generate_answer) # 查完天气就生成答案 workflow.add_edge(generate_answer, END) # 生成答案后结束 # 编译图 app workflow.compile() # 5. 运行这个 LangGraph 工作流 if __name__ __main__: initial_state { user_query: 我想去一个温暖的海边城市度假预算不高有什么推荐吗并告诉我那里下周的天气。, messages: [], recommended_cities: [], weather_info: [] } final_state app.invoke(initial_state) for message in final_state[messages]: if isinstance(message, tuple): print(f{message[0]}: {message[1]}) else: print(message.content if hasattr(message, content) else message)这个例子展示了 LangGraph 如何将复杂任务分解为清晰的步骤节点并控制执行流。你可以看到它比单一的AgentExecutor更灵活可以轻松扩展例如增加一个“判断预算是否足够”的条件节点根据结果决定是继续推荐还是直接结束。4. 深入实战连接 MCP 工具与处理常见错误4.1 如何理解和使用 MCPMCP 的目标是标准化工具调用。在实践中你可能会遇到两种角色MCP 服务器Server提供工具的一方。它将工具的功能通过 MCP 协议暴露出来。MCP 客户端Client使用工具的一方。你的 LangChain Agent 可以作为客户端去连接 MCP 服务器。对于初学者一个更实用的切入点是许多符合 MCP 协议的工具已经可以通过langchain-community中的集成来方便地使用。你不需要从零开始搭建 MCP 服务器。例如假设有一个公开的“天气 MCP 服务器”你可能可以这样连接示例代码具体取决于工具实现# 伪代码展示概念 from langchain_community.tools.mcp import MCPTool # 配置连接到 MCP 服务器的信息 weather_mcp_tool MCPTool( server_urlhttp://weather-mcp-server:8000, tool_nameget_weather ) tools.append(weather_mcp_tool)然后这个weather_mcp_tool就可以像我们之前自定义的get_weather工具一样被bind_tools绑定并被 Agent 调用。现阶段建议先掌握如何创建和使用自定义的tool理解工具调用的流程。当需要集成更复杂、更标准化的外部服务时再去深入研究如何部署或连接特定的 MCP 服务器。4.2 你必须知道的常见错误与排查清单在开发过程中你几乎一定会遇到下面这些错误。别慌按顺序排查。错误1Agent stopped due to iteration limit or time limit.或Agent execution terminated due to error.原因这是最常见的问题。Agent 陷入了“思考-调用-思考”的循环或者在某一步出错了。排查开启verboseTrue这是最重要的调试手段查看 Agent 每一步的思考和工具调用输出。检查工具描述模型的“思考”完全依赖于工具的文档字符串。确保你的tool函数下的描述清晰、准确地说明了工具的功能、输入和输出。描述不清会导致模型错误调用或反复调用。简化问题用一个最简单的问题如“今天天气如何”测试看是否能走通单次工具调用。检查模型输出在verbose日志中看模型是否输出了一个格式正确的tool_calls对象。如果没有可能是提示词Prompt不够清晰没有“教会”模型使用工具。错误2Context size exceeded...上下文过长原因对话历史chat_history或中间过程太长超过了模型的最大上下文长度。排查与解决使用verbose确认看看是不是每次调用都把大量历史信息传给了模型。精简历史对于 LangGraph确保你的State设计是高效的只保留必要信息。对于AgentExecutor可以考虑使用ConversationBufferWindowMemory来只保留最近几轮对话。总结历史对于长对话可以实现一个“总结”节点在 LangGraph 中定期将冗长的历史压缩成摘要。错误3工具调用失败返回非预期结果或异常原因工具函数本身执行出错或者返回的数据格式让模型无法理解。排查独立测试工具在 Agent 之外直接调用你的工具函数传入各种参数看它是否能正确返回。检查输入参数在verbose日志中查看模型传给工具的参数值是否正确。类型错误、格式错误是常见原因。工具返回需为字符串tool装饰的函数必须返回字符串或可转换为字符串的对象。如果返回复杂字典或对象模型可能无法处理。错误4ModuleNotFoundError: No module named langchain_xxx原因包没安装对。LangChain 生态的包名经常变化。解决使用pip list | grep langchain查看已安装的包。仔细核对官方文档或教程中使用的包名。langchain-communitylangchain-openailangchain-ollama等都是独立的包。错误5LangGraph 工作流卡住或不按预期执行原因图的边Edge逻辑定义有误或者某个节点函数没有正确修改或返回state。排查可视化你的图LangGraph 支持将工作流导出为图片这是调试的神器。from langgraph.graph import StateGraph # ... 构建你的 workflow ... app workflow.compile() # 导出为 PNG app.get_graph().draw_mermaid_png(output_file_pathmy_workflow.png)检查节点返回值每个节点函数都必须返回更新后的state字典。检查条件边如果你使用了add_conditional_edges确保你的条件函数返回的下一个节点名称是图中存在的。5. 从 Demo 到项目架构与进阶思考当你跑通第一个 Agent 后下一步就是思考如何把它变成一个可维护、可扩展的项目。5.1 项目结构优化回顾第 2.4 节的目录并进一步细化agents/存放不同功能的 Agent 定义使用create_tool_calling_agent创建的部分。chains/存放一些可复用的简单链Prompt Model。tools/按领域分类存放工具如tools/weather/,tools/search/。复杂的工具可以考虑封装成简单的 MCP 服务器。config/使用pydantic或python-dotenv管理配置区分开发和生产环境。tests/为你的工具和关键工作流节点编写单元测试。5.2 生产环境考量稳定性错误处理与重试在工具调用和模型调用层添加重试逻辑如使用tenacity库。超时控制为每个工具调用和模型调用设置超时避免单个步骤卡死整个 Agent。降级方案当核心工具如天气 API失败时是否有备用数据源或友好的默认回复可观测性结构化日志不要只依赖verboseTrue。集成像structlog这样的库将 Agent 的执行步骤、工具调用参数和结果、耗时等信息以 JSON 格式记录下来方便后续监控和分析。追踪Tracing使用 LangSmithLangChain 官方平台或 OpenTelemetry 来可视化整个 Agent 的调用链这对于调试复杂工作流至关重要。性能缓存对模型响应和工具结果进行适当缓存例如相同城市一小时内不再重复查询天气减少开销和延迟。异步如果工作流中多个步骤可以并行例如为多个城市同时查询天气考虑使用 LangGraph 的异步支持或asyncio来提升效率。5.3 关于 MCP 的深入方向当你需要让 Agent 使用公司内部系统、特定数据库或复杂 API 时MCP 的价值就凸显了。开发 MCP 服务器你可以用任何语言Python, JavaScript, Go 等编写一个符合 MCP 协议的服务器将内部能力“工具化”。安全性MCP 协议设计时考虑了安全性比如工具调用的权限控制、输入输出审计。在生产中这是连接企业内部工具时必须评估的。动态工具发现高级的 Agent 可以在运行时从 MCP 服务器动态发现可用的新工具而无需重启应用。5.4 持续学习路径官方文档是第一位docs.langchain.com和langchain-ai.github.io/langgraph/是核心资料。先看概念指南Concepts再查 API 参考。从模板和案例入手LangChain 和 LangGraph 的 GitHub 仓库有大量示例cookbook。克隆下来运行并修改它们比从头开始写更快。加入社区遇到具体错误时在 LangChain Discord 或相关 GitHub Issues 中搜索很多坑已经有人踩过。关注演进这个领域迭代极快。关注核心库的 Release Notes了解新特性和不兼容的变更。最后也是最关键的建议不要试图一次性构建一个全能的超级 Agent。从一个具体、微小但完整的问题开始比如“查询天气并建议是否带伞”把它做透跑通“用户输入 - 模型思考 - 工具调用 - 结果整合 - 输出回答”的完整闭环。在这个小闭环中你会遇到并解决 90% 的基础问题。之后再逐步增加工具、引入 LangGraph 处理复杂流程、考虑连接 MCP 服务器你的 AI 应用开发之路就会清晰而扎实。