★ FEATURED ARTICLE 如果你从“智能的解构”这个系列一路读过来大概率已经对 Agent、RAG、工作流这些概念不陌生了。但到了第 11 章我想先把注意力从模型本身挪开放回连接模型的那些接口Tool-Calling、OpenAPI、MCP。这三样东西看起来像三件互不相干的工程工具实际上它们串起了智能体应用从模型到业务系统之间最关键的“中间层”。这一章不会只讲概念我会结合自己的落地经验聊聊为什么接口标准正在成为智能体项目最要紧的基础设施也把三者的适用场景和实战坑位都摊开讲透。适合正在做 Agent 功能开发、给智能体接外部工具、或者在多个应用之间复用工具能力的读者。1. 从模型调用到工具协作为什么接口标准成了智能体的“新基础设施”1.1 智能体发展的“下半场”拼的是工具不是模型参数两年前大家接大模型做的事很简单把上下文塞进 prompt拿到一段文本然后自己用正则或者分词去解析结果。这种模式在纯问答场景里够用可一旦你希望模型能查快递、订会议、改数据库里的记录事情就变得非常不可控。模型输出的文本“我帮你查到了北京的天气”不等于真正执行了查询动作你必须自己从这句话里猜用户意图再拼装参数去请求天气接口。猜得准还好猜不准整个对话流程就直接断掉。智能体应用之所以叫“智能体”就是因为模型要在一个循环里不断地观察、决策、行动。这个循环里最关键的一步是“工具调用”而工具调用最核心的问题不是模型聪明不聪明而是接口规不规范。模型再强如果它不知道有哪些工具、每个工具收什么参数、返回值长什么样就只能瞎编工具系统再完备如果模型输出的调用格式不固定也接不住。所以你会看到近两年围绕模型接口层长出了一大批标准Tool-Calling 让模型可以输出结构化的函数调用意图OpenAPI 让已有的 HTTP 服务可以被机器理解和调用MCP 则试图为模型和外部工具之间定义一套通用的、可动态发现的连接协议。它们不是三个互相排斥的选项而是层层递进的三类基础设施。1.2 Tool-Calling、OpenAPI、MCP各自解决的问题我用一句话分别总结它们Tool-Calling 解决的是“模型如何表达调用意图”的问题。它是模型 API 层的一个能力让模型在回复中携带结构化函数调用参数而不是说一句含糊的自然语言。OpenAPI 解决的是“如何把任意 HTTP 服务变成可被程序识别的规范描述”的问题。它其实是接口契约任何服务只要暴露 OpenAPI 描述就能被自动生成客户端、文档和映射到 Tool-Calling 的工具定义。MCP 解决的是“工具和数据源如何以统一协议被模型应用发现并调用”的问题。它更像一套运行时协议定义了客户端、服务端、工具、资源、提示词之间的交互方式。可以从表格里看更清楚协议核心问题抽象层级典型使用场景Tool-Calling模型输出结构化函数调用模型 API 层单 Agent 内的函数路由OpenAPIHTTP 接口的规范描述服务契约层REST API 接入智能体MCP工具/资源的统一发现与调用应用连接层多应用共享工具基础设施在实际项目里三者经常组合出现。先用 OpenAPI 从现有后端生成工具定义然后通过模型 API 的 Tool-Calling 能力把工具暴露给模型如果工具规模变大、多个应用都要接入再用 MCP 把工具服务化。理解了这个关系后面内容就好读了。2. Tool-Calling 的核心实现与选型细节2.1 Tool-Calling 的原理从指令跟随到结构化输出的跳变很多第一次接触 Tool-Calling 的同学容易误解以为模型“调用”了函数。其实不是。模型本质上是在做文本生成只是 API 层额外提供了一种约束你传入一份工具清单模型在需要时输出一个特殊字段这个字段的结构是约定好的。拿最典型的请求来看你在请求体里带上{ model: xxx, messages: [{role: user, content: 北京今天适合出门吗}], tools: [ { type: function, function: { name: get_weather, description: 查询指定城市的实时天气信息, parameters: { type: object, properties: { city: {type: string, description: 城市名称中文全称}, unit: {type: string, enum: [celsius, fahrenheit]} }, required: [city] } } } ] }模型如果判断需要查天气返回的消息里会带着{ tool_calls: [ { id: call_abc123, type: function, function: { name: get_weather, arguments: {\city\: \北京\, \unit\: \celsius\} } } ] }注意这里 arguments 是一个 JSON 字符串不是对象。你拿到之后要自己解析执行对应函数再把结果以role: tool的方式回传给模型。关键认知是模型只负责“表达调用计划”真正执行还是你的代码。如果你没把执行结果正确回传模型就会在下一步推理里失去上下文。我之前见过一个团队把函数执行和生成逻辑混在同一个线程里结果一个工具阻塞了 20 秒导致整个对话超时这就是没有理解“模型表达 外部执行 结果回填”的循环结构。2.2 工具定义怎么写字段设计、参数约束、描述词的“隐藏权重”工具定义的写作质量直接决定模型会不会乱调、不调或者错调。我自己的经验是把写工具定义当成写一份“给一个理解能力很强但一无所知的实习生看的工作手册”。命名上尽量用动词开头比如get_user_info、create_order、cancel_subscription避免用太抽象的词。描述要写清楚“什么时候该用、什么时候不该用、有没有副作用”。很多工程师写描述只写一句“查询天气”这远远不够。更好的写法是{ name: get_weather, description: 当用户询问某个城市当前或近几日的天气情况时使用。输入城市名称返回天气描述、气温、风力。如果需要查询空气质量请使用另一个工具 get_air_quality不要使用本工具。 }这里把边界条件写得很清楚。模型对描述文本里的“不要”“除非”“仅当”这类否定词非常敏感写不好反而提高幻觉概率。我习惯用正面描述为主必要的时候用一句“如果用户需要 X请使用另一个工具”来做路由分割。参数设计上原则是“少而精、枚举尽量锁、必填尽量少”。一个工具如果超过四五个参数模型漏传或错传的概率会指数级上升。能用枚举限制的就不要让模型自由发挥。比如温度单位定义为[celsius, fahrenheit]而不是让模型猜。必填字段只要不是逻辑上非有不可就别标成 required留给模型判断。还有一个隐藏要点工具描述和参数描述会占用上下文 Token但省这个钱可能会更亏。我见过有人为了省 Token把所有工具的 description 都砍成一句话结果模型把下单工具当查单工具用。省下几十个 token多出几轮错误恢复得不偿失。2.3 多工具选择与并发调用的实用技巧当工具数量多到一定程度比如超过 20 个模型的选择准确率会明显下降。这时候有几种处理方式第一种按域分组。不要把 20 个工具全部平铺给模型而是设计一个路由层先让模型选“用户意图属于哪个域”再把该域的 5 个工具传进去。相当于先粗粒度分类再细粒度决策。第二种使用参数里的tool_choice。很多模型 API 支持auto、none、required或指定某个工具名称。在流程关键节点比如必须调用一个工具才能继续时设置为required能避免模型跳过工具直接乱答。第三种并发调用。模型支持在一次回复中输出多个tool_calls。比如用户问“北京和上海明天冷不冷”模型可能同时发起两个 get_weather 调用。你要做的是并发执行而不是串行等待。下面是一个偏向 Python 伪代码的示意import asyncio async def run_tool_call(call): name call.function.name args json.loads(call.function.arguments) return await execute_tool(name, args) async def process_tool_calls(response_tool_calls, messages): results await asyncio.gather(*[run_tool_call(call) for call in response_tool_calls]) for call, result in zip(response_tool_calls, results): messages.append({ role: tool, tool_call_id: call.id, content: result })注意tool_call_id一定要对应准确。如果不维护这个 id回填结果时模型会分不清哪个结果对应哪个调用轻则上下文混乱重则直接报错。还有一个实际经验并发调用里如果其中一路工具失败不要整个流程崩溃而是把这个失败结果也作为工具返回内容比如{error: timeout}让模型基于错误信息决定重试还是向用户道歉。这样用户体验比直接报错好得多。3. OpenAPI 在智能体接口设计中的角色3.1 OpenAPI 不只是文档它能当“工具生成器”用很多团队在设计内部服务时已经顺手维护了 OpenAPI 文档因为要给前端联调用。但在接智能体时大家往往又手工写一遍工具定义完全重复劳动。其实 OpenAPI 本身就是机器可读的接口契约完全可以把每个 operation 转换成 Tool-Calling 需要的工具定义。我最近在一个模拟项目 X 里做智能客服系统后端有 40 多个 REST 接口分布在订单、商品、库存、物流几个域。如果用纯手工方式把每个接口翻译成工具定义按每个接口 10 分钟算要花掉一个下午而且翻译过程中很容易丢字段。后来我用脚本把 OpenAPI 描述批量解析成 tools十几分钟就搞定了。后面接口一更新重新跑一遍生成脚本即可再也不用担心工具定义和数据源头脱节。还有一个额外收益OpenAPI 里的operationId、summary、description已经包含了大量语义信息可以直接复用为工具名和描述。写工具描述最花时间的部分往往是把你对业务的理解写成模型能懂的话。而 OpenAPI 描述通常已经由后端工程师写过了表达的准确度比自己临时编要高。3.2 从 OpenAPI 到 Tool-Calling 的映射实践具体怎么映射我建议按这样的步骤走解析 OpenAPI 文件得到所有paths和operations。对每个 operation先提取operationId作为工具名。没有 operationId 时用method path组合比如get_/orders/{id}。提取参数路径参数、查询参数、请求体中的 schema统一映射成 JSON Schema 的properties结构。把required合并出来包括路径参数和必填请求字段。生成description优先拼接operation.summaryoperation.description如果为空再手动补一句。一个简化版的生成逻辑长这样def operation_to_tool(method, path, operation): parameters operation.get(parameters, []) properties {} required [] for p in parameters: p_name p[name] properties[p_name] p.get(schema, {type: string}) if p.get(required, False): required.append(p_name) # requestBody 的处理省略需要解析 schema tool_name operation.get(operationId, f{method}_{path}) tool_description .join([ operation.get(summary, ), operation.get(description, ) ]).strip() return { type: function, function: { name: tool_name, description: tool_description, parameters: { type: object, properties: properties, required: required } } }这里面有几个坑要专门提醒一下第一$ref引用必须提前解析。很多 OpenAPI 文档为了可维护性会把 schema 抽到 components 里直接拿原样传给模型 API很多 API 是不认$ref的。跑生成脚本前先做一轮 schema 展开。第二部分 OpenAPI 里的复杂结构比如oneOf、allOf主流模型的 tools 参数不一定支持。如果你硬传有的平台会报错有的会忽略。实操中最稳妥的方式是遇到这些结构就简化成普通 object 或者手写一个示例值。第三请求体里的二进制上传、form-data 这类场景生成工具定义时要把类型改成 object并给一个明确的说明避免模型强行传 base64 字符串。第四权限和鉴权不能放进工具定义。工具的security信息更适合保留在调用层由后端自己处理。如果你把 token 强依赖写进工具描述模型一旦理解偏差可能让用户输入敏感信息这就很危险。4. MCP为模型连接外部世界的统一协议4.1 MCP 到底是什么客户端-服务端模型的启示如果说 Tool-Calling 是模型 API 自带的能力那么 MCP 则是更上一层的“通用连接协议”。MCP 的全称是 Model Context Protocol想解决的痛点是每个智能体应用都可能需要接不同的数据源和工具如果每接一个系统就写一套私有集成那整个生态会非常碎片化。于是有人把很多智能体连接外部工具时共同需要的逻辑抽象成了一套标准协议。它的架构里有三个角色Host一个智能体应用比如聊天助手、IDE 插件或者自动化工作流引擎。ClientHost 内部用来连接某个 MCP Server 的组件负责建立传输、初始化协议、转发调用请求。Server暴露工具、资源、提示词的程序。一个 Server 可以封装一个业务系统也可以封装一组通用能力。这套架构很像生活中常见的“万能接口”概念电脑上用 USB-C 连接显示器、移动硬盘、采集卡设备厂商只要实现 USB-C 标准用户就不需要为每个设备配不同的线缆。MCP 就是智能体世界的 USB-CServer 只需要实现 MCP就能被任意支持 MCP 的 Host 使用。MCP 支持两种传输方式stdio 适合本地进程启动子进程走标准输入输出通信HTTP/SSE 适合远程服务部署。它定义了资源、工具和提示词三类原语。资源用来给模型提供上下文数据比如文件内容、查询结果工具是可执行的操作模型可以主动调用提示词则是服务端预先配置好的模板。4.2 接入一个 MCP Server 的完整套路下面用一个天气服务来演示怎么快速搭起一个 MCP Server。这里我用 Python 的 SDK 风格描述实际使用时要根据你依赖的 SDK 版本微调。import asyncio from mcp.server import Server from mcp.server.stdio import stdio_server app Server(weather-demo) app.list_tools() async def list_tools(): return [ { name: get_weather, description: 查询指定城市的当前天气, inputSchema: { type: object, properties: { city: {type: string, description: 城市中文名} }, required: [city] } } ] app.call_tool() async def call_tool(name: str, arguments: dict): if name get_weather: city arguments.get(city, ) # 这里替换成真实天气服务调用 return { content: [ {type: text, text: f{city}: 晴, 25°C} ] } raise ValueError(funknown tool: {name}) async def run(): async with stdio_server() as (read_stream, write_stream): await app.run(read_stream, write_stream) if __name__ __main__: asyncio.run(run())这个 Server 启动后会通过 stdio 与客户端通信。客户端这边需要做的是建立会话然后发现工具再把工具映射给模型。from mcp import ClientSession from mcp.client.stdio import stdio_client, StdioServerParameters server_params StdioServerParameters( commandpython, args[weather_server.py] ) async def discover_tools(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() for tool in tools.tools: print(tool.name, tool.inputSchema) result await session.call_tool( get_weather, {city: 北京} ) print(result.content)如果你在做一个更完整的智能体把discover_tools返回的工具列表转换成 Tool-Calling 格式传给模型即可。等于说 MCP 负责了“工具从哪来、怎么实时发现”的活Tool-Calling 负责“模型怎么表达调用意图”的活。这里有个很重要的实操点在 MCP 的 stdio 模式下应用程序的常规日志不能打到 stdout。因为 stdout 被协议占据了一旦你把日志混进去客户端解析协议直接失败。要么把日志写到 stderr要么输出到文件。很多第一次跑 MCP 的人死活连不上先查这个问题。4.3 MCP与Tool-Calling的关系协议之上还是并集子集很多人会问有了 MCP是不是就不需要 Tool-Calling 了答案是否定的。MCP 和 Tool-Calling 是不同层的标准。MCP 帮助你“找到工具并完成传输”Tool-Calling 帮助模型“根据输入选择工具并生成参数”。一个完整的智能体通常需要两者配合。可以这样理解Tool-Calling 是一台设备内部的指令总线规定 CPU 要怎么发出访问外设的信号MCP 是外部接口标准规定设备怎么插入主机、怎么枚举能力。一台主机要正常工作内部总线和外部接口都需要。在项目选型时如果只有单个智能体、工具数量很少完全可以直接用 Tool-Calling透传一个工具列表省去部署 MCP Server 的成本。但如果你有多个不同的智能体应用都要访问同一套工具或者工具列表会动态变化那就值得使用 MCP。它带来的动态发现能力可以让你避免每次接口变更都要重新发版智能体程序。缺点是链路多了一层排查问题多了一个环节对团队运维能力有要求。5. 三种方案如何落地选择与问题排查5.1 选型矩阵什么场景用哪个学了这么多概念还是要回到落地。我整理了一张选型表你可以直接参照实际场景更合适的方案为什么单个智能体写几个内部函数Tool-Calling零额外组件快已有大量 REST API想快速接智能体OpenAPI 转工具复用现有契约减少手工维护多个应用共享一套业务工具MCP统一发现与调用避免重复集成需要给模型提供文件、数据库等上下文MCP resources不仅是工具还有数据通道存量系统是遗留接口没有 OpenAPITool-Calling 手动定义先有工具定义跑通再逐步规范化不要一上来就把三个方案全用了。我见过一个团队在 MVP 阶段就给智能体接了 MCP工具定义又从 OpenAPI 自动生成再加了一层自己的路由逻辑最后出现问题都不知道是哪一层出的。更合理的路径是小步快跑先手工写好工具定义通过 Tool-Calling 把闭环跑通等维护成本高了再用 OpenAPI 半自动化生成当工具数量超过 10 个且跨应用复用时再引入 MCP。5.2 实战中遇到的常见问题与排查技巧我把自己在项目里踩过的典型问题整理成了速查表遇到类似情况可以直接照方抓药。问题一工具定义过大对话还没开始上下文先爆了现象是每轮请求都把 20 个工具完整传一遍每个工具参数平均 200 token光工具就要 4000 token还没算历史消息。排查思路看请求日志里 tools 字段的大小。解决方式精简参数描述给每个工具只保留最必要的参数或使用意图路由先分域再传子工具或利用模型平台提供的工具缓存能力让工具定义在会话内复用。问题二模型返回的 arguments 不是合法 JSON现象是json.loads直接抛异常。这种情况在模型版本更新后偶尔会复现。排查思路记录时序回溯看是不是上下文里有太多无关注释干扰了输出。解决方式不要简单地让模型重试而是把解析错误信息作为工具调用结果回传让模型基于错误自己纠正。比如把 content 设为{error: arguments parse failed, expected JSON}。大多数模型看到这个会重新生成正确的参数。问题三并发 tool_calls 结果回填混乱现象是多工具并行时助手回复内容张冠李戴。这几乎都是tool_call_id没对上。排查思路打印 messages 回填前后的完整结构。解决方式严格遵守协议每一条 tool 消息都必须带tool_call_id并且和tool_calls列表里的 id 一一对应。问题四OpenAPI 生成的工具定义在模型 API 上报错现象是某个 schema 不合法典型报错集中在oneOf、allOf或者多层$ref。排查思路用 OpenAPI 解析器预先验证 schema 完整性。解决方式生成 tool 定义时主动降级把复杂 schema 拍平成普通 object 类型去掉描述里过长、包含特殊字符的内容检查枚举值类型是否与 schema 里声明的类型一致。问题五MCP Server 连接成功但调用总是超时现象是 stdio 模式下 Server 启动了但call_tool很久没返回。排查思路先检查 Server 是否把日志打到 stdout。这个问题发生率排第一。其次检查 Server 里的处理函数有没有阻塞在同步调用上。解决方式write 日志分离到 stderr把耗时操作改成异步给外部依赖调用加上超时。问题六模型老是调用错工具现象是用户要查订单模型却调用了创建订单接口。排查思路翻出工具定义的 description 看是否包含了足够的路由边界。解决方式在描述里明确写“当用户意图为查询时使用当用户意图为新增时使用另一个工具”给工具名加前缀域比如query_order_*和create_order_*让模型更容易区分必要时用 tool_choice 锁定目标。这些坑几乎都不是模型能力问题而是接口设计问题。接口协议的价值就在于把这些容易出错的细节规范化让“模型调用工具”这件事从玄学变成工程。我个人在实际操作中的体会是接口协议比选模型参数更容易被忽略但它对智能体应用稳定性的影响往往是决定性的。如果你正在做一个新的 Agent 项目我的建议很简单先把 Tool-Calling 的闭环彻底跑通再考虑 OpenAPI 自动生成最后当规模上来之后再碰 MCP。不要为了技术时髦去上 MCP否则排查问题的成本会让你非常难受。最后分享一个小技巧无论用哪种协议给每个工具的 description 里都加一句“当信息不足时默认如何响应”。只加这一句话就能明显减少模型在边界场景里的胡猜。
阅读完成 · 觉得有帮助？
