如果最近你在查 LangChain 的资料很容易陷入一种“信息过载却抓不住主线”的感觉一会儿看到 Chain、Agent一会儿看到 ReAct一会儿又是 MCP、Middleware 和 Skills。全网教程不少但很多内容要么只给你一段能跑的代码要么从头到尾在堆概念。学完之后你发现自己依然说不清这些词之间是什么关系更不知道项目里应该先用哪个、后搭哪个。这篇文章想给你一个干净的主线。我会从 LangChain 最核心的“编排层”定位讲起把 ReAct 的思考-行动循环拆开再带你用 Middleware 的思维方式解决日志、重试、限流这些工程化问题然后演示如何把外部工具封装成 MCP Tool再进一步抽象成可复用的 Skills。全程会给出可运行的最小示例和验证方式也会明确告诉你哪些做法更适合本地学习、哪些做法更适合生产环境。我的核心判断是LangChain 本身不提供模型能力也不该变成你项目里的万能胶水。它的价值在于帮你把模型、工具、记忆和流程串成一个可控的 Agent 系统。谁先建立这种“编排者视角”谁就能在 AI Agent 的工程化路上少走一大截弯路。1. 先回答三个最常见的问题LangChain 到底解决什么问题很多初学 AI Agent 的读者第一个困惑就是LangChain 到底是什么为什么有人把它说成“AI 开发框架”又有人说它正在被 LangGraph 取代先给一个保守但准确的判断LangChain 不是一个模型平台而是一套面向 LLM 应用的“编排层”工具链。它替你处理了大量固定动作比如 Prompt 模板拼装、和不同模型提供方的协议对接、输出解析、工具调用、记忆读写以及多步骤 Agent 流程的调度。换句话说模型负责思考LangChain 负责把思考之外那些重复劳动标准化。第二个困惑是 LangChain 和 LangGraph 的区别。简单来说LangChain 早期是 Chain链式 API适合“写死”的线性或少量分支流程LangGraph 则把流程建模成一张有状态的图节点支持条件跳转、循环、人工介入和持久化。当我们讨论 ReAct 这种需要循环决策的 Agent 时LangGraph 的表达力明显更强。可以这样理解Chain 像工厂流水线LangGraph 像带路口的调度系统。这不是谁取代谁而是表达层级的上移。第三个困惑则是我们今天的主题词怎么串起来。我建议按一条主线记忆MCP 是一种让模型访问外部工具的标准协议ReAct 是 Agent 内部“思考-行动-观察”的决策循环Middleware 是对重复横切逻辑日志、重试、追踪的拦截式处理Skills 则是把特定任务的“工具封装 提示词模板 使用约定”打包成模块。这四者解决的不是同一层面的问题但它们会被 LangChain/LangGraph 统一组织在一个 Agent 应用里。把这些边界厘清比单纯记 API 重要得多。2. 从 Chain 到 Agent 再到生态LangChain 里的核心概念先说 Chain。如果你使用过 LangChain 早期版本代码里常有LLMChain它的本质是“Prompt 模板 模型输出”的组合单元。虽然新版中有许多组件被函数化和 LangGraph 节点替代但 Chain 的思维仍然有指导意义把一次模型交互拆成模板、变量、模型调用、输出解析几个可替换的部分。Agent 则是这个思维的延伸。Agent 不再固定执行“用户问题 → 模型回答”的单一流程而是变成一个循环模型有机会调用工具、看到工具返回结果、再次生成下一步动作直到认为可以回答用户。常见形式是 ReAct——推理Reasoning与行动Acting交替进行。它的循环逻辑是模型的推理输出里包含 Next Thought 和 Action然后由代码解析出 Action去调用具体的工具函数把 Observation 返回给模型。真实项目里这一步通常由一个 Agent 框架比如 LangGraph 或 LangChain 的 AgentExecutor来做解析和工具分发。AI Agent 和普通 ChatBot 的区别也在这里。普通 ChatBot 是一次问答Agent 则拥有“工具使用”和“过程控制”能力。没有 Agent 框架时你要自己维护思考历史、工具调用状态、循环次数上限有框架后你需要理解框架的节点和状态设计而不是在回调地狱里撞运气。MCPModel Context Protocol是 2024 年底至今的热词因为很多 Agent 产品都开始用它连接外部服务。它的价值可以类比为 LLM 世界的 USB-C 接口以前每个 Agent 要自己写适配器去调不同服务的 APIMCP 统一了“服务端暴露工具/资源 → 客户端读取并调用”的机制底层走 JSON-RPC 2.0。你若在企业内部集成数据库查询、蓝湖设计稿信息、代码仓库等垂直能力MCP 能显著减少重复对接工作。有关这一结论的解释是MCP Server 只需要实现标准协议任何支持 MCP Client 的 Agent 应用都能复用而不必为每个 Agent 定制 SDK。至于 Skills它多半是一个方法论层面的概念。你可以把 Skill 理解成打包好的“岗位说明书”包括 Skill 触发的场景条件、可调用的工具列表、该领域的背景知识和输出格式要求。LangChain 把这类信息放在 System Prompt 里配合具体工具注册就能组合出不同技能的 Agent。比如“代码审查 Skill”会加载代码规范提示词注册代码扫描工具和仓库查询工具而“数据分析 Skill”则加载数据可视化规范注册 SQL 工具和绘图工具。从代码层面看Skill 工具集 Prompt 约束 流程约定想清楚这一点你就能自己设计 Skill 目录了。3. 环境准备与前置条件本地搭建 LangChain LLM 最小环境本节我们会把环境搭到一个能跑 Mini Agent 的状态。以 Python 为主因为 LangChain 的 Agent、Tool、ChatModel 抽象在 Python 生态最完整。操作系统不限但下面命令默认你在终端环境里使用 Python 3.9 以上版本推荐 3.10 或 3.11。第一步创建独立的虚拟环境。这是最不该跳过的步骤因为 LangChain 生态更新非常快依赖冲突是初学者最常遇到的启动失败原因。python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate python -m pip install --upgrade pip第二步安装核心依赖。建议安装你真正需要的包不要一次性把 langchain 全家桶复制进 requirements。刚起步时只安装三个部分核心框架、模型接入包、环境变量加载工具。若你后面要通过 LangGraph 管理流程再补装 langgraph需要接 MCP 工具时再补装 MCP 适配包。下面给出了一个最小集合pip install langchain-core langchain langchain-community langchain-openai langchain-text-splitters python-dotenv对于想用 LangGraph 编排 ReAct 的读者可以一起安装pip install langgraph langchain-mcp-adapters需要注意版本的保守态度LangChain 发布节奏很快定死某个具体小版本未必有意义但项目落地时一定要把版本记录留档。可以执行pip freeze requirements.txt后续复现环境时用pip install -r requirements.txt恢复。若不固定版本半年后可能因为 API 变动而无法运行早期代码。第三步准备模型 API Key。环境变量是最常见的配置方式不要硬编码在源码里。在项目根目录创建.env文件# .env OPENAI_API_KEY你的密钥然后写一个加载配置的入口# 文件路径src/config.py import os from dotenv import load_dotenv load_dotenv() def get_openai_api_key() - str: api_key os.getenv(OPENAI_API_KEY, ) if not api_key: raise ValueError(未检测到 OPENAI_API_KEY请检查 .env 文件) return api_key第四步验证模型初始化是否成功。这里用一个通用写法适配方换成具体的模型提供商即可# 文件路径src/init_llm.py from langchain_openai import ChatOpenAI from config import get_openai_api_key api_key get_openai_api_key() llm ChatOpenAI(modelgpt-4o-mini, api_keyapi_key, temperature0) response llm.invoke(用一句话介绍 LangChain) print(response.content)如果能看到模型返回说明 LangChain 与模型之间的通道已经打通。若输出包含类似Received APIMessages或者认证错误的日志优先去检查 API Key 是否正确、余额是否充足、网络访问是否通。跑通这一个最小场景后再往上加 Agent 能力。很多教程一上来就贴 Agent 代码结果初学者根本分辨不出是哪一层出的错——模型初始化错误、工具调用语法过期还是模型工具调用能力不足。分层验证是节省时间的关键。4. 用 Middleware 思路处理横切逻辑日志、重试、限流、追踪Middleware 并不是 LangChain 在 Python 生态中的“一等公民 API”——它更多是从 Web 框架引入的一种编程思想。你可能在 LangChain.js 里见过官方术语 Middleware因为在 JS 生态里部分版本支持在模型调用过程中插入拦截逻辑。但在 Python 的 LangChain/LangGraph 里我们实现同样效果的手段通常是 Callback、自定义 Runnable、或 LangGraph 的节点包装。这里需要注意这个区别避免你去文档里找不到统一入口时误以为自己是配置错了。那 Middleware 解决什么问题让我用一个实际场景说明。假设你给公司做了一个内部知识库 Agent用户每次提问都要调用大模型部分请求还会访问数据库工具。上线第一天一切正常第五天几个问题出现了出现 429 限流错误、日志里什么都查不到、某个第三方工具偶发超时导致整个链路失败。如果你把这些逻辑全部写在业务代码里每个 Agent 节点都要重复处理一遍代码会越来越乱。Middleware 的中心思想是把这些横切关注点从业务代码中抽出来放到请求进入核心业务逻辑之前和响应返回之后拦截处理。其调用顺序是固定的收到请求 → 中间件 A 处理 → 中间件 B 处理 → 核心业务 → 中间件 B 善后 → 中间件 A 善后。在 Agent 应用里我们通常关注以下横切点横切关注点典型处理手法放在哪一层日志追踪记录输入输出、耗时时长、token 用量Callback / 节点包装重试处理 429、5xx、瞬时网络错误模型调用外层限流对单用户请求做速率限制API 网关或模型调用前缓存相同提问在有效期内直接返回结果模型调用前审计记录谁在什么时间调用过什么工具工具执行前后下面用一个最小示例展示如何在 LangChain 里包装模型调用实现“输出日志 自动重试”的中间件效果。这段代码没有依赖任何高级框架核心是自定义 Runnable。# 文件路径src/middleware_demo.py import time from typing import Any from langchain_core.runnables import Runnable from langchain_core.language_models.chat_models import BaseChatModel class LogAndRetryMiddleware(Runnable): def __init__(self, llm: BaseChatModel, max_retries: int 3, base_delay: float 1.0): self.llm llm self.max_retries max_retries self.base_delay base_delay def invoke(self, input: Any, config: Any None) - Any: for attempt in range(1, self.max_retries 1): try: start time.time() result self.llm.invoke(input, configconfig) elapsed time.time() - start print(f[middleware] attempt{attempt} success elapsed{elapsed:.2f}s) return result except Exception as e: if attempt self.max_retries: print(f[middleware] give up after {attempt} attempts, error{e}) raise delay self.base_delay * (2 ** (attempt - 1)) print(f[middleware] attempt{attempt} failed reason{e} next_retry{delay:.1f}s) time.sleep(delay) def build_llm_with_middleware(): from langchain_openai import ChatOpenAI from config import get_openai_api_key api_key get_openai_api_key() raw_llm ChatOpenAI(modelgpt-4o-mini, api_keyapi_key, temperature0) return LogAndRetryMiddleware(raw_llm, max_retries2) if __name__ __main__: middleware_llm build_llm_with_middleware() result middleware_llm.invoke(请说一句中间件测试成功) print(result.content)这段代码的核心价值在于解释一种结构我们不直接调用llm.invoke()而是构造一个实现了 Runnable 接口的包装对象。这个包装对象内部维护原始 LLM并在调用前后注入日志和重试逻辑。你在 LangChain 里经常会看到一个概念叫 Runnable 组合器能被 pipe 起来的前提就是实现统一的invoke/stream/batch接口。理解了这一点看待 LangChain 的 “可组合组件” 时就有了抓手。若要更贴近 Agent 场景可以在 LangGraph 节点外层做同样的包装。你只把节点函数定义好然后定义一个“wrapper” 来包裹所有节点# 伪代码示意LangGraph 节点包装思路 from functools import wraps def with_tracing(node_func): wraps(node_func) async def wrapped(state): print(f[trace] enter node{node_func.__name__}) try: result await node_func(state) print(f[trace] exit node{node_func.__name__}) return result except Exception as e: print(f[trace] error node{node_func.__name__} message{e}) raise return wrapped工程上的建议是不要把中间件逻辑都堆到一个文件里。日志、重试、限流各自抽象成独立 wrapper 或 Runnable 包装类再用一个函数把它们叠加方便单独关闭或替换。新手常见的错误是直接在业务节点里写try...except...结果同样一段重试逻辑复制到了五六个节点里。建议尽早引入统一包装代码会清爽很多。5. ReAct 模式手写 Agent 循环理解它的本质ReAct 才是 AI Agent 的灵魂它提供了一种让模型与工具协作的通用表达。当前框架里大量 Agent 默认都采用了 ReAct 或其变体因此在学 LangChain Agent API 之前我强烈建议先用一个手写循环把 ReAct 跑通。这会让后面的框架学习轻松很多。ReAct 的完整循环通常包含四条关键指令Thought、Action、Action Input、Observation。Thought 是模型对当前状态的推理Action 是模型决定调用的工具名Action Input 是传入该工具的参数Observation 是工具返回的结果。 模型看到 Observation 之后会继续生成下一轮 Thought如此往复直到生成 Final Answer。把它翻译成代码就是下面这个循环# 文件路径src/react_loop.py import json from config import get_openai_api_key from langchain_openai import ChatOpenAI # 1. 定义一个最简单的工具函数 def get_weather(city: str) - str: 一个模拟天气查询工具生产环境应接入真实 API table { 北京: 晴25 摄氏度, 上海: 多云28 摄氏度, 广州: 小雨30 摄氏度, } return table.get(city, 暂无该城市天气数据) TOOLS { get_weather: { description: 查询城市天气, function: get_weather, } } TOOL_SCHEMAS [ { type: function, function: { name: get_weather, description: 查询指定城市当前天气, parameters: { type: object, properties: { city: {type: string, description: 城市名如北京} }, required: [city], }, }, } ] SYSTEM_PROMPT 你是一个会使用工具的回答助手。在回答问题时请严格按如下格式思考 Thought: 描述你的推理过程 Action: 工具名称只能是 get_weather Action Input: {city: 城市名} Observation: 观察工具返回结果 当你已经得到足够信息时输出 Final Answer: 最终回答 def run_react(question: str, max_steps: int 5): api_key get_openai_api_key() llm ChatOpenAI(modelgpt-4o-mini, api_keyapi_key, temperature0) messages [ {role: system, content: SYSTEM_PROMPT}, ] observation_text for step in range(1, max_steps 1): # 2. 把观察结果拼进最新一轮消息 if observation_text: messages.append({role: user, content: fObservation: {observation_text}}) resp llm.invoke(messages) ai_text resp.content print(f\n 第 {step} 轮 ) print(ai_text) messages.append({role: assistant, content: ai_text}) if Final Answer: in ai_text: print(\nReAct 循环结束) break # 3. 从模型输出里解析 Action 和 Action Input try: action_line [line for line in ai_text.splitlines() if line.startswith(Action:)][0] action_input_line [line for line in ai_text.splitlines() if line.startswith(Action Input:)][0] action_name action_line.split(:, 1)[1].strip() action_input_raw action_input_line.split(:, 1)[1].strip() action_args json.loads(action_input_raw) except Exception as e: print(无法解析模型的 action 输出停止循环, e) break # 4. 执行工具 tool TOOLS.get(action_name) if not tool: observation_text f错误未知工具 {action_name} else: observation_text tool[function](**action_args) print(fObservation: {observation_text}) if __name__ __main__: run_react(北京今天天气怎么样需要穿外套吗)这段代码故意没有使用 LangChain 的 AgentExecutor而是保留了最朴素的模型字符串输出解析方式目的是让你看清 ReAct 的本质依赖两样东西模型的工具调用格式约定以及代码对文本的解析执行。真实项目里我们不会一直手写这种脆弱解析使用 LangChain/LangGraph 预置的能力会更稳。但经过手写循环你再去看框架文档里的 Agent 配置时就不会觉得那是一堆魔法了。需要留意的是上面这种“文本格式约定 字符串解析”的做法确实容易遇到模型输出不稳定、Action 参数是单引号 JSON 导致解析失败等情况。更稳的工程做法是用模型原生的 tool calling 能力它让模型输出结构化工具调用参数而不是让开发者从自由文本里解析。下一节会展示更贴近生产的方式。6. 实际工程用 LangGraph 编排 Agent接入 MCP Server 与工具手工 ReAct 循环适合学习若在企业项目里上生产我更推荐用 LangGraph 这样的图编排框架来管理节点和状态。原因不难理解真实 Agent 不只是“思考→调用一个工具→回答”这么简单它可能需要多个工具、多轮人机交互、条件分支、超时回退甚至需要持久化。用 LangGraph 可以显式表达这些流程代码结构比手写 while 循环更清晰。6.1 用 LangGraph 实现一个自带条件路由的 Agent先看一个基于 function calling 的简化版。它的实现思路是Agent 节点根据模型是否生成 tool_calls 来决定下一步走向。如果模型要调用工具就进入 tools 节点如果模型直接给出了最终回答则结束。# 文件路径src/langgraph_agent.py from typing import Literal, TypedDict from langchain_openai import ChatOpenAI from langgraph.graph import END, StateGraph, MessagesState from langgraph.prebuilt import ToolNode def get_weather(city: str) - str: 查询城市天气 table { 北京: 晴25 摄氏度, 上海: 多云28 摄氏度, 广州: 小雨30 摄氏度, } return table.get(city, 暂无该城市天气数据) tools [get_weather] tool_node ToolNode(tools) def create_agent_graph(model: str gpt-4o-mini): from config import get_openai_api_key llm ChatOpenAI(modelmodel, api_keyget_openai_api_key(), temperature0).bind_tools(tools) def should_continue(state: MessagesState) - Literal[tools, end]: last_message state[messages][-1] if getattr(last_message, tool_calls, None): return tools return end def call_model(state: MessagesState): response llm.invoke(state[messages]) return {messages: [response]} graph StateGraph(MessagesState) graph.add_node(agent, call_model) graph.add_node(tools, tool_node) graph.set_entry_point(agent) graph.add_conditional_edges(agent, should_continue, {tools: tools, end: END}) graph.add_edge(tools, agent) return graph.compile() if __name__ __main__: app create_agent_graph() result app.invoke({messages: [{role: user, content: 上海天气怎么样}]}) print(result[messages][-1].content)这个版本的核心结构已经非常接近生产型 Agent 雏形一个 agent 节点调用模型并产生下一步决策一个 tools 节点执行工具并结果返回 agent循环直到模型不再产生 new tool_calls。StateGraph 的节点是普通函数条件边决定状态走向。理解这套“图 状态 条件边”的思维比记住某个 API 名称更有用。6.2 通过 MCP Server 接入外部工具实际上真实项目里的工具不太可能是写死的本地函数而是需要查询内部系统或第三方服务。如果没有统一协议团队每接入一个系统就要写一套对接逻辑。MCP 的出现改变了这个局面。MCP Server 可以将“工具能力”暴露为标准协议格式MCP Client 则负责发现工具、调用工具并返回结果。LangChain 官方社区提供了 MCP 适配层可以让我们把 MCP Server 暴露的工具直接包装成 LangChain Tool。一个非常简化的流程是启动一个 MCP Server如基于 Python 的 FastMCP或 Node 的官方 SDK使用langchain-mcp-adapters中的客户端去连接它把返回的工具列表 load 为 LangChain 工具交给 Agent 使用。下面这段代码假设你已经有一个本地运行的 MCP Server例如它提供了get_order_status这样的工具# 文件路径src/mcp_agent.py import asyncio from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent from langchain_core.prompts import PromptTemplate from config import get_openai_api_key async def run_mcp_agent(question: str): # 假设本地 MCP Server 通过 SSE 监听在 8000 端口 async with MultiServerMCPClient({ order-service: { transport: sse, url: http://127.0.0.1:8000/sse, } }) as client: tools await client.get_tools() llm ChatOpenAI(modelgpt-4o-mini, api_keyget_openai_api_key(), temperature0) prompt PromptTemplate.from_template(你是一个订单查询助手。可用工具{tools}。问题{input}) agent create_react_agent(llm, tools, prompt) result await agent.ainvoke({input: question}) print(result[output]) if __name__ __main__: asyncio.run(run_mcp_agent(帮我查一下订单 10086 的状态))此处需要说明一点MCP 是一个相当年轻的协议标准不同库的 API 设计仍在演进中。以官方文档为最终参考是最稳妥的。若你使用 SSE 传输注意服务端地址必须可被客户端访问不能在云函数里随便写localhost。调试阶段可以先在本地把 Server 和 Agent 都跑起来确认工具能被发现再逐步迁移环境。MCP 对团队协作的另外一个启发是它让“工具生产者”和“Agent 开发者”有了分工。工具生产者只需维护自己的 MCP Server定义清楚工具名、描述、参数结构和权限边界Agent 开发者就能在保持隔离的情况下完成接入。这种解耦若能落地内部每新增一个数据源就不再需要所有 Agent 工程赶工写适配代码了。所以我对 MCP 的判断是它是 Agent 时代最值得关注的基础设施协议之一但落地时需要配套完善的服务治理、可观测性和权限体系。6.3 把 ReAct Agent 沉淀为 Skills工具接好之后下一步是思考模块化。一个大型企业内部往往有多个助手客服助手、售后助手、经营分析助手。它们会共用部分能力但各有各的 Prompt 约定、敏感词限制和业务流程。如果把这些混在一个 Agent 里改一处就可能影响全部。Skills 的作用就是把这些内容边界切开让你可以为同一套模型底座定义多种专家技能。从工程实现角度一个 Skill 至少包含三部分工具集合该 Skill 能调用哪些工具工具描述要写清楚适用条件系统提示词告诉模型你是谁、遵循什么规则、应当怎样组织回答入口约定问题命中哪种场景时才应该激活该 Skill。在 LangGraph 里你不需要所谓的 Skills API 去强行组织只需要把系统提示按 Skill 配置化。典型做法是为每个 Skill 写好独立 Prompt 模板启动 Agent 时根据用户问题意图选择模板和工具子集。以客服和经营分析为例# 文件路径src/skill_registry.py from typing import List def load_skill_prompt(skill_name: str) - str: skills { customer_service: 你是电商客服助手。你的职责是帮助用户解决售前咨询、售后问题、订单状态查询。 你必须遵守 1. 不承诺超出公司政策的赔偿 2. 遇到退款、纠纷相关问题立即升级给人工客服 3. 回答要简洁礼貌。 , data_analysis: 你是经营数据分析师。你的职责是根据用户问题编写查询、读取结果并生成可视化洞察。 你必须遵守 1. 每次分析前明确指标口径 2. 涉及机密数据时只输出脱敏结论 3. 图表配色遵循公司设计规范。 , } return skills.get(skill_name, ) def load_skill_tools(skill_name: str): if skill_name customer_service: return [get_order_status, search_product, create_after_sale_ticket] if skill_name data_analysis: return [query_warehouse, execute_sql, generate_chart] return []真正成熟的 Skill 体系还会配合 Prompt 中结构化说明让模型知道何时切换工具、如何判定能力边界。有人会把这类实现做成独立目录每个 Skill 一个文件夹。项目落地不必引入太重设计先定义清楚输入输出接口和工具白名单就能给后续维护带来可观的收益。7. 如何验证效果与排查问题现在你已经有了多个代码示例接下来要做的是验证。首先确认模型 API Key 可用执行第三节里的最小初始化脚本若打印出模型回复说明通道正常。其次在 ReAct 手写循环里输入“北京今天天气怎么样需要穿外套吗”预期模型会生成 Action 调用 weather 工具然后根据 Observation 给出穿衣建议。LangGraph 版则更为自动直接输出最终回答但在控制台可以加入调试日志来观察节点跳转。这里要特别提醒有些读者觉得模型没有按照 ReAct 格式输出就是 Agent 框架不行其实多数情况下是 Prompt 或模型本身的问题。你可以在调试时打印模型原始输出确认它是否生成了工具调用字段。若模型没有生成 tool_calls优先检查你是否有调用.bind_tools(tools)以及工具函数的名字、描述、参数结构是否清晰。模型感知工具是靠这些描述文本而不是靠注释里的中文说明。另一个常见问题是 Agent 循环陷死模型不断调用工具却迟迟不给出最终回答。解决办法是设定最大循环次数在 LangGraph 中通过 RecursionLimit 或自定义状态字段控制避免无界请求。中间件层的日志在这里是救命稻草它能帮你定位是“模型一直要调用工具”还是“工具结果一直没正确返回给模型”。如果出现 HTTP 429 错误说明你触发了模型服务方限流。优先方案是引入指数退避重试而不是盲目提高并发。如果出现Function xxx is not allowed之类的限制错误请检查你的工具白名单配置。如果出现“MCP 工具无法注册”的报错则优先排查 MCP Server 地址是否可达、服务端是否真正完成了工具声明和权限校验、客户端和适配包的版本是否一致。8. 常见问题与排查速查表问题现象可能原因排查方式解决方案模型返回“未配置 API Key”.env 未正确加载或环境变量名拼写错误在代码里打印 os.getenv(OPENAI_API_KEY) 是否为空确认 .env 文件路径和变量名使用 python-dotenv 加载Agent 调用工具报 404 或 401MCP Server 地址错误、Token 失效用 curl 测试 Server 暴露端口更新地址、Token检查服务端白名单权限工具结果一直不被采纳模型没有把 Observation 传入下一轮消息打印 messages 列表检查历史拼接按框架要求的消息格式返回并确认工具节点输出字段模型不生成 tool_calls工具描述不清晰或未 bind_tools打印工具 schema确认描述里有无错别字用更具体的工具描述必要时示例参数Agent 循环次数过多模型无法判断何时结束增加 max_steps 日志输出观察每轮动作设定更严格的最大循环数并提示模型尽快回答输出不稳定同一问题结果不同temperature 过高或 Prompt 缺乏限定先将 temperature 设为 0 做确定性回归正式评估时用较稳定的配置和用例集本地调 MCP Server 失败localhost 指向错误环境检查 Server 与 Agent 是否同一主机使用局域网 IP 或部署到统一内网实际调试时建议按“自底向上”排查先测单模型调用再测工具函数本身再测工具在 LangChain 里能否被发现最后再跑完整 Agent 流程。多数问题出在前两层直接看 Agent 日志往往会把原因掩盖住。9. 最佳实践与工程落地的几条建议把 LangChain/LangGraph/ReAct/MCP/Skills 这一套工具真正用进团队项目以下几条建议值得留在思考框架里。先关注分层而不是囤积 API。不要把 Model、Prompt、Tool、MCP 注册表全部堆在一处。模型接入层可以是一个 ChatOpenAI 工厂函数工具层可以是独立目录每个工具一个模块MCP Server 则对应独立服务Prompt 与 Skills 进入配置目录Graph 只负责顺序和条件路由。分层清晰后替换模型供应商或切换工具实现时影响面会被限制在小范围内。其次日志和可观测性是 Agent 应用的生命线。建议为每个请求生成 Trace ID并把每次模型调用、工具调用、节点跳转都记录成结构化日志。不要只在print里输出关键动作生产环境应该把日志接入统一日志平台。Agent 的出错常是非确定性的没有完整 trace 等于让线上问题复活后无法定位。然后权限和合规边界必须提前定义。模型能访问哪些工具、能调用哪些接口、能读取哪些字段都应该通过工具注册时的元数据明确控制。企业接入 MCP 时尤其要注意这一点因为一个开放的 MCP Server 可能暴露很多内部能力。最小权限原则不是空话默认拒绝按需放行。敏感操作建议加人工审批节点。再有一点要建立自己的评测集不要只靠“看起来不错”。在日常使用中收集天然问题把问题分成意图类和边界类建立回归用例。每当你调 Prompt、换模型、新增工具都跑一遍既有用例集观察响应质量和稳定性变化。AI 应用的脆弱性往往不来自模型而来自你改了 Prompt 后没人知道之前哪些功能被悄悄影响。关于框架选型还有一个建议是不要人云亦云。如果你的业务只是调用一次不带工具的模型直接用原生的 SDK 就足够了不必为标签而引入 LangChain。如果你要开发一个多步骤、有外部工具和人工审批的 AgentLangGraph 和 MCP 的配合会比纯手写 while 循环稳妥得多。判断标准永远是复杂度与收益是否匹配。最后补充一个易踩的坑不要迷信 LangChain 内置的 AgentExecutor它在简单 demo 中很方便但你需要自己控制节点路由、历史压缩、人工干预时LangGraph 的图结构明显更可控。许多生产级 Agent 最终都往 LangGraph 迁移不是因为“新框架必然好”而是因为真实的业务流程需要显式状态管理。10. 总结与后续学习路线这篇文章围绕一条主线展开LangChain 是 AI 应用的编排层ReAct 是 Agent 的核心决策循环Middleware 思想用来解决日志重试等横切问题MCP 标准化了工具接入Skills 帮助你把不同专家能力封装成模块。你看到的不是一堆孤立概念的展览而是一条从“模型调用”走向“可控 Agent 应用”的工程路径。下一步该怎么继续我建议你按顺序做三件事第一步把文中第 5 节的手写 ReAct 循环改造成自己的天气或其他业务工具熟悉工具定义和循环解析。第二步把 LangGraph 版本跑通试着加入第二个工具并设置条件分支和最大循环次数。第三步部署或找一个本地 MCP Server把一次真实的工具查询接入 Agent通过实际链路感受 MCP 能否解决你的重复对接问题。在你动手的过程中一定会遇到比教程更多的意外情况。先回到自己的项目目标再判断使用 LangChain 的哪部分能力能简化它。选择框架不是目的工程上更快地交付可靠系统才是。如果你正准备在公司内部推广 LangChain Agent 方案建议先挑通一个最小的高频场景比如“查订单 自助答复”打磨好日志、限流、评测和回滚机制后再横向扩展更多技能。这条路看起来不如写一个惊艳 Demo 刺激却能让项目真正存活下来并持续产生价值。建议收藏这篇文章作为你的入门路线图等到实践产出结果后再回头对照理解其中的每一个判断。
LangChain编排实战：从ReAct循环到MCP、Skills的Agent工程化路径
如果最近你在查 LangChain 的资料很容易陷入一种“信息过载却抓不住主线”的感觉一会儿看到 Chain、Agent一会儿看到 ReAct一会儿又是 MCP、Middleware 和 Skills。全网教程不少但很多内容要么只给你一段能跑的代码要么从头到尾在堆概念。学完之后你发现自己依然说不清这些词之间是什么关系更不知道项目里应该先用哪个、后搭哪个。这篇文章想给你一个干净的主线。我会从 LangChain 最核心的“编排层”定位讲起把 ReAct 的思考-行动循环拆开再带你用 Middleware 的思维方式解决日志、重试、限流这些工程化问题然后演示如何把外部工具封装成 MCP Tool再进一步抽象成可复用的 Skills。全程会给出可运行的最小示例和验证方式也会明确告诉你哪些做法更适合本地学习、哪些做法更适合生产环境。我的核心判断是LangChain 本身不提供模型能力也不该变成你项目里的万能胶水。它的价值在于帮你把模型、工具、记忆和流程串成一个可控的 Agent 系统。谁先建立这种“编排者视角”谁就能在 AI Agent 的工程化路上少走一大截弯路。1. 先回答三个最常见的问题LangChain 到底解决什么问题很多初学 AI Agent 的读者第一个困惑就是LangChain 到底是什么为什么有人把它说成“AI 开发框架”又有人说它正在被 LangGraph 取代先给一个保守但准确的判断LangChain 不是一个模型平台而是一套面向 LLM 应用的“编排层”工具链。它替你处理了大量固定动作比如 Prompt 模板拼装、和不同模型提供方的协议对接、输出解析、工具调用、记忆读写以及多步骤 Agent 流程的调度。换句话说模型负责思考LangChain 负责把思考之外那些重复劳动标准化。第二个困惑是 LangChain 和 LangGraph 的区别。简单来说LangChain 早期是 Chain链式 API适合“写死”的线性或少量分支流程LangGraph 则把流程建模成一张有状态的图节点支持条件跳转、循环、人工介入和持久化。当我们讨论 ReAct 这种需要循环决策的 Agent 时LangGraph 的表达力明显更强。可以这样理解Chain 像工厂流水线LangGraph 像带路口的调度系统。这不是谁取代谁而是表达层级的上移。第三个困惑则是我们今天的主题词怎么串起来。我建议按一条主线记忆MCP 是一种让模型访问外部工具的标准协议ReAct 是 Agent 内部“思考-行动-观察”的决策循环Middleware 是对重复横切逻辑日志、重试、追踪的拦截式处理Skills 则是把特定任务的“工具封装 提示词模板 使用约定”打包成模块。这四者解决的不是同一层面的问题但它们会被 LangChain/LangGraph 统一组织在一个 Agent 应用里。把这些边界厘清比单纯记 API 重要得多。2. 从 Chain 到 Agent 再到生态LangChain 里的核心概念先说 Chain。如果你使用过 LangChain 早期版本代码里常有LLMChain它的本质是“Prompt 模板 模型输出”的组合单元。虽然新版中有许多组件被函数化和 LangGraph 节点替代但 Chain 的思维仍然有指导意义把一次模型交互拆成模板、变量、模型调用、输出解析几个可替换的部分。Agent 则是这个思维的延伸。Agent 不再固定执行“用户问题 → 模型回答”的单一流程而是变成一个循环模型有机会调用工具、看到工具返回结果、再次生成下一步动作直到认为可以回答用户。常见形式是 ReAct——推理Reasoning与行动Acting交替进行。它的循环逻辑是模型的推理输出里包含 Next Thought 和 Action然后由代码解析出 Action去调用具体的工具函数把 Observation 返回给模型。真实项目里这一步通常由一个 Agent 框架比如 LangGraph 或 LangChain 的 AgentExecutor来做解析和工具分发。AI Agent 和普通 ChatBot 的区别也在这里。普通 ChatBot 是一次问答Agent 则拥有“工具使用”和“过程控制”能力。没有 Agent 框架时你要自己维护思考历史、工具调用状态、循环次数上限有框架后你需要理解框架的节点和状态设计而不是在回调地狱里撞运气。MCPModel Context Protocol是 2024 年底至今的热词因为很多 Agent 产品都开始用它连接外部服务。它的价值可以类比为 LLM 世界的 USB-C 接口以前每个 Agent 要自己写适配器去调不同服务的 APIMCP 统一了“服务端暴露工具/资源 → 客户端读取并调用”的机制底层走 JSON-RPC 2.0。你若在企业内部集成数据库查询、蓝湖设计稿信息、代码仓库等垂直能力MCP 能显著减少重复对接工作。有关这一结论的解释是MCP Server 只需要实现标准协议任何支持 MCP Client 的 Agent 应用都能复用而不必为每个 Agent 定制 SDK。至于 Skills它多半是一个方法论层面的概念。你可以把 Skill 理解成打包好的“岗位说明书”包括 Skill 触发的场景条件、可调用的工具列表、该领域的背景知识和输出格式要求。LangChain 把这类信息放在 System Prompt 里配合具体工具注册就能组合出不同技能的 Agent。比如“代码审查 Skill”会加载代码规范提示词注册代码扫描工具和仓库查询工具而“数据分析 Skill”则加载数据可视化规范注册 SQL 工具和绘图工具。从代码层面看Skill 工具集 Prompt 约束 流程约定想清楚这一点你就能自己设计 Skill 目录了。3. 环境准备与前置条件本地搭建 LangChain LLM 最小环境本节我们会把环境搭到一个能跑 Mini Agent 的状态。以 Python 为主因为 LangChain 的 Agent、Tool、ChatModel 抽象在 Python 生态最完整。操作系统不限但下面命令默认你在终端环境里使用 Python 3.9 以上版本推荐 3.10 或 3.11。第一步创建独立的虚拟环境。这是最不该跳过的步骤因为 LangChain 生态更新非常快依赖冲突是初学者最常遇到的启动失败原因。python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate python -m pip install --upgrade pip第二步安装核心依赖。建议安装你真正需要的包不要一次性把 langchain 全家桶复制进 requirements。刚起步时只安装三个部分核心框架、模型接入包、环境变量加载工具。若你后面要通过 LangGraph 管理流程再补装 langgraph需要接 MCP 工具时再补装 MCP 适配包。下面给出了一个最小集合pip install langchain-core langchain langchain-community langchain-openai langchain-text-splitters python-dotenv对于想用 LangGraph 编排 ReAct 的读者可以一起安装pip install langgraph langchain-mcp-adapters需要注意版本的保守态度LangChain 发布节奏很快定死某个具体小版本未必有意义但项目落地时一定要把版本记录留档。可以执行pip freeze requirements.txt后续复现环境时用pip install -r requirements.txt恢复。若不固定版本半年后可能因为 API 变动而无法运行早期代码。第三步准备模型 API Key。环境变量是最常见的配置方式不要硬编码在源码里。在项目根目录创建.env文件# .env OPENAI_API_KEY你的密钥然后写一个加载配置的入口# 文件路径src/config.py import os from dotenv import load_dotenv load_dotenv() def get_openai_api_key() - str: api_key os.getenv(OPENAI_API_KEY, ) if not api_key: raise ValueError(未检测到 OPENAI_API_KEY请检查 .env 文件) return api_key第四步验证模型初始化是否成功。这里用一个通用写法适配方换成具体的模型提供商即可# 文件路径src/init_llm.py from langchain_openai import ChatOpenAI from config import get_openai_api_key api_key get_openai_api_key() llm ChatOpenAI(modelgpt-4o-mini, api_keyapi_key, temperature0) response llm.invoke(用一句话介绍 LangChain) print(response.content)如果能看到模型返回说明 LangChain 与模型之间的通道已经打通。若输出包含类似Received APIMessages或者认证错误的日志优先去检查 API Key 是否正确、余额是否充足、网络访问是否通。跑通这一个最小场景后再往上加 Agent 能力。很多教程一上来就贴 Agent 代码结果初学者根本分辨不出是哪一层出的错——模型初始化错误、工具调用语法过期还是模型工具调用能力不足。分层验证是节省时间的关键。4. 用 Middleware 思路处理横切逻辑日志、重试、限流、追踪Middleware 并不是 LangChain 在 Python 生态中的“一等公民 API”——它更多是从 Web 框架引入的一种编程思想。你可能在 LangChain.js 里见过官方术语 Middleware因为在 JS 生态里部分版本支持在模型调用过程中插入拦截逻辑。但在 Python 的 LangChain/LangGraph 里我们实现同样效果的手段通常是 Callback、自定义 Runnable、或 LangGraph 的节点包装。这里需要注意这个区别避免你去文档里找不到统一入口时误以为自己是配置错了。那 Middleware 解决什么问题让我用一个实际场景说明。假设你给公司做了一个内部知识库 Agent用户每次提问都要调用大模型部分请求还会访问数据库工具。上线第一天一切正常第五天几个问题出现了出现 429 限流错误、日志里什么都查不到、某个第三方工具偶发超时导致整个链路失败。如果你把这些逻辑全部写在业务代码里每个 Agent 节点都要重复处理一遍代码会越来越乱。Middleware 的中心思想是把这些横切关注点从业务代码中抽出来放到请求进入核心业务逻辑之前和响应返回之后拦截处理。其调用顺序是固定的收到请求 → 中间件 A 处理 → 中间件 B 处理 → 核心业务 → 中间件 B 善后 → 中间件 A 善后。在 Agent 应用里我们通常关注以下横切点横切关注点典型处理手法放在哪一层日志追踪记录输入输出、耗时时长、token 用量Callback / 节点包装重试处理 429、5xx、瞬时网络错误模型调用外层限流对单用户请求做速率限制API 网关或模型调用前缓存相同提问在有效期内直接返回结果模型调用前审计记录谁在什么时间调用过什么工具工具执行前后下面用一个最小示例展示如何在 LangChain 里包装模型调用实现“输出日志 自动重试”的中间件效果。这段代码没有依赖任何高级框架核心是自定义 Runnable。# 文件路径src/middleware_demo.py import time from typing import Any from langchain_core.runnables import Runnable from langchain_core.language_models.chat_models import BaseChatModel class LogAndRetryMiddleware(Runnable): def __init__(self, llm: BaseChatModel, max_retries: int 3, base_delay: float 1.0): self.llm llm self.max_retries max_retries self.base_delay base_delay def invoke(self, input: Any, config: Any None) - Any: for attempt in range(1, self.max_retries 1): try: start time.time() result self.llm.invoke(input, configconfig) elapsed time.time() - start print(f[middleware] attempt{attempt} success elapsed{elapsed:.2f}s) return result except Exception as e: if attempt self.max_retries: print(f[middleware] give up after {attempt} attempts, error{e}) raise delay self.base_delay * (2 ** (attempt - 1)) print(f[middleware] attempt{attempt} failed reason{e} next_retry{delay:.1f}s) time.sleep(delay) def build_llm_with_middleware(): from langchain_openai import ChatOpenAI from config import get_openai_api_key api_key get_openai_api_key() raw_llm ChatOpenAI(modelgpt-4o-mini, api_keyapi_key, temperature0) return LogAndRetryMiddleware(raw_llm, max_retries2) if __name__ __main__: middleware_llm build_llm_with_middleware() result middleware_llm.invoke(请说一句中间件测试成功) print(result.content)这段代码的核心价值在于解释一种结构我们不直接调用llm.invoke()而是构造一个实现了 Runnable 接口的包装对象。这个包装对象内部维护原始 LLM并在调用前后注入日志和重试逻辑。你在 LangChain 里经常会看到一个概念叫 Runnable 组合器能被 pipe 起来的前提就是实现统一的invoke/stream/batch接口。理解了这一点看待 LangChain 的 “可组合组件” 时就有了抓手。若要更贴近 Agent 场景可以在 LangGraph 节点外层做同样的包装。你只把节点函数定义好然后定义一个“wrapper” 来包裹所有节点# 伪代码示意LangGraph 节点包装思路 from functools import wraps def with_tracing(node_func): wraps(node_func) async def wrapped(state): print(f[trace] enter node{node_func.__name__}) try: result await node_func(state) print(f[trace] exit node{node_func.__name__}) return result except Exception as e: print(f[trace] error node{node_func.__name__} message{e}) raise return wrapped工程上的建议是不要把中间件逻辑都堆到一个文件里。日志、重试、限流各自抽象成独立 wrapper 或 Runnable 包装类再用一个函数把它们叠加方便单独关闭或替换。新手常见的错误是直接在业务节点里写try...except...结果同样一段重试逻辑复制到了五六个节点里。建议尽早引入统一包装代码会清爽很多。5. ReAct 模式手写 Agent 循环理解它的本质ReAct 才是 AI Agent 的灵魂它提供了一种让模型与工具协作的通用表达。当前框架里大量 Agent 默认都采用了 ReAct 或其变体因此在学 LangChain Agent API 之前我强烈建议先用一个手写循环把 ReAct 跑通。这会让后面的框架学习轻松很多。ReAct 的完整循环通常包含四条关键指令Thought、Action、Action Input、Observation。Thought 是模型对当前状态的推理Action 是模型决定调用的工具名Action Input 是传入该工具的参数Observation 是工具返回的结果。 模型看到 Observation 之后会继续生成下一轮 Thought如此往复直到生成 Final Answer。把它翻译成代码就是下面这个循环# 文件路径src/react_loop.py import json from config import get_openai_api_key from langchain_openai import ChatOpenAI # 1. 定义一个最简单的工具函数 def get_weather(city: str) - str: 一个模拟天气查询工具生产环境应接入真实 API table { 北京: 晴25 摄氏度, 上海: 多云28 摄氏度, 广州: 小雨30 摄氏度, } return table.get(city, 暂无该城市天气数据) TOOLS { get_weather: { description: 查询城市天气, function: get_weather, } } TOOL_SCHEMAS [ { type: function, function: { name: get_weather, description: 查询指定城市当前天气, parameters: { type: object, properties: { city: {type: string, description: 城市名如北京} }, required: [city], }, }, } ] SYSTEM_PROMPT 你是一个会使用工具的回答助手。在回答问题时请严格按如下格式思考 Thought: 描述你的推理过程 Action: 工具名称只能是 get_weather Action Input: {city: 城市名} Observation: 观察工具返回结果 当你已经得到足够信息时输出 Final Answer: 最终回答 def run_react(question: str, max_steps: int 5): api_key get_openai_api_key() llm ChatOpenAI(modelgpt-4o-mini, api_keyapi_key, temperature0) messages [ {role: system, content: SYSTEM_PROMPT}, ] observation_text for step in range(1, max_steps 1): # 2. 把观察结果拼进最新一轮消息 if observation_text: messages.append({role: user, content: fObservation: {observation_text}}) resp llm.invoke(messages) ai_text resp.content print(f\n 第 {step} 轮 ) print(ai_text) messages.append({role: assistant, content: ai_text}) if Final Answer: in ai_text: print(\nReAct 循环结束) break # 3. 从模型输出里解析 Action 和 Action Input try: action_line [line for line in ai_text.splitlines() if line.startswith(Action:)][0] action_input_line [line for line in ai_text.splitlines() if line.startswith(Action Input:)][0] action_name action_line.split(:, 1)[1].strip() action_input_raw action_input_line.split(:, 1)[1].strip() action_args json.loads(action_input_raw) except Exception as e: print(无法解析模型的 action 输出停止循环, e) break # 4. 执行工具 tool TOOLS.get(action_name) if not tool: observation_text f错误未知工具 {action_name} else: observation_text tool[function](**action_args) print(fObservation: {observation_text}) if __name__ __main__: run_react(北京今天天气怎么样需要穿外套吗)这段代码故意没有使用 LangChain 的 AgentExecutor而是保留了最朴素的模型字符串输出解析方式目的是让你看清 ReAct 的本质依赖两样东西模型的工具调用格式约定以及代码对文本的解析执行。真实项目里我们不会一直手写这种脆弱解析使用 LangChain/LangGraph 预置的能力会更稳。但经过手写循环你再去看框架文档里的 Agent 配置时就不会觉得那是一堆魔法了。需要留意的是上面这种“文本格式约定 字符串解析”的做法确实容易遇到模型输出不稳定、Action 参数是单引号 JSON 导致解析失败等情况。更稳的工程做法是用模型原生的 tool calling 能力它让模型输出结构化工具调用参数而不是让开发者从自由文本里解析。下一节会展示更贴近生产的方式。6. 实际工程用 LangGraph 编排 Agent接入 MCP Server 与工具手工 ReAct 循环适合学习若在企业项目里上生产我更推荐用 LangGraph 这样的图编排框架来管理节点和状态。原因不难理解真实 Agent 不只是“思考→调用一个工具→回答”这么简单它可能需要多个工具、多轮人机交互、条件分支、超时回退甚至需要持久化。用 LangGraph 可以显式表达这些流程代码结构比手写 while 循环更清晰。6.1 用 LangGraph 实现一个自带条件路由的 Agent先看一个基于 function calling 的简化版。它的实现思路是Agent 节点根据模型是否生成 tool_calls 来决定下一步走向。如果模型要调用工具就进入 tools 节点如果模型直接给出了最终回答则结束。# 文件路径src/langgraph_agent.py from typing import Literal, TypedDict from langchain_openai import ChatOpenAI from langgraph.graph import END, StateGraph, MessagesState from langgraph.prebuilt import ToolNode def get_weather(city: str) - str: 查询城市天气 table { 北京: 晴25 摄氏度, 上海: 多云28 摄氏度, 广州: 小雨30 摄氏度, } return table.get(city, 暂无该城市天气数据) tools [get_weather] tool_node ToolNode(tools) def create_agent_graph(model: str gpt-4o-mini): from config import get_openai_api_key llm ChatOpenAI(modelmodel, api_keyget_openai_api_key(), temperature0).bind_tools(tools) def should_continue(state: MessagesState) - Literal[tools, end]: last_message state[messages][-1] if getattr(last_message, tool_calls, None): return tools return end def call_model(state: MessagesState): response llm.invoke(state[messages]) return {messages: [response]} graph StateGraph(MessagesState) graph.add_node(agent, call_model) graph.add_node(tools, tool_node) graph.set_entry_point(agent) graph.add_conditional_edges(agent, should_continue, {tools: tools, end: END}) graph.add_edge(tools, agent) return graph.compile() if __name__ __main__: app create_agent_graph() result app.invoke({messages: [{role: user, content: 上海天气怎么样}]}) print(result[messages][-1].content)这个版本的核心结构已经非常接近生产型 Agent 雏形一个 agent 节点调用模型并产生下一步决策一个 tools 节点执行工具并结果返回 agent循环直到模型不再产生 new tool_calls。StateGraph 的节点是普通函数条件边决定状态走向。理解这套“图 状态 条件边”的思维比记住某个 API 名称更有用。6.2 通过 MCP Server 接入外部工具实际上真实项目里的工具不太可能是写死的本地函数而是需要查询内部系统或第三方服务。如果没有统一协议团队每接入一个系统就要写一套对接逻辑。MCP 的出现改变了这个局面。MCP Server 可以将“工具能力”暴露为标准协议格式MCP Client 则负责发现工具、调用工具并返回结果。LangChain 官方社区提供了 MCP 适配层可以让我们把 MCP Server 暴露的工具直接包装成 LangChain Tool。一个非常简化的流程是启动一个 MCP Server如基于 Python 的 FastMCP或 Node 的官方 SDK使用langchain-mcp-adapters中的客户端去连接它把返回的工具列表 load 为 LangChain 工具交给 Agent 使用。下面这段代码假设你已经有一个本地运行的 MCP Server例如它提供了get_order_status这样的工具# 文件路径src/mcp_agent.py import asyncio from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent from langchain_core.prompts import PromptTemplate from config import get_openai_api_key async def run_mcp_agent(question: str): # 假设本地 MCP Server 通过 SSE 监听在 8000 端口 async with MultiServerMCPClient({ order-service: { transport: sse, url: http://127.0.0.1:8000/sse, } }) as client: tools await client.get_tools() llm ChatOpenAI(modelgpt-4o-mini, api_keyget_openai_api_key(), temperature0) prompt PromptTemplate.from_template(你是一个订单查询助手。可用工具{tools}。问题{input}) agent create_react_agent(llm, tools, prompt) result await agent.ainvoke({input: question}) print(result[output]) if __name__ __main__: asyncio.run(run_mcp_agent(帮我查一下订单 10086 的状态))此处需要说明一点MCP 是一个相当年轻的协议标准不同库的 API 设计仍在演进中。以官方文档为最终参考是最稳妥的。若你使用 SSE 传输注意服务端地址必须可被客户端访问不能在云函数里随便写localhost。调试阶段可以先在本地把 Server 和 Agent 都跑起来确认工具能被发现再逐步迁移环境。MCP 对团队协作的另外一个启发是它让“工具生产者”和“Agent 开发者”有了分工。工具生产者只需维护自己的 MCP Server定义清楚工具名、描述、参数结构和权限边界Agent 开发者就能在保持隔离的情况下完成接入。这种解耦若能落地内部每新增一个数据源就不再需要所有 Agent 工程赶工写适配代码了。所以我对 MCP 的判断是它是 Agent 时代最值得关注的基础设施协议之一但落地时需要配套完善的服务治理、可观测性和权限体系。6.3 把 ReAct Agent 沉淀为 Skills工具接好之后下一步是思考模块化。一个大型企业内部往往有多个助手客服助手、售后助手、经营分析助手。它们会共用部分能力但各有各的 Prompt 约定、敏感词限制和业务流程。如果把这些混在一个 Agent 里改一处就可能影响全部。Skills 的作用就是把这些内容边界切开让你可以为同一套模型底座定义多种专家技能。从工程实现角度一个 Skill 至少包含三部分工具集合该 Skill 能调用哪些工具工具描述要写清楚适用条件系统提示词告诉模型你是谁、遵循什么规则、应当怎样组织回答入口约定问题命中哪种场景时才应该激活该 Skill。在 LangGraph 里你不需要所谓的 Skills API 去强行组织只需要把系统提示按 Skill 配置化。典型做法是为每个 Skill 写好独立 Prompt 模板启动 Agent 时根据用户问题意图选择模板和工具子集。以客服和经营分析为例# 文件路径src/skill_registry.py from typing import List def load_skill_prompt(skill_name: str) - str: skills { customer_service: 你是电商客服助手。你的职责是帮助用户解决售前咨询、售后问题、订单状态查询。 你必须遵守 1. 不承诺超出公司政策的赔偿 2. 遇到退款、纠纷相关问题立即升级给人工客服 3. 回答要简洁礼貌。 , data_analysis: 你是经营数据分析师。你的职责是根据用户问题编写查询、读取结果并生成可视化洞察。 你必须遵守 1. 每次分析前明确指标口径 2. 涉及机密数据时只输出脱敏结论 3. 图表配色遵循公司设计规范。 , } return skills.get(skill_name, ) def load_skill_tools(skill_name: str): if skill_name customer_service: return [get_order_status, search_product, create_after_sale_ticket] if skill_name data_analysis: return [query_warehouse, execute_sql, generate_chart] return []真正成熟的 Skill 体系还会配合 Prompt 中结构化说明让模型知道何时切换工具、如何判定能力边界。有人会把这类实现做成独立目录每个 Skill 一个文件夹。项目落地不必引入太重设计先定义清楚输入输出接口和工具白名单就能给后续维护带来可观的收益。7. 如何验证效果与排查问题现在你已经有了多个代码示例接下来要做的是验证。首先确认模型 API Key 可用执行第三节里的最小初始化脚本若打印出模型回复说明通道正常。其次在 ReAct 手写循环里输入“北京今天天气怎么样需要穿外套吗”预期模型会生成 Action 调用 weather 工具然后根据 Observation 给出穿衣建议。LangGraph 版则更为自动直接输出最终回答但在控制台可以加入调试日志来观察节点跳转。这里要特别提醒有些读者觉得模型没有按照 ReAct 格式输出就是 Agent 框架不行其实多数情况下是 Prompt 或模型本身的问题。你可以在调试时打印模型原始输出确认它是否生成了工具调用字段。若模型没有生成 tool_calls优先检查你是否有调用.bind_tools(tools)以及工具函数的名字、描述、参数结构是否清晰。模型感知工具是靠这些描述文本而不是靠注释里的中文说明。另一个常见问题是 Agent 循环陷死模型不断调用工具却迟迟不给出最终回答。解决办法是设定最大循环次数在 LangGraph 中通过 RecursionLimit 或自定义状态字段控制避免无界请求。中间件层的日志在这里是救命稻草它能帮你定位是“模型一直要调用工具”还是“工具结果一直没正确返回给模型”。如果出现 HTTP 429 错误说明你触发了模型服务方限流。优先方案是引入指数退避重试而不是盲目提高并发。如果出现Function xxx is not allowed之类的限制错误请检查你的工具白名单配置。如果出现“MCP 工具无法注册”的报错则优先排查 MCP Server 地址是否可达、服务端是否真正完成了工具声明和权限校验、客户端和适配包的版本是否一致。8. 常见问题与排查速查表问题现象可能原因排查方式解决方案模型返回“未配置 API Key”.env 未正确加载或环境变量名拼写错误在代码里打印 os.getenv(OPENAI_API_KEY) 是否为空确认 .env 文件路径和变量名使用 python-dotenv 加载Agent 调用工具报 404 或 401MCP Server 地址错误、Token 失效用 curl 测试 Server 暴露端口更新地址、Token检查服务端白名单权限工具结果一直不被采纳模型没有把 Observation 传入下一轮消息打印 messages 列表检查历史拼接按框架要求的消息格式返回并确认工具节点输出字段模型不生成 tool_calls工具描述不清晰或未 bind_tools打印工具 schema确认描述里有无错别字用更具体的工具描述必要时示例参数Agent 循环次数过多模型无法判断何时结束增加 max_steps 日志输出观察每轮动作设定更严格的最大循环数并提示模型尽快回答输出不稳定同一问题结果不同temperature 过高或 Prompt 缺乏限定先将 temperature 设为 0 做确定性回归正式评估时用较稳定的配置和用例集本地调 MCP Server 失败localhost 指向错误环境检查 Server 与 Agent 是否同一主机使用局域网 IP 或部署到统一内网实际调试时建议按“自底向上”排查先测单模型调用再测工具函数本身再测工具在 LangChain 里能否被发现最后再跑完整 Agent 流程。多数问题出在前两层直接看 Agent 日志往往会把原因掩盖住。9. 最佳实践与工程落地的几条建议把 LangChain/LangGraph/ReAct/MCP/Skills 这一套工具真正用进团队项目以下几条建议值得留在思考框架里。先关注分层而不是囤积 API。不要把 Model、Prompt、Tool、MCP 注册表全部堆在一处。模型接入层可以是一个 ChatOpenAI 工厂函数工具层可以是独立目录每个工具一个模块MCP Server 则对应独立服务Prompt 与 Skills 进入配置目录Graph 只负责顺序和条件路由。分层清晰后替换模型供应商或切换工具实现时影响面会被限制在小范围内。其次日志和可观测性是 Agent 应用的生命线。建议为每个请求生成 Trace ID并把每次模型调用、工具调用、节点跳转都记录成结构化日志。不要只在print里输出关键动作生产环境应该把日志接入统一日志平台。Agent 的出错常是非确定性的没有完整 trace 等于让线上问题复活后无法定位。然后权限和合规边界必须提前定义。模型能访问哪些工具、能调用哪些接口、能读取哪些字段都应该通过工具注册时的元数据明确控制。企业接入 MCP 时尤其要注意这一点因为一个开放的 MCP Server 可能暴露很多内部能力。最小权限原则不是空话默认拒绝按需放行。敏感操作建议加人工审批节点。再有一点要建立自己的评测集不要只靠“看起来不错”。在日常使用中收集天然问题把问题分成意图类和边界类建立回归用例。每当你调 Prompt、换模型、新增工具都跑一遍既有用例集观察响应质量和稳定性变化。AI 应用的脆弱性往往不来自模型而来自你改了 Prompt 后没人知道之前哪些功能被悄悄影响。关于框架选型还有一个建议是不要人云亦云。如果你的业务只是调用一次不带工具的模型直接用原生的 SDK 就足够了不必为标签而引入 LangChain。如果你要开发一个多步骤、有外部工具和人工审批的 AgentLangGraph 和 MCP 的配合会比纯手写 while 循环稳妥得多。判断标准永远是复杂度与收益是否匹配。最后补充一个易踩的坑不要迷信 LangChain 内置的 AgentExecutor它在简单 demo 中很方便但你需要自己控制节点路由、历史压缩、人工干预时LangGraph 的图结构明显更可控。许多生产级 Agent 最终都往 LangGraph 迁移不是因为“新框架必然好”而是因为真实的业务流程需要显式状态管理。10. 总结与后续学习路线这篇文章围绕一条主线展开LangChain 是 AI 应用的编排层ReAct 是 Agent 的核心决策循环Middleware 思想用来解决日志重试等横切问题MCP 标准化了工具接入Skills 帮助你把不同专家能力封装成模块。你看到的不是一堆孤立概念的展览而是一条从“模型调用”走向“可控 Agent 应用”的工程路径。下一步该怎么继续我建议你按顺序做三件事第一步把文中第 5 节的手写 ReAct 循环改造成自己的天气或其他业务工具熟悉工具定义和循环解析。第二步把 LangGraph 版本跑通试着加入第二个工具并设置条件分支和最大循环次数。第三步部署或找一个本地 MCP Server把一次真实的工具查询接入 Agent通过实际链路感受 MCP 能否解决你的重复对接问题。在你动手的过程中一定会遇到比教程更多的意外情况。先回到自己的项目目标再判断使用 LangChain 的哪部分能力能简化它。选择框架不是目的工程上更快地交付可靠系统才是。如果你正准备在公司内部推广 LangChain Agent 方案建议先挑通一个最小的高频场景比如“查订单 自助答复”打磨好日志、限流、评测和回滚机制后再横向扩展更多技能。这条路看起来不如写一个惊艳 Demo 刺激却能让项目真正存活下来并持续产生价值。建议收藏这篇文章作为你的入门路线图等到实践产出结果后再回头对照理解其中的每一个判断。
