在实际 AI 应用开发中我们经常遇到这样的困境大模型本身能力强大但让它稳定、可靠地执行一个包含多步骤、需要调用外部工具或数据的复杂任务却异常困难。简单的提示词调用难以保证执行逻辑的连贯性和准确性而从头开发一套任务调度、工具调用和状态管理的系统又成本高昂。这正是 AI Agent智能体技术要解决的核心问题。它不是一个单一的工具而是一套让大模型具备“自主”完成任务能力的框架体系。本文将围绕 Agent 的核心概念、主流框架 LangChain 的实战应用以及新兴的 Model Context Protocol (MCP) 协议构建一篇从零到一的入门指南。无论你是希望将 AI 能力集成到现有业务系统的开发者还是对智能体开发感兴趣的研究者通过本文你将能够理解 Agent 的工作机制使用 LangChain 搭建一个具备工具调用能力的智能体并了解如何通过 MCP 协议扩展其能力边界。我们会从环境搭建、代码实现、运行验证到常见问题排查提供一个完整、可复现的学习路径。1. 理解 AI Agent超越简单问答的自主执行体在讨论具体技术之前必须厘清“智能体”究竟是什么。它很容易与大模型本身或简单的 API 调用混淆。1.1 Agent 的核心定义与组成一个 AI Agent智能体通常指一个能够感知环境、进行决策并执行动作以实现特定目标的软件实体。在大模型语境下它特指以大语言模型为核心“大脑”结合规划、记忆、工具使用等能力构成的系统。其核心组件包括规划模块将复杂目标分解为可执行的子任务或步骤序列。这通常由大模型通过 Chain-of-Thought 等提示工程技术完成。记忆模块分为短期记忆当前对话上下文和长期记忆通过向量数据库等存储和检索的历史信息使 Agent 能够进行多轮交互并积累知识。工具使用模块这是 Agent 与外部世界交互的关键。Agent 可以调用预定义的工具函数如搜索网络、查询数据库、执行代码、操作文件等从而突破大模型自身在实时性、准确性和操作性上的局限。行动与观察循环Agent 根据当前状态和任务决定下一步行动如调用某个工具执行后观察结果工具返回再基于新状态决定后续行动形成一个思考 - 行动 - 观察的循环直到任务完成或无法继续。1.2 为什么需要 Agent 框架以 LangChain 为例手动实现上述循环是繁琐且易错的。你需要处理提示词模板、管理对话历史、解析模型输出以决定调用哪个工具、处理工具返回结果并重新组织输入给模型。Agent 框架如 LangChain 将这些通用模式抽象成可复用的组件。LangChain 提供了AgentExecutor这个核心类它封装了与模型交互、解析输出、调用工具、处理错误的整个生命周期。开发者只需定义好可用的工具集Tools和选择一种代理类型AgentType框架便会自动构建提示词并管理执行流程。例如当你问一个集成了搜索工具的 Agent “今天北京天气如何”框架会自动构建一个包含工具描述的提示词给模型模型输出类似我需要调用天气查询工具参数是{“location“: “北京“}的指令框架解析后调用真实的天气 API再将结果返回给模型生成最终回答。这一切对开发者是透明的。1.3 MCP 协议工具生态的统一接口随着智能体应用增多一个挑战浮现如何让 Agent 方便、安全地使用各种外部工具和服务每个工具都需要为不同的 Agent 框架LangChain, LlamaIndex, AutoGen 等编写适配器成本很高。Model Context Protocol (MCP) 旨在解决这个问题。它定义了一套标准协议让工具以“服务器”的形式暴露能力而 Agent 框架作为“客户端”可以通过统一的接口发现和调用这些工具。这类似于数据库的 JDBC/ODBC 驱动。对于开发者MCP 的好处是解耦工具开发者只需实现一次 MCP 服务端即可被所有支持 MCP 的客户端使用。动态性Agent 可以在运行时发现并加载新的工具无需重启或修改代码。安全性工具可以运行在独立的进程或环境中通过严格的接口进行控制。在本文后续我们将看到如何利用支持 MCP 的工具来增强 LangChain Agent 的能力。2. 环境准备与项目初始化在开始编写代码前我们需要建立一个稳定、可复现的开发环境。本节将详细说明从 Python 环境、依赖安装到项目结构搭建的每一步。2.1 开发环境与核心依赖我们选择 Python 作为开发语言因为它拥有最丰富的 AI 开发生态。请确保你的系统已安装 Python推荐 3.9 或 3.10 版本某些库对 3.11 可能存在兼容性问题。首先创建一个干净的虚拟环境这是管理项目依赖的最佳实践可以避免包版本冲突。# 创建项目目录并进入 mkdir langchain-agent-tutorial cd langchain-agent-tutorial # 创建虚拟环境使用 venv python -m venv venv # 激活虚拟环境 # 在 Windows 上 venv\Scripts\activate # 在 macOS/Linux 上 source venv/bin/activate激活后命令行提示符前通常会显示(venv)表示你已处于该虚拟环境中。接下来安装核心依赖。我们将使用 LangChain 作为主要框架并选择 OpenAI 的模型作为“大脑”你需要一个 OpenAI API Key。同时我们会安装一些常用的工具库。# 安装 LangChain 核心包和 OpenAI 集成 pip install langchain langchain-openai # 安装用于网页内容提取的工具库示例工具 pip install requests beautifulsoup4 # 安装环境变量管理库用于安全存储 API Key pip install python-dotenv # 可选安装 LangChain 社区包包含更多工具和集成 pip install langchain-community2.2 获取并配置 API 密钥大模型服务通常需要 API 密钥。绝对不要将密钥硬编码在代码中或提交到版本控制系统。我们使用.env文件来管理。在项目根目录下创建一个名为.env的文件内容如下# .env 文件 OPENAI_API_KEY你的-openai-api-key-here # 未来可以添加其他服务的密钥如 # SERPAPI_API_KEYyour_serpapi_key # WEATHER_API_KEYyour_weather_key然后在代码中通过python-dotenv加载这些环境变量。2.3 初始化项目结构与第一个验证脚本建立清晰的项目结构有助于后续开发。建议如下langchain-agent-tutorial/ ├── .env # 环境变量列入.gitignore ├── .gitignore # Git忽略文件 ├── requirements.txt # 项目依赖清单 ├── src/ # 源代码目录 │ ├── __init__.py │ ├── tools/ # 自定义工具定义 │ │ ├── __init__.py │ │ └── custom_tools.py │ ├── agents/ # 智能体定义与执行逻辑 │ │ ├── __init__.py │ │ └── simple_agent.py │ └── utils/ # 工具函数 │ ├── __init__.py │ └── config.py # 配置加载 └── examples/ # 示例脚本 └── 01_verify_env.py现在创建一个最简单的脚本来验证环境是否配置正确。在examples/01_verify_env.py中写入# examples/01_verify_env.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI # 1. 加载 .env 文件中的环境变量 load_dotenv() # 2. 检查 API 密钥是否已加载 api_key os.getenv(OPENAI_API_KEY) if not api_key: print(错误未找到 OPENAI_API_KEY。请检查 .env 文件。) exit(1) print(API 密钥加载成功。) # 3. 初始化一个最简单的 ChatOpenAI 模型实例 # 使用 gpt-3.5-turbo 模型温度设为0输出更确定 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyapi_key) # 4. 进行一次简单的调用测试 try: response llm.invoke(请用一句话介绍你自己。) print(模型调用成功) print(回复, response.content) except Exception as e: print(f模型调用失败错误信息{e}) print(请检查1. API密钥是否正确且有效2. 网络连接3. OpenAI服务状态。)运行这个脚本python examples/01_verify_env.py如果看到类似“模型调用成功”和模型的自我介绍说明你的基础环境Python, LangChain, OpenAI SDK, API Key已经准备就绪。这是所有后续工作的基石。3. 构建你的第一个 LangChain Agent理解了概念并准备好环境后我们开始动手构建一个具备实际功能的智能体。我们将创建一个能够进行简单数学计算和获取网页标题的 Agent。3.1 定义自定义工具工具是 Agent 的手臂。LangChain 提供了多种方式定义工具最简单的是使用tool装饰器。我们在src/tools/custom_tools.py中创建两个工具。# src/tools/custom_tools.py from langchain.tools import tool import requests from bs4 import BeautifulSoup tool def multiply(a: float, b: float) - float: 将两个数字相乘。当用户需要计算乘积时使用此工具。 return a * b tool def get_webpage_title(url: str) - str: 获取给定URL的网页标题。输入必须是一个有效的HTTP或HTTPS URL。 try: # 简单请求不处理复杂情况如JS渲染 headers {User-Agent: Mozilla/5.0} response requests.get(url, headersheaders, timeout10) response.raise_for_status() # 检查HTTP错误 soup BeautifulSoup(response.content, html.parser) title soup.title.string if soup.title else 未找到标题 return title.strip() except requests.exceptions.RequestException as e: return f请求网页时出错{e} except Exception as e: return f解析网页时出错{e}关键解释tool装饰器将普通函数转换为 LangChain 可识别的 Tool 对象。函数的文档字符串...至关重要Agent 依靠它来理解工具的功能和输入格式。描述要清晰准确。函数需要类型注解如a: float这有助于框架进行参数解析。工具内部应包含基本的错误处理返回有意义的错误信息而不是直接抛出异常这有助于 Agent 理解执行状态。3.2 创建并运行智能体接下来我们在src/agents/simple_agent.py中创建 Agent 的执行逻辑。# src/agents/simple_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from src.tools.custom_tools import multiply, get_webpage_title # 加载配置 load_dotenv() def run_agent(question: str): 运行一个简单的 OpenAI Tools Agent 来回答问题。 # 1. 初始化大模型 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyos.getenv(OPENAI_API_KEY)) # 2. 准备工具列表 tools [multiply, get_webpage_title] # 3. 构建提示词模板 # 这是 Agent 运行的核心指令定义了它的角色、能力和格式要求。 prompt ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的助手可以回答问题并使用工具。 如果你需要计算或获取网页信息请使用提供的工具。 当你使用工具时请确保输入参数正确。 如果工具返回错误分析错误并尝试其他方法或直接回答你不知道。 最终答案应清晰、完整。), MessagesPlaceholder(variable_namechat_history), # 预留对话历史的位置 (human, {input}), # 用户当前输入 MessagesPlaceholder(variable_nameagent_scratchpad), # 框架自动填充工具调用和结果 ]) # 4. 创建 Agent # create_openai_tools_agent 专为适配 OpenAI 的 function calling 格式而设计。 agent create_openai_tools_agent(llmllm, toolstools, promptprompt) # 5. 创建执行器 # AgentExecutor 负责处理循环调用agent执行工具将结果返回给agent直到结束。 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 6. 执行任务 print(f\n用户问题{question}) print(*50) result agent_executor.invoke({input: question, chat_history: []}) print(*50) print(f最终答案{result[output]}) if __name__ __main__: # 测试几个问题 test_questions [ “123乘以456等于多少”, “请告诉我清华大学官网的标题是什么网址是 https://www.tsinghua.edu.cn”, “先计算 15 和 25 的乘积然后去查一下 LangChain 官网的标题网址是 https://www.langchain.com” ] for q in test_questions: run_agent(q) print(\n -*70 \n)关键解释与运行提示词模板system消息定义了 Agent 的角色和行为准则。MessagesPlaceholder是 LangChain 的占位符agent_scratchpad会被框架自动填充工具调用和返回的历史这是实现思考循环的关键。Agent 类型create_openai_tools_agent利用了 OpenAI 模型原生的function calling能力模型会输出结构化的工具调用请求这比让模型输出文本再通过正则表达式解析要稳定得多。AgentExecutorverboseTrue会打印出详细的执行步骤对于调试和理解 Agent 的思考过程至关重要。handle_parsing_errorsTrue能优雅地处理模型输出格式错误等问题。执行运行python src/agents/simple_agent.py。观察控制台输出你会看到类似以下的步骤用户问题123乘以456等于多少 进入新的 AgentExecutor 链... 我需要计算 123 和 456 的乘积。动作multiply动作输入{a: 123, b: 456}观察结果56088思考我得到了乘积结果。最终答案123乘以456等于56088。 对于第二个问题你会看到它调用了get_webpage_title工具并返回了网页标题。这个简单的例子展示了 Agent 的核心工作流理解问题 - 规划决定使用工具- 执行工具 - 观察结果 - 合成最终答案。3.3 解析 Agent 的执行流程与关键参数通过verbose输出我们看到了链式调用。下面详细拆解AgentExecutor内部的一次循环格式化输入将用户输入、聊天历史本例为空和系统提示组合成完整的消息列表发送给模型。模型决策模型根据提示词和工具描述决定是生成最终答案还是调用工具。如果是调用工具它会输出一个符合function calling格式的 JSON 对象包含工具名和参数。解析与执行AgentExecutor解析模型输出找到对应的 Tool 对象并使用解析出的参数调用该工具。格式化观察将工具执行的结果observation格式化为一条消息添加到agent_scratchpad中。循环判断将新的消息列表包含工具调用和结果再次发送给模型。模型根据新信息决定下一步。这个过程重复直到模型输出一个不被解析为工具调用的最终答案消息。返回结果将最终答案作为output返回。关键参数调优max_iterations(默认 15): 限制 Agent 的最大循环次数防止陷入死循环。对于复杂任务可能需要调高对于简单任务可以调低以节省成本。early_stopping_method: 设置提前停止条件例如“force“会在达到max_iterations时强制停止并返回当前结果。handle_parsing_errors: 强烈建议设为True。当模型输出不符合工具调用格式时会将错误信息作为观察返回给模型让它有机会自我纠正。temperature: 在初始化ChatOpenAI时设置。对于需要确定性和工具调用的任务通常设为0或较低值如0.1。对于需要创造性的任务可以调高。4. 集成 MCP 协议以扩展工具生态我们已经构建了一个使用自定义工具的 Agent。但维护大量自定义工具成本高且难以复用。MCP 协议允许我们接入一个由社区维护的、不断增长的工具生态。这里我们以一个“文件系统”工具为例展示如何通过 MCP 让 Agent 获得读取本地文件列表的能力。4.1 理解 MCP 的客户端-服务器模型在 MCP 架构中MCP 服务器提供工具。例如一个“文件系统服务器”可以提供list_directory、read_file等工具。服务器通过标准接口通常是 STDIO 或 HTTP暴露这些工具的描述和调用方法。MCP 客户端使用工具。LangChain 可以作为客户端连接到 MCP 服务器动态获取工具列表并在需要时调用它们。我们将使用一个简单的 MCP 服务器示例。首先需要安装 MCP 相关的 Python 包。# 安装 MCP 核心 SDK 和 LangChain 的 MCP 集成 pip install mcp langchain-mcp4.2 启动一个简单的 MCP 服务器为了演示我们创建一个简单的 MCP 服务器它提供一个列出当前目录文件的工具。创建文件mcp_server_demo.py# mcp_server_demo.py import anyio from mcp import Client, Server from mcp.server.models import Tool from typing import List import os # 1. 定义一个工具函数 async def list_files(directory: str “.”) - List[str]: 列出指定目录下的文件和文件夹。 try: files os.listdir(directory) return files except Exception as e: return [f“列出目录时出错{e}”] # 2. 创建 Server 实例并注册工具 async def main(): async with Server(“filesystem-server”) as server: # 将工具函数包装成 MCP Tool 对象 list_files_tool Tool( name“list_files”, description“列出指定目录下的文件和文件夹。”, inputSchema{ “type“: “object“, “properties“: { “directory“: { “type“: “string“, “description“: “要列出的目录路径默认为当前目录。”, } }, }, ) # 注册工具并绑定到实际的函数 server.list_tools() async def handle_list_tools(): return [list_files_tool] server.call_tool() async def handle_call_tool(name: str, arguments: dict): if name “list_files“: result await list_files(**arguments) return { “content“: [{“type“: “text““text“: “ “.join(result)}] } raise ValueError(f“未知工具{name}“) # 3. 通过标准输入输出运行服务器 await server.run(stdioTrue) if __name__ “__main__“: anyio.run(main)这个服务器定义了一个名为list_files的工具并通过标准输入输出stdio暴露其接口。运行它它会等待客户端连接。4.3 在 LangChain Agent 中连接 MCP 服务器现在我们修改之前的 Agent让它连接这个 MCP 服务器并使用其提供的工具。创建src/agents/mcp_agent.py# src/agents/mcp_agent.py import os import asyncio from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_mcp import McpServer, McpTool # 加载配置 load_dotenv() async def run_mcp_agent(question: str): 运行一个集成了 MCP 工具的 Agent。 # 1. 初始化大模型 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0, api_keyos.getenv(“OPENAI_API_KEY”)) # 2. 连接到 MCP 服务器 # 注意这里假设 mcp_server_demo.py 在另一个进程中运行。 # 我们使用子进程的方式启动服务器并连接。 import subprocess # 启动 MCP 服务器进程 server_process subprocess.Popen( [“python”, “mcp_server_demo.py”], stdoutsubprocess.PIPE, stdinsubprocess.PIPE, stderrsubprocess.PIPE, textTrue ) # 给服务器一点启动时间 await asyncio.sleep(2) # 使用 stdio 传输连接到服务器 server McpServer.from_stdio_transport( read_streamserver_process.stdout, write_streamserver_process.stdin, ) # 获取服务器提供的所有工具 mcp_tools await server.list_tools() # 将 MCP 工具转换为 LangChain 可用的 Tool 对象 tools [McpTool.from_mcp_tool(tool) for tool in mcp_tools] # 3. 构建提示词和 Agent与之前类似 prompt ChatPromptTemplate.from_messages([ (“system”, “你是一个可以访问文件系统的助手。你可以使用工具来列出目录内容。请准确回答用户的问题。”), MessagesPlaceholder(variable_name“chat_history”), (“human”, “{input}”), MessagesPlaceholder(variable_name“agent_scratchpad”), ]) agent create_openai_tools_agent(llmllm, toolstools, promptprompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 4. 执行任务 print(f“\n用户问题{question}”) print(““*50) result await agent_executor.ainvoke({“input“: question, “chat_history“: []}) print(““*50) print(f“最终答案{result[‘output’]}”) # 5. 清理关闭服务器连接和进程 await server.close() server_process.terminate() server_process.wait() async def main(): questions [ “列出当前目录下有什么文件”, “查看一下 src 目录里有什么” ] for q in questions: await run_mcp_agent(q) print(“\n” “-“*70 “\n”) if __name__ “__main__“: asyncio.run(main())关键解释动态工具加载代码通过McpServer.from_stdio_transport连接到正在运行的 MCP 服务器并通过list_tools动态获取工具列表。这意味着你无需在代码中硬编码工具只需连接服务器Agent 就能获得新能力。工具转换McpTool.from_mcp_tool将 MCP 协议定义的工具转换为 LangChain 的Tool对象从而无缝集成到现有的 Agent 框架中。异步处理MCP 通信通常是异步的因此我们使用async/await和ainvoke方法。进程管理示例中通过subprocess启动服务器进程。在生产环境中MCP 服务器可能作为独立的守护进程运行客户端通过网络或 socket 连接。运行此脚本前确保mcp_server_demo.py在同一目录下。你将看到 Agent 成功调用了list_files工具并返回了目录列表。这演示了如何通过标准协议扩展 Agent 的能力。5. 生产环境考量与最佳实践将实验性的 Agent 推向生产环境需要关注稳定性、成本、安全性和可维护性。以下是关键的实践建议。5.1 稳定性与错误处理Agent 的自主循环可能出错或陷入死循环。设置迭代限制务必设置max_iterations如 10-20。对于复杂任务可以更高但必须有上限。agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations15, early_stopping_method“force“, # 达到上限后强制停止 handle_parsing_errorsTrue, )全面的工具错误处理工具函数内部必须捕获异常并返回结构化的错误信息而不是抛出异常导致整个 Agent 崩溃。例如网络工具应处理超时、状态码异常数据库工具应处理连接失败。使用 ReAct 等高级模式基础的openai-toolsAgent 已经不错。对于更复杂的场景可以考虑ReAct代理类型它要求模型显式输出“Thought:”, “Action:”, “Observation:” 格式逻辑更清晰有时更稳定。实现看门狗对于长时间运行的任务可以在外部设置超时监控强制终止运行过久的 Agent 实例。5.2 成本控制与性能优化大模型 API 调用是按 Token 计费的Agent 的多轮交互会显著增加 Token 消耗。精选工具只提供必要的工具。过多的工具描述会增加提示词长度也可能干扰模型选择。压缩对话历史对于长对话可以将历史消息进行总结Summarization后再放入上下文而不是全部原始消息。LangChain 提供了ConversationSummaryBufferMemory等记忆组件。使用更便宜的模型进行规划可以采用“小模型规划大模型执行”的策略。例如用gpt-3.5-turbo负责规划步骤和选择工具用gpt-4负责需要深度理解或创作的最后一步。缓存结果对于重复性查询如“今天天气”可以使用LangChain的Cache组件缓存工具调用或模型响应结果。5.3 安全性与权限控制让 Agent 自由调用工具存在风险。工具权限隔离不同的 Agent 实例应配备不同的工具集。一个处理内部数据的 Agent 不应有访问外部网络或执行系统命令的工具。输入验证与净化在工具被调用前对输入参数进行严格验证。例如文件路径工具应检查路径是否在允许的目录范围内SQL 查询工具应禁止DROP,DELETE等危险操作或使用参数化查询。用户身份与审计在生产系统中将用户身份与会话绑定并记录所有 Agent 的思考过程、工具调用和结果用于审计和问题追溯。verboseTrue的输出是重要的日志来源。MCP 服务器的安全确保 MCP 服务器运行在最小权限环境下并且只暴露必要的接口。通过网络连接的 MCP 服务器应使用认证和加密。5.4 可观测性与调试当 Agent 行为不符合预期时需要有手段进行调试。启用详细日志AgentExecutor(verboseTrue)是首要的调试工具。保存这些日志。结构化日志记录将 Agent 的执行步骤输入、模型调用、工具调用、输出以结构化的格式如 JSON记录到日志系统如 ELK Stack便于查询和分析。追踪与监控使用像LangSmithLangChain 官方平台这样的工具它可以可视化 Agent 的整个执行链查看每一步的输入输出、耗时和 Token 使用情况是开发和调试的强大助手。单元测试与集成测试为你的工具函数编写单元测试。为常见的 Agent 任务编写集成测试模拟用户输入并验证输出是否符合预期。6. 常见问题排查清单在开发和使用 Agent 过程中你会遇到各种问题。以下是一个快速排查指南。问题现象可能原因检查步骤解决方案Agent 不调用工具直接回答1. 工具描述不清晰。2. 系统提示词未强调使用工具。3. 模型温度 (temperature) 过高导致输出随机。4. 问题太简单模型认为无需工具。1. 检查工具函数的文档字符串是否准确描述了功能和输入格式。2. 查看verbose日志看模型输出的Thought部分。3. 确认temperature设置建议设为 0。1. 重写工具描述使其更精确。2. 强化系统提示词如“你必须使用工具来回答问题”。3. 将temperature设为 0。4. 在提示词中举例说明工具使用场景。工具调用参数解析错误1. 模型输出的参数格式不对。2. 工具函数参数类型与模型输出不匹配。3.handle_parsing_errors未开启。1. 查看verbose日志中Action Input的原始 JSON。2. 检查工具函数的参数类型注解。1. 确保使用create_openai_tools_agent它利用原生 function calling格式最稳定。2. 开启handle_parsing_errorsTrue让模型有机会纠正。3. 在工具描述中明确参数类型和示例。AgentExecutor报KeyError通常是因为传递给invoke的输入字典缺少AgentExecutor所需的键如input或chat_history。检查调用agent_executor.invoke({...})时传入的字典结构。确保输入字典包含提示词模板中定义的所有variable_name。例如如果模板有{input}和{chat_history}则调用应为invoke({“input“: “问题” “chat_history“: []})。MCP 连接失败1. MCP 服务器未启动或崩溃。2. 传输方式stdio/HTTP配置错误。3. 权限问题。1. 检查 MCP 服务器进程是否在运行。2. 查看服务器日志stderr。3. 确认客户端使用的连接地址和端口。1. 确保先启动服务器再启动客户端。2. 对于 stdio确保正确管道了stdout和stdin。3. 对于网络服务器检查防火墙和网络连通性。上下文长度超限对话历史或工具描述过长导致提示词超出模型上下文窗口。1. 计算提示词的大致 Token 数。2. 查看 API 返回的错误信息。1. 使用对话记忆总结器压缩历史。2. 精简工具描述。3. 升级到支持更长上下文的模型如gpt-4-turbo。4. 实现滑动窗口只保留最近 N 轮对话。工具执行超时或失败1. 工具函数本身有 bug 或网络超时。2. 外部服务不可用。1. 查看工具返回给 Agent 的错误信息。2. 单独测试工具函数。1. 在工具函数内增加超时设置和更细致的异常捕获。2. 返回清晰的错误信息让 Agent 能理解并可能尝试其他方法。3. 为关键工具设置重试机制。7. 扩展方向与下一步学习建议掌握了基础 Agent 的构建后你可以向以下几个方向深入以应对更复杂的场景。1. 使用更强大的预建工具LangChain 社区工具langchain-community包提供了大量现成工具如 Google 搜索 (GoogleSearchRun)、维基百科 (WikipediaQueryRun)、Python REPL 等。直接集成它们能快速赋予 Agent 强大能力。MCP 生态探索社区已有的 MCP 服务器例如用于数据库连接、代码仓库操作、云服务管理的服务器。这可以让你像搭积木一样为 Agent 添加能力。2. 实现多智能体协作复杂任务可以分解给多个各司其职的 Agent 协作完成。例如规划者 Agent负责分解任务。执行者 Agent负责调用工具执行子任务。评审者 Agent负责检查执行结果的质量。 可以使用LangGraphLangChain 的状态机框架或CrewAI、AutoGen等多智能体框架来编排它们之间的交互。3. 增强记忆与知识管理向量数据库记忆将长期记忆存入向量数据库如 Chroma, Pinecone使 Agent 能进行语义搜索记住过去的对话和学到的知识。摘要记忆使用ConversationSummaryMemory自动总结长对话节省上下文空间。知识库检索结合RetrievalQA链让 Agent 在回答前先从你的私有文档库中检索相关信息实现基于知识的问答。4. 与现有系统深度集成将 Agent 作为智能中间件嵌入你的业务系统。作为 API 服务使用 FastAPI 或 Flask 将 Agent 包装成 REST API供前端或其他服务调用。处理工作流让 Agent 监听消息队列如 RabbitMQ, Kafka自动处理特定类型的任务工单。自动化运维结合可观测性数据日志、指标创建能够诊断问题、执行修复脚本的运维 Agent。5. 深入底层原理与定制自定义代理类型研究Agent基类创建完全符合你业务逻辑的代理类型例如强制按特定步骤执行。优化提示工程设计更精妙的系统提示词和少量示例Few-Shot引导模型更可靠地进行规划和工具选择。模型微调如果任务领域非常专业可以考虑使用工具调用数据对基础模型进行微调使其更擅长使用你的特定工具集。从构建一个简单的工具调用 Agent 开始逐步深入到多智能体、长记忆和系统集成你将能够打造出真正强大、自主的 AI 应用。记住始终从一个小而具体的问题开始验证可行性再逐步扩展其能力和边界。 从零构建AI智能体：LangChain实战与MCP协议工具集成指南
在实际 AI 应用开发中我们经常遇到这样的困境大模型本身能力强大但让它稳定、可靠地执行一个包含多步骤、需要调用外部工具或数据的复杂任务却异常困难。简单的提示词调用难以保证执行逻辑的连贯性和准确性而从头开发一套任务调度、工具调用和状态管理的系统又成本高昂。这正是 AI Agent智能体技术要解决的核心问题。它不是一个单一的工具而是一套让大模型具备“自主”完成任务能力的框架体系。本文将围绕 Agent 的核心概念、主流框架 LangChain 的实战应用以及新兴的 Model Context Protocol (MCP) 协议构建一篇从零到一的入门指南。无论你是希望将 AI 能力集成到现有业务系统的开发者还是对智能体开发感兴趣的研究者通过本文你将能够理解 Agent 的工作机制使用 LangChain 搭建一个具备工具调用能力的智能体并了解如何通过 MCP 协议扩展其能力边界。我们会从环境搭建、代码实现、运行验证到常见问题排查提供一个完整、可复现的学习路径。1. 理解 AI Agent超越简单问答的自主执行体在讨论具体技术之前必须厘清“智能体”究竟是什么。它很容易与大模型本身或简单的 API 调用混淆。1.1 Agent 的核心定义与组成一个 AI Agent智能体通常指一个能够感知环境、进行决策并执行动作以实现特定目标的软件实体。在大模型语境下它特指以大语言模型为核心“大脑”结合规划、记忆、工具使用等能力构成的系统。其核心组件包括规划模块将复杂目标分解为可执行的子任务或步骤序列。这通常由大模型通过 Chain-of-Thought 等提示工程技术完成。记忆模块分为短期记忆当前对话上下文和长期记忆通过向量数据库等存储和检索的历史信息使 Agent 能够进行多轮交互并积累知识。工具使用模块这是 Agent 与外部世界交互的关键。Agent 可以调用预定义的工具函数如搜索网络、查询数据库、执行代码、操作文件等从而突破大模型自身在实时性、准确性和操作性上的局限。行动与观察循环Agent 根据当前状态和任务决定下一步行动如调用某个工具执行后观察结果工具返回再基于新状态决定后续行动形成一个思考 - 行动 - 观察的循环直到任务完成或无法继续。1.2 为什么需要 Agent 框架以 LangChain 为例手动实现上述循环是繁琐且易错的。你需要处理提示词模板、管理对话历史、解析模型输出以决定调用哪个工具、处理工具返回结果并重新组织输入给模型。Agent 框架如 LangChain 将这些通用模式抽象成可复用的组件。LangChain 提供了AgentExecutor这个核心类它封装了与模型交互、解析输出、调用工具、处理错误的整个生命周期。开发者只需定义好可用的工具集Tools和选择一种代理类型AgentType框架便会自动构建提示词并管理执行流程。例如当你问一个集成了搜索工具的 Agent “今天北京天气如何”框架会自动构建一个包含工具描述的提示词给模型模型输出类似我需要调用天气查询工具参数是{“location“: “北京“}的指令框架解析后调用真实的天气 API再将结果返回给模型生成最终回答。这一切对开发者是透明的。1.3 MCP 协议工具生态的统一接口随着智能体应用增多一个挑战浮现如何让 Agent 方便、安全地使用各种外部工具和服务每个工具都需要为不同的 Agent 框架LangChain, LlamaIndex, AutoGen 等编写适配器成本很高。Model Context Protocol (MCP) 旨在解决这个问题。它定义了一套标准协议让工具以“服务器”的形式暴露能力而 Agent 框架作为“客户端”可以通过统一的接口发现和调用这些工具。这类似于数据库的 JDBC/ODBC 驱动。对于开发者MCP 的好处是解耦工具开发者只需实现一次 MCP 服务端即可被所有支持 MCP 的客户端使用。动态性Agent 可以在运行时发现并加载新的工具无需重启或修改代码。安全性工具可以运行在独立的进程或环境中通过严格的接口进行控制。在本文后续我们将看到如何利用支持 MCP 的工具来增强 LangChain Agent 的能力。2. 环境准备与项目初始化在开始编写代码前我们需要建立一个稳定、可复现的开发环境。本节将详细说明从 Python 环境、依赖安装到项目结构搭建的每一步。2.1 开发环境与核心依赖我们选择 Python 作为开发语言因为它拥有最丰富的 AI 开发生态。请确保你的系统已安装 Python推荐 3.9 或 3.10 版本某些库对 3.11 可能存在兼容性问题。首先创建一个干净的虚拟环境这是管理项目依赖的最佳实践可以避免包版本冲突。# 创建项目目录并进入 mkdir langchain-agent-tutorial cd langchain-agent-tutorial # 创建虚拟环境使用 venv python -m venv venv # 激活虚拟环境 # 在 Windows 上 venv\Scripts\activate # 在 macOS/Linux 上 source venv/bin/activate激活后命令行提示符前通常会显示(venv)表示你已处于该虚拟环境中。接下来安装核心依赖。我们将使用 LangChain 作为主要框架并选择 OpenAI 的模型作为“大脑”你需要一个 OpenAI API Key。同时我们会安装一些常用的工具库。# 安装 LangChain 核心包和 OpenAI 集成 pip install langchain langchain-openai # 安装用于网页内容提取的工具库示例工具 pip install requests beautifulsoup4 # 安装环境变量管理库用于安全存储 API Key pip install python-dotenv # 可选安装 LangChain 社区包包含更多工具和集成 pip install langchain-community2.2 获取并配置 API 密钥大模型服务通常需要 API 密钥。绝对不要将密钥硬编码在代码中或提交到版本控制系统。我们使用.env文件来管理。在项目根目录下创建一个名为.env的文件内容如下# .env 文件 OPENAI_API_KEY你的-openai-api-key-here # 未来可以添加其他服务的密钥如 # SERPAPI_API_KEYyour_serpapi_key # WEATHER_API_KEYyour_weather_key然后在代码中通过python-dotenv加载这些环境变量。2.3 初始化项目结构与第一个验证脚本建立清晰的项目结构有助于后续开发。建议如下langchain-agent-tutorial/ ├── .env # 环境变量列入.gitignore ├── .gitignore # Git忽略文件 ├── requirements.txt # 项目依赖清单 ├── src/ # 源代码目录 │ ├── __init__.py │ ├── tools/ # 自定义工具定义 │ │ ├── __init__.py │ │ └── custom_tools.py │ ├── agents/ # 智能体定义与执行逻辑 │ │ ├── __init__.py │ │ └── simple_agent.py │ └── utils/ # 工具函数 │ ├── __init__.py │ └── config.py # 配置加载 └── examples/ # 示例脚本 └── 01_verify_env.py现在创建一个最简单的脚本来验证环境是否配置正确。在examples/01_verify_env.py中写入# examples/01_verify_env.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI # 1. 加载 .env 文件中的环境变量 load_dotenv() # 2. 检查 API 密钥是否已加载 api_key os.getenv(OPENAI_API_KEY) if not api_key: print(错误未找到 OPENAI_API_KEY。请检查 .env 文件。) exit(1) print(API 密钥加载成功。) # 3. 初始化一个最简单的 ChatOpenAI 模型实例 # 使用 gpt-3.5-turbo 模型温度设为0输出更确定 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyapi_key) # 4. 进行一次简单的调用测试 try: response llm.invoke(请用一句话介绍你自己。) print(模型调用成功) print(回复, response.content) except Exception as e: print(f模型调用失败错误信息{e}) print(请检查1. API密钥是否正确且有效2. 网络连接3. OpenAI服务状态。)运行这个脚本python examples/01_verify_env.py如果看到类似“模型调用成功”和模型的自我介绍说明你的基础环境Python, LangChain, OpenAI SDK, API Key已经准备就绪。这是所有后续工作的基石。3. 构建你的第一个 LangChain Agent理解了概念并准备好环境后我们开始动手构建一个具备实际功能的智能体。我们将创建一个能够进行简单数学计算和获取网页标题的 Agent。3.1 定义自定义工具工具是 Agent 的手臂。LangChain 提供了多种方式定义工具最简单的是使用tool装饰器。我们在src/tools/custom_tools.py中创建两个工具。# src/tools/custom_tools.py from langchain.tools import tool import requests from bs4 import BeautifulSoup tool def multiply(a: float, b: float) - float: 将两个数字相乘。当用户需要计算乘积时使用此工具。 return a * b tool def get_webpage_title(url: str) - str: 获取给定URL的网页标题。输入必须是一个有效的HTTP或HTTPS URL。 try: # 简单请求不处理复杂情况如JS渲染 headers {User-Agent: Mozilla/5.0} response requests.get(url, headersheaders, timeout10) response.raise_for_status() # 检查HTTP错误 soup BeautifulSoup(response.content, html.parser) title soup.title.string if soup.title else 未找到标题 return title.strip() except requests.exceptions.RequestException as e: return f请求网页时出错{e} except Exception as e: return f解析网页时出错{e}关键解释tool装饰器将普通函数转换为 LangChain 可识别的 Tool 对象。函数的文档字符串...至关重要Agent 依靠它来理解工具的功能和输入格式。描述要清晰准确。函数需要类型注解如a: float这有助于框架进行参数解析。工具内部应包含基本的错误处理返回有意义的错误信息而不是直接抛出异常这有助于 Agent 理解执行状态。3.2 创建并运行智能体接下来我们在src/agents/simple_agent.py中创建 Agent 的执行逻辑。# src/agents/simple_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from src.tools.custom_tools import multiply, get_webpage_title # 加载配置 load_dotenv() def run_agent(question: str): 运行一个简单的 OpenAI Tools Agent 来回答问题。 # 1. 初始化大模型 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyos.getenv(OPENAI_API_KEY)) # 2. 准备工具列表 tools [multiply, get_webpage_title] # 3. 构建提示词模板 # 这是 Agent 运行的核心指令定义了它的角色、能力和格式要求。 prompt ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的助手可以回答问题并使用工具。 如果你需要计算或获取网页信息请使用提供的工具。 当你使用工具时请确保输入参数正确。 如果工具返回错误分析错误并尝试其他方法或直接回答你不知道。 最终答案应清晰、完整。), MessagesPlaceholder(variable_namechat_history), # 预留对话历史的位置 (human, {input}), # 用户当前输入 MessagesPlaceholder(variable_nameagent_scratchpad), # 框架自动填充工具调用和结果 ]) # 4. 创建 Agent # create_openai_tools_agent 专为适配 OpenAI 的 function calling 格式而设计。 agent create_openai_tools_agent(llmllm, toolstools, promptprompt) # 5. 创建执行器 # AgentExecutor 负责处理循环调用agent执行工具将结果返回给agent直到结束。 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 6. 执行任务 print(f\n用户问题{question}) print(*50) result agent_executor.invoke({input: question, chat_history: []}) print(*50) print(f最终答案{result[output]}) if __name__ __main__: # 测试几个问题 test_questions [ “123乘以456等于多少”, “请告诉我清华大学官网的标题是什么网址是 https://www.tsinghua.edu.cn”, “先计算 15 和 25 的乘积然后去查一下 LangChain 官网的标题网址是 https://www.langchain.com” ] for q in test_questions: run_agent(q) print(\n -*70 \n)关键解释与运行提示词模板system消息定义了 Agent 的角色和行为准则。MessagesPlaceholder是 LangChain 的占位符agent_scratchpad会被框架自动填充工具调用和返回的历史这是实现思考循环的关键。Agent 类型create_openai_tools_agent利用了 OpenAI 模型原生的function calling能力模型会输出结构化的工具调用请求这比让模型输出文本再通过正则表达式解析要稳定得多。AgentExecutorverboseTrue会打印出详细的执行步骤对于调试和理解 Agent 的思考过程至关重要。handle_parsing_errorsTrue能优雅地处理模型输出格式错误等问题。执行运行python src/agents/simple_agent.py。观察控制台输出你会看到类似以下的步骤用户问题123乘以456等于多少 进入新的 AgentExecutor 链... 我需要计算 123 和 456 的乘积。动作multiply动作输入{a: 123, b: 456}观察结果56088思考我得到了乘积结果。最终答案123乘以456等于56088。 对于第二个问题你会看到它调用了get_webpage_title工具并返回了网页标题。这个简单的例子展示了 Agent 的核心工作流理解问题 - 规划决定使用工具- 执行工具 - 观察结果 - 合成最终答案。3.3 解析 Agent 的执行流程与关键参数通过verbose输出我们看到了链式调用。下面详细拆解AgentExecutor内部的一次循环格式化输入将用户输入、聊天历史本例为空和系统提示组合成完整的消息列表发送给模型。模型决策模型根据提示词和工具描述决定是生成最终答案还是调用工具。如果是调用工具它会输出一个符合function calling格式的 JSON 对象包含工具名和参数。解析与执行AgentExecutor解析模型输出找到对应的 Tool 对象并使用解析出的参数调用该工具。格式化观察将工具执行的结果observation格式化为一条消息添加到agent_scratchpad中。循环判断将新的消息列表包含工具调用和结果再次发送给模型。模型根据新信息决定下一步。这个过程重复直到模型输出一个不被解析为工具调用的最终答案消息。返回结果将最终答案作为output返回。关键参数调优max_iterations(默认 15): 限制 Agent 的最大循环次数防止陷入死循环。对于复杂任务可能需要调高对于简单任务可以调低以节省成本。early_stopping_method: 设置提前停止条件例如“force“会在达到max_iterations时强制停止并返回当前结果。handle_parsing_errors: 强烈建议设为True。当模型输出不符合工具调用格式时会将错误信息作为观察返回给模型让它有机会自我纠正。temperature: 在初始化ChatOpenAI时设置。对于需要确定性和工具调用的任务通常设为0或较低值如0.1。对于需要创造性的任务可以调高。4. 集成 MCP 协议以扩展工具生态我们已经构建了一个使用自定义工具的 Agent。但维护大量自定义工具成本高且难以复用。MCP 协议允许我们接入一个由社区维护的、不断增长的工具生态。这里我们以一个“文件系统”工具为例展示如何通过 MCP 让 Agent 获得读取本地文件列表的能力。4.1 理解 MCP 的客户端-服务器模型在 MCP 架构中MCP 服务器提供工具。例如一个“文件系统服务器”可以提供list_directory、read_file等工具。服务器通过标准接口通常是 STDIO 或 HTTP暴露这些工具的描述和调用方法。MCP 客户端使用工具。LangChain 可以作为客户端连接到 MCP 服务器动态获取工具列表并在需要时调用它们。我们将使用一个简单的 MCP 服务器示例。首先需要安装 MCP 相关的 Python 包。# 安装 MCP 核心 SDK 和 LangChain 的 MCP 集成 pip install mcp langchain-mcp4.2 启动一个简单的 MCP 服务器为了演示我们创建一个简单的 MCP 服务器它提供一个列出当前目录文件的工具。创建文件mcp_server_demo.py# mcp_server_demo.py import anyio from mcp import Client, Server from mcp.server.models import Tool from typing import List import os # 1. 定义一个工具函数 async def list_files(directory: str “.”) - List[str]: 列出指定目录下的文件和文件夹。 try: files os.listdir(directory) return files except Exception as e: return [f“列出目录时出错{e}”] # 2. 创建 Server 实例并注册工具 async def main(): async with Server(“filesystem-server”) as server: # 将工具函数包装成 MCP Tool 对象 list_files_tool Tool( name“list_files”, description“列出指定目录下的文件和文件夹。”, inputSchema{ “type“: “object“, “properties“: { “directory“: { “type“: “string“, “description“: “要列出的目录路径默认为当前目录。”, } }, }, ) # 注册工具并绑定到实际的函数 server.list_tools() async def handle_list_tools(): return [list_files_tool] server.call_tool() async def handle_call_tool(name: str, arguments: dict): if name “list_files“: result await list_files(**arguments) return { “content“: [{“type“: “text““text“: “ “.join(result)}] } raise ValueError(f“未知工具{name}“) # 3. 通过标准输入输出运行服务器 await server.run(stdioTrue) if __name__ “__main__“: anyio.run(main)这个服务器定义了一个名为list_files的工具并通过标准输入输出stdio暴露其接口。运行它它会等待客户端连接。4.3 在 LangChain Agent 中连接 MCP 服务器现在我们修改之前的 Agent让它连接这个 MCP 服务器并使用其提供的工具。创建src/agents/mcp_agent.py# src/agents/mcp_agent.py import os import asyncio from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_mcp import McpServer, McpTool # 加载配置 load_dotenv() async def run_mcp_agent(question: str): 运行一个集成了 MCP 工具的 Agent。 # 1. 初始化大模型 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0, api_keyos.getenv(“OPENAI_API_KEY”)) # 2. 连接到 MCP 服务器 # 注意这里假设 mcp_server_demo.py 在另一个进程中运行。 # 我们使用子进程的方式启动服务器并连接。 import subprocess # 启动 MCP 服务器进程 server_process subprocess.Popen( [“python”, “mcp_server_demo.py”], stdoutsubprocess.PIPE, stdinsubprocess.PIPE, stderrsubprocess.PIPE, textTrue ) # 给服务器一点启动时间 await asyncio.sleep(2) # 使用 stdio 传输连接到服务器 server McpServer.from_stdio_transport( read_streamserver_process.stdout, write_streamserver_process.stdin, ) # 获取服务器提供的所有工具 mcp_tools await server.list_tools() # 将 MCP 工具转换为 LangChain 可用的 Tool 对象 tools [McpTool.from_mcp_tool(tool) for tool in mcp_tools] # 3. 构建提示词和 Agent与之前类似 prompt ChatPromptTemplate.from_messages([ (“system”, “你是一个可以访问文件系统的助手。你可以使用工具来列出目录内容。请准确回答用户的问题。”), MessagesPlaceholder(variable_name“chat_history”), (“human”, “{input}”), MessagesPlaceholder(variable_name“agent_scratchpad”), ]) agent create_openai_tools_agent(llmllm, toolstools, promptprompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 4. 执行任务 print(f“\n用户问题{question}”) print(““*50) result await agent_executor.ainvoke({“input“: question, “chat_history“: []}) print(““*50) print(f“最终答案{result[‘output’]}”) # 5. 清理关闭服务器连接和进程 await server.close() server_process.terminate() server_process.wait() async def main(): questions [ “列出当前目录下有什么文件”, “查看一下 src 目录里有什么” ] for q in questions: await run_mcp_agent(q) print(“\n” “-“*70 “\n”) if __name__ “__main__“: asyncio.run(main())关键解释动态工具加载代码通过McpServer.from_stdio_transport连接到正在运行的 MCP 服务器并通过list_tools动态获取工具列表。这意味着你无需在代码中硬编码工具只需连接服务器Agent 就能获得新能力。工具转换McpTool.from_mcp_tool将 MCP 协议定义的工具转换为 LangChain 的Tool对象从而无缝集成到现有的 Agent 框架中。异步处理MCP 通信通常是异步的因此我们使用async/await和ainvoke方法。进程管理示例中通过subprocess启动服务器进程。在生产环境中MCP 服务器可能作为独立的守护进程运行客户端通过网络或 socket 连接。运行此脚本前确保mcp_server_demo.py在同一目录下。你将看到 Agent 成功调用了list_files工具并返回了目录列表。这演示了如何通过标准协议扩展 Agent 的能力。5. 生产环境考量与最佳实践将实验性的 Agent 推向生产环境需要关注稳定性、成本、安全性和可维护性。以下是关键的实践建议。5.1 稳定性与错误处理Agent 的自主循环可能出错或陷入死循环。设置迭代限制务必设置max_iterations如 10-20。对于复杂任务可以更高但必须有上限。agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations15, early_stopping_method“force“, # 达到上限后强制停止 handle_parsing_errorsTrue, )全面的工具错误处理工具函数内部必须捕获异常并返回结构化的错误信息而不是抛出异常导致整个 Agent 崩溃。例如网络工具应处理超时、状态码异常数据库工具应处理连接失败。使用 ReAct 等高级模式基础的openai-toolsAgent 已经不错。对于更复杂的场景可以考虑ReAct代理类型它要求模型显式输出“Thought:”, “Action:”, “Observation:” 格式逻辑更清晰有时更稳定。实现看门狗对于长时间运行的任务可以在外部设置超时监控强制终止运行过久的 Agent 实例。5.2 成本控制与性能优化大模型 API 调用是按 Token 计费的Agent 的多轮交互会显著增加 Token 消耗。精选工具只提供必要的工具。过多的工具描述会增加提示词长度也可能干扰模型选择。压缩对话历史对于长对话可以将历史消息进行总结Summarization后再放入上下文而不是全部原始消息。LangChain 提供了ConversationSummaryBufferMemory等记忆组件。使用更便宜的模型进行规划可以采用“小模型规划大模型执行”的策略。例如用gpt-3.5-turbo负责规划步骤和选择工具用gpt-4负责需要深度理解或创作的最后一步。缓存结果对于重复性查询如“今天天气”可以使用LangChain的Cache组件缓存工具调用或模型响应结果。5.3 安全性与权限控制让 Agent 自由调用工具存在风险。工具权限隔离不同的 Agent 实例应配备不同的工具集。一个处理内部数据的 Agent 不应有访问外部网络或执行系统命令的工具。输入验证与净化在工具被调用前对输入参数进行严格验证。例如文件路径工具应检查路径是否在允许的目录范围内SQL 查询工具应禁止DROP,DELETE等危险操作或使用参数化查询。用户身份与审计在生产系统中将用户身份与会话绑定并记录所有 Agent 的思考过程、工具调用和结果用于审计和问题追溯。verboseTrue的输出是重要的日志来源。MCP 服务器的安全确保 MCP 服务器运行在最小权限环境下并且只暴露必要的接口。通过网络连接的 MCP 服务器应使用认证和加密。5.4 可观测性与调试当 Agent 行为不符合预期时需要有手段进行调试。启用详细日志AgentExecutor(verboseTrue)是首要的调试工具。保存这些日志。结构化日志记录将 Agent 的执行步骤输入、模型调用、工具调用、输出以结构化的格式如 JSON记录到日志系统如 ELK Stack便于查询和分析。追踪与监控使用像LangSmithLangChain 官方平台这样的工具它可以可视化 Agent 的整个执行链查看每一步的输入输出、耗时和 Token 使用情况是开发和调试的强大助手。单元测试与集成测试为你的工具函数编写单元测试。为常见的 Agent 任务编写集成测试模拟用户输入并验证输出是否符合预期。6. 常见问题排查清单在开发和使用 Agent 过程中你会遇到各种问题。以下是一个快速排查指南。问题现象可能原因检查步骤解决方案Agent 不调用工具直接回答1. 工具描述不清晰。2. 系统提示词未强调使用工具。3. 模型温度 (temperature) 过高导致输出随机。4. 问题太简单模型认为无需工具。1. 检查工具函数的文档字符串是否准确描述了功能和输入格式。2. 查看verbose日志看模型输出的Thought部分。3. 确认temperature设置建议设为 0。1. 重写工具描述使其更精确。2. 强化系统提示词如“你必须使用工具来回答问题”。3. 将temperature设为 0。4. 在提示词中举例说明工具使用场景。工具调用参数解析错误1. 模型输出的参数格式不对。2. 工具函数参数类型与模型输出不匹配。3.handle_parsing_errors未开启。1. 查看verbose日志中Action Input的原始 JSON。2. 检查工具函数的参数类型注解。1. 确保使用create_openai_tools_agent它利用原生 function calling格式最稳定。2. 开启handle_parsing_errorsTrue让模型有机会纠正。3. 在工具描述中明确参数类型和示例。AgentExecutor报KeyError通常是因为传递给invoke的输入字典缺少AgentExecutor所需的键如input或chat_history。检查调用agent_executor.invoke({...})时传入的字典结构。确保输入字典包含提示词模板中定义的所有variable_name。例如如果模板有{input}和{chat_history}则调用应为invoke({“input“: “问题” “chat_history“: []})。MCP 连接失败1. MCP 服务器未启动或崩溃。2. 传输方式stdio/HTTP配置错误。3. 权限问题。1. 检查 MCP 服务器进程是否在运行。2. 查看服务器日志stderr。3. 确认客户端使用的连接地址和端口。1. 确保先启动服务器再启动客户端。2. 对于 stdio确保正确管道了stdout和stdin。3. 对于网络服务器检查防火墙和网络连通性。上下文长度超限对话历史或工具描述过长导致提示词超出模型上下文窗口。1. 计算提示词的大致 Token 数。2. 查看 API 返回的错误信息。1. 使用对话记忆总结器压缩历史。2. 精简工具描述。3. 升级到支持更长上下文的模型如gpt-4-turbo。4. 实现滑动窗口只保留最近 N 轮对话。工具执行超时或失败1. 工具函数本身有 bug 或网络超时。2. 外部服务不可用。1. 查看工具返回给 Agent 的错误信息。2. 单独测试工具函数。1. 在工具函数内增加超时设置和更细致的异常捕获。2. 返回清晰的错误信息让 Agent 能理解并可能尝试其他方法。3. 为关键工具设置重试机制。7. 扩展方向与下一步学习建议掌握了基础 Agent 的构建后你可以向以下几个方向深入以应对更复杂的场景。1. 使用更强大的预建工具LangChain 社区工具langchain-community包提供了大量现成工具如 Google 搜索 (GoogleSearchRun)、维基百科 (WikipediaQueryRun)、Python REPL 等。直接集成它们能快速赋予 Agent 强大能力。MCP 生态探索社区已有的 MCP 服务器例如用于数据库连接、代码仓库操作、云服务管理的服务器。这可以让你像搭积木一样为 Agent 添加能力。2. 实现多智能体协作复杂任务可以分解给多个各司其职的 Agent 协作完成。例如规划者 Agent负责分解任务。执行者 Agent负责调用工具执行子任务。评审者 Agent负责检查执行结果的质量。 可以使用LangGraphLangChain 的状态机框架或CrewAI、AutoGen等多智能体框架来编排它们之间的交互。3. 增强记忆与知识管理向量数据库记忆将长期记忆存入向量数据库如 Chroma, Pinecone使 Agent 能进行语义搜索记住过去的对话和学到的知识。摘要记忆使用ConversationSummaryMemory自动总结长对话节省上下文空间。知识库检索结合RetrievalQA链让 Agent 在回答前先从你的私有文档库中检索相关信息实现基于知识的问答。4. 与现有系统深度集成将 Agent 作为智能中间件嵌入你的业务系统。作为 API 服务使用 FastAPI 或 Flask 将 Agent 包装成 REST API供前端或其他服务调用。处理工作流让 Agent 监听消息队列如 RabbitMQ, Kafka自动处理特定类型的任务工单。自动化运维结合可观测性数据日志、指标创建能够诊断问题、执行修复脚本的运维 Agent。5. 深入底层原理与定制自定义代理类型研究Agent基类创建完全符合你业务逻辑的代理类型例如强制按特定步骤执行。优化提示工程设计更精妙的系统提示词和少量示例Few-Shot引导模型更可靠地进行规划和工具选择。模型微调如果任务领域非常专业可以考虑使用工具调用数据对基础模型进行微调使其更擅长使用你的特定工具集。从构建一个简单的工具调用 Agent 开始逐步深入到多智能体、长记忆和系统集成你将能够打造出真正强大、自主的 AI 应用。记住始终从一个小而具体的问题开始验证可行性再逐步扩展其能力和边界。