从零开发带工具调用能力的智能问答系统核心是把LLM大脑 Tools外部能力 Memory记忆 Agent 编排四块拼起来。LangChain 现在的推荐做法是业务内简单工具用tool直接封装跨系统、要复用的能力走MCPModel Context Protocol标准化接入。下面按可落地的顺序一步步来。一、整体架构与选型一个生产可用的问答智能体通常包含用户问题 → Agent(LLM 推理) → 选择工具 → 执行工具(API/MCP/RAG) → 观察结果 → 组织答案 ↑ | └─────────────── 多轮循环 ───────────────┘关键选型模型支持 tool calling 的大模型GPT-4o、Claude、Qwen、DeepSeek 等均可通过langchain-openai的base_url接兼容接口Agent 框架langchainlanggraphLangChain 官方现在主推 LangGraph 做 Agent 编排工具简单/业务紧耦合 →tool原生封装跨系统/需复用/独立部署 →MCP Server通过langchain-mcp-adapters接入MCP 与 Function Calling 的关系互补而非替代。MCP 解决工具接口标准化、多 Agent 共享Function Calling 解决单次模型如何调 API。完整链路是MCP Client 把 Server 的工具注册进来 → 转成模型的 tools 参数 → 模型用 Function Calling 选定工具 → Client 经 MCP Server 执行 → 结果回传模型。二、环境准备# 核心依赖pipinstalllangchain langchain-openai langchain-community langgraph pipinstalllangchain-mcp-adapters# MCP 适配器pipinstallpython-dotenv# 环境变量管理# 如需本地 MCP ServerNode 版npminstall-gmodelcontextprotocol/server-filesystem.env文件OPENAI_API_KEY你的key OPENAI_BASE_URL模型代理地址可选用于对接兼容接口 MODEL_NAMEgpt-4o-mini三、Step 1搭建最小可跑通的 Agent原生 tool先用最简单的计算器工具跑通思考→选工具→执行→回答闭环importosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportAgentExecutor,create_tool_calling_agentfromlangchain_core.promptsimportChatPromptTemplate,MessagesPlaceholderfromlangchain_core.toolsimporttoolfromlangchain_community.chat_message_historiesimportFileChatMessageHistory load_dotenv()# 1. 自定义工具用 tool 装饰器封装tooldefcalculator(num1:float,num2:float,op:str)-str:数字计算工具用于两个数字运算 :param num1: 第一个数字 :param num2: 第二个数字 :param op: 运算符号支持 - * / ifop:resnum1num2elifop-:resnum1-num2elifop*:resnum1*num2elifop/:resnum1/num2else:return不支持该运算符returnf计算结果:{res}tools[calculator]# 2. 初始化 LLMllmChatOpenAI(modelos.getenv(MODEL_NAME,gpt-4o-mini),temperature0)# 3. Prompt 模板必须包含 agent_scratchpadpromptChatPromptTemplate.from_messages([(system,你是一个擅长使用工具完成任务的助手优先调用工具获取结果不要凭空编造数据。),MessagesPlaceholder(variable_namechat_history),(user,{input}),MessagesPlaceholder(variable_nameagent_scratchpad),])# 4. 创建 Agent 与 Executoragentcreate_tool_calling_agent(llm,tools,prompt)agent_executorAgentExecutor(agentagent,toolstools,verboseTrue)# 5. 持久化记忆historyFileChatMessageHistory(./agent_memory.json)whileTrue:user_inputinput(\n请输入你的问题(输入 exit 退出):)ifuser_inputexit:breakrespagent_executor.invoke({input:user_input,chat_history:history.messages})print(fAI:{resp[output]})history.add_user_message(user_input)history.add_ai_message(resp[output])工具描述的写法直接影响工具选择准确率。docstring 要写清这个工具做什么、何时用、参数含义。模糊的描述会让模型乱调工具。四、Step 2接入外部 API 作为工具真实问答系统几乎一定要调外部 REST API订单查询、天气、搜索等。用tool封装 HTTP 请求即可importrequestsfromlangchain_core.toolsimporttooltooldefquery_order(order_id:str)-str:查询订单状态输入为订单ID(如 ORD12345)try:resprequests.get(fhttps://api.your-domain.com/orders/{order_id},timeout5)resp.raise_for_status()dataresp.json()returnf订单{order_id}状态:{data.get(status)}, 物流:{data.get(tracking_no)}exceptrequests.RequestExceptionase:returnf查询失败:{e}tooldefget_weather(city:str)-str:获取指定城市的当前天气api_keyos.getenv(WEATHER_API_KEY)resprequests.get(https://api.weatherapi.com/v1/current.json,params{key:api_key,q:city},timeout5)dataresp.json()returnf{city}:{data[current][temp_c]}°C,{data[current][condition][text]}工具开发的最佳实践异常处理网络请求必须 try/except返回友好错误信息而非抛异常超时控制所有 HTTP 调用设timeout参数校验用 PydanticStructuredTool做强类型校验敏感信息API Key 走环境变量禁止硬编码幂等性工具最好设计为可重复调用把 API 工具加入tools列表即可让 Agent 自主调用tools[calculator,query_order,get_weather]五、Step 3接入 MCP 服务重点当工具需要跨项目复用、独立部署、或被多个 Agent 共享时应该把它做成 MCP Server。5.1 编写一个 MCP Server用 Python 的 FastMCP 写一个提供数学工具的 Servermath_server.pyfrommcp.server.fastmcpimportFastMCP mcpFastMCP(Math)mcp.tool()defadd(a:int,b:int)-int:Add two numbersreturnabmcp.tool()defmultiply(a:int,b:int)-int:Multiply two numbersreturna*bif__name____main__:mcp.run(transportstdio)也可以用 Node.js 写两端完全解耦互不干扰。5.2 在 LangChain 中接入 MCP 工具langchain-mcp-adapters支持stdio本地进程和Streamable HTTP远程服务两种传输方式importasynciofromlangchain_mcp_adapters.clientimportMultiServerMCPClientfromlangchain.agentsimportcreate_agentasyncdefmain():# 连接多个 MCP Serverstdio http 混合clientMultiServerMCPClient({math:{command:python,args:[./math_server.py],transport:stdio,},weather:{url:http://localhost:8000/mcp,transport:http,}})toolsawaitclient.get_tools()print(f加载了{len(tools)}个 MCP 工具)# 创建 Agentagentcreate_agent(openai:gpt-4.1,tools)resultawaitagent.ainvoke({messages:whats (3 5) x 12?})print(result[output])asyncio.run(main())如果用 JS/TSlangchain/mcp-adapters支持更丰富的配置认证头、OAuth、自动重连等import{MultiServerMCPClient}fromlangchain/mcp-adapters;import{createAgent}fromlangchain;import{ChatOpenAI}fromlangchain/openai;constclientnewMultiServerMCPClient({mcpServers:{math:{transport:stdio,command:npx,args:[-y,modelcontextprotocol/server-math],},weather:{url:https://example.com/weather/mcp,headers:{Authorization:Bearer token123}}}});consttoolsawaitclient.getTools();constmodelnewChatOpenAI({model:gpt-4o-mini,temperature:0});constagentcreateAgent({llm:model,tools});⚠️生产环境务必 Pin MCP Server 版本避免远程 Server 升级导致工具签名变化。5.3 原生 tool vs MCP 怎么选维度原生toolMCP Server复用性仅当前应用任意 MCP 客户端可用跨语言不支持Python/Node/Rust 全兼容部署随应用一起可独立部署、升级适用场景快速原型、1-2 个工具多系统共享、需独立运维经验法则工具会被多个项目用到 → MCP只是当前业务的简单封装 →tool。六、Step 4RAG Agent 组合知识库问答纯工具调用适合操作类问题但企业问答往往需要基于私有文档回答。把 RAG 检索也封装成一个工具即可fromlangchain_community.vectorstoresimportChromafromlangchain_openaiimportOpenAIEmbeddingsfromlangchain_core.toolsimporttool# 假设已构建好向量库vectorstoreChroma(collection_namedocs,embedding_functionOpenAIEmbeddings())tooldefsearch_knowledge_base(query:str)-str:在企业知识库中检索相关文档用于回答产品、政策、规范类问题docsvectorstore.similarity_search(query,k3)return\n\n.join([doc.page_contentfordocindocs])# 工具组合RAG API 计算tools[search_knowledge_base,query_order,calculator]这样 Agent 会根据问题自主决定是查知识库、还是调 API、还是直接计算。七、Step 5生产级增强7.1 多轮记忆与上下文除了上面演示的FileChatMessageHistory生产环境建议用 Redis 或数据库fromlangchain_redisimportRedisChatMessageHistory historyRedisChatMessageHistory(session_iduser_123,urlredis://localhost:6379)7.2 工具调用治理工具数量控制单个 Agent 工具数建议10-15 个以内过多会干扰模型选择超时与熔断给每个工具设超时失败重试 1-2 次日志与追踪用 LangSmith 或 OpenTelemetry 记录每次 tool call 的输入输出权限控制敏感工具如退款、删除加人工确认环节7.3 错误处理模式agent_executorAgentExecutor(agentagent,toolstools,verboseTrue,max_iterations10,# 防止无限循环handle_parsing_errorsTrue,# 解析错误时优雅降级return_intermediate_stepsTrue,# 返回中间步骤便于调试)八、完整项目结构建议my-agent/ ├── .env # API Keys ├── math_server.py # MCP Server独立进程 ├── agent.py # 主 Agent 入口 ├── tools/ # 原生 tool 工具 │ ├── api_tools.py # 外部 API 封装 │ └── rag_tool.py # 知识库检索工具 ├── config/ │ └── mcp_servers.json # MCP Server 配置 └── memory/ # 持久化记忆如果用文件启动 MCP 增强的 Agentimportjsonfromlangchain_mcp_adapters.clientimportMultiServerMCPClientfromlangchain.agentsimportcreate_tool_calling_agent,AgentExecutorfromlangchain_openaiimportChatOpenAIfromlangchain_core.promptsimportChatPromptTemplate,MessagesPlaceholderfromtools.api_toolsimportquery_order,get_weatherfromtools.rag_toolimportsearch_knowledge_base# 1. 加载 MCP 配置withopen(config/mcp_servers.json)asf:mcp_configjson.load(f)[mcpServers]# 2. 原生工具 MCP 工具合并mcp_clientMultiServerMCPClient(mcp_config)mcp_toolsawaitmcp_client.get_tools()native_tools[query_order,get_weather,search_knowledge_base]all_toolsnative_toolsmcp_tools# 3. 构建 AgentllmChatOpenAI(modelgpt-4o-mini,temperature0)promptChatPromptTemplate.from_messages([(system,你是一个企业智能助手可调用工具查询订单、天气、知识库等。优先用工具获取真实数据。),MessagesPlaceholder(chat_history),(user,{input}),MessagesPlaceholder(agent_scratchpad),])agentcreate_tool_calling_agent(llm,all_tools,prompt)executorAgentExecutor(agentagent,toolsall_tools,verboseTrue)# 4. 运行resultexecutor.invoke({input:查一下订单 ORD12345 的状态并告诉我北京今天天气})print(result[output])九、调试与上线路径本地跑通用verboseTrue观察 Agent 的思考链单元测试对每个tool单独测试确保输入输出符合预期集成测试用 LangSmith 追踪完整调用链路生产部署Agent 服务化FastAPI 封装MCP Server 独立部署通过 HTTP 传输加限流、鉴权、审计日志监控工具调用成功率与耗时最容易踩的坑忘记在 Prompt 里加agent_scratchpad→ Agent 无法写入思考过程工具 docstring 太模糊 → 模型选错工具MCP Server 用 stdio 传输但路径不对 → 子进程拉起失败工具执行时间长阻塞主线程 → 改用异步工具按这个路径从零搭建的智能问答系统既能查知识库RAG又能调业务 API还能通过 MCP 复用外部工具生态——这才是 2026 年生产级 Agent 的标准形态。