本文是「Agent 工程实战」系列的第 17 篇属于工具链线。系列索引21 篇阅读路线Agent 放权前先补权限、出站、发现这三道口子摘要OpenAI Agents API 公开测试官方示例代码直接把 MCP 写成一等公民。本文对照官方文档梳理已有 MCP Server 要动的地方HTTP 传输接入、server_label 标识以及为按需加载重写的工具描述。附接入结构拆解和改造清单。文章目录官方示例里直接长出了 MCPAgents API 到底是什么MCP 接入长什么样我的 MCP Server 要动哪几处工具描述从写给人看变成写给检索器看接入后怎么验证自己改对了哪些场景其实不用上 MCP一份落地自查清单回头看官方示例里直接长出了 MCP写 MCP Server 那篇文章的时候我结尾提过一句给 AI 写 API 文档比给 AI 写接口本身更难。前几天 OpenAI 发布 Agents API我刷到官方博客第一反应是——工具这一层他们开始认真对待了。先给结论这次不是宣布支持 MCP 概念那种官宣官方示例代码里直接写了type: mcp连传输方式都定好了。手上有 MCP Server 的人接过去的姿势基本是确定的。我把自己写过的 MCP Server 对着官方文档盘了一遍把要动的点整理成这篇改造笔记。先声明边界Agents API 还在公开测试期这篇是基于官方文档和既有工程经验的梳理不是已经跑通完整链路的实战复盘。哪些是文档里明写的、哪些是我自己的判断下文会标出来。Agents API 到底是什么以下内容基于 2026.09.10 发布的公开测试版接口仍在快速迭代看到文章时如果版本已变以官方文档为准。官方公告讲得很直白把 Codex 背后的那套 harness 托管给开发者通过一次 API 调用创建 agent指定任务、模型、工具和环境剩下的交给 OpenAI 跑。几个关键事实都能在公告原文找到公开测试版发布即对所有开发者开放没有附加费用只按 token 和工具使用收费官方示例用的模型是 gpt-6-astra环境有三种选法OpenAI 托管沙箱、自己的基础设施、或者 Cloudflare、Modal、Vercel 这些沙箱伙伴底层 harness 开源仓库在 GitHub 上逻辑能自己翻这些不展开讲。下面说我的正题MCP 是接进去的。想核实的朋友可以直接看官方公告原文 Introducing the Agents API接口细节在 Agents API overview 里。MCP 接入长什么样整体链路画成图是这么个走向你的应用 OpenAI 托管侧 你的服务器 │ │ │ ▼ ▼ ▼ sessions.create ───────► Agents API ───────► Codex Harness ──HTTP──► MCP Server │ │ tool search 按需加载工具定义 处理请求并返回结果 长会话上下文自动压缩 │ 返回结果沿同一条链路回到你的应用为什么要看这张图它把你只在登录侧动代码中间全是托管的关系摆清楚了。接 MCP 这件事本质上就是在图的最右端多挂一台你的服务中间这段不是你能改的。官方公告里给的 MCP 配置是这么个形状{agent:{tools:[{type:mcp,server_label:order_service,transport:{type:http,server_url:https://api.example.com/mcp}}]}}为什么要看这段它可能是未来一段时间里怎么给 agent 挂工具的标准写法直接对应你的 MCP Server 要被谁、以什么方式找到。字段结构照官方公告来的我把server_label和server_url换成了订单场景方便演示——官方原文的 label 是openai_docs、地址指向他们自己的文档站。本地能核对的只有字段结构四个键名和公告一致// 字段结构核对对照官方公告原文 type: mcp server_label: order_service → 给这个工具源起的名字 transport.type: http → 走 HTTP 传输 transport.server_url: https://… → 你的 Server 地址这一段里有三个信息点接的时候一个都不能少type: mcp声明这是个 MCP 工具源server_label给这个 server 起的名字agent 日志里靠它区分是哪个源transport.http.server_url你的 Server 得通过 HTTP 暴露出来地址填这里注意 transport 用的是 http不是本地 stdio 那套。你的 Server 要能被一个跑在云上的 agent 从公网访问到。这个前提看着不起眼实际是本地开发最容易栽的地方后面边界说明里再展开。JS SDK 的调用长这样也是官方示例beta.前缀如实保留我为了突出 MCP 部分省掉了 vault_ids、environment 这些非核心字段input换成了订单场景constsessionawaitclient.beta.agents.sessions.create({agent:{model:gpt-6-astra,tools:[{type:mcp,server_label:order_service,transport:{type:http,server_url:https://api.example.com/mcp}}]},input:把上个月的订单统计出来});为什么要看这段确认 API 层面对接成本很低——一个sessions.create工具挂进 agent 就完事。麻烦的不是这行调用是和它配套的整条链路。调用主体的结构也和上面对照过// 调用结构核验对照官方公告示例 client.beta.agents.sessions.create(...) ├─ agent.model: gpt-6-astra → 官方示例模型 ├─ agent.tools[0].type: mcp → 工具源类型 └─ input: 把上个月的订单统计出来 → 任务描述我换成了订单场景 // 调用成功返回 session 后agent 会带着配置的 MCP 工具开始跑任务我的 MCP Server 要动哪几处对照完官方示例我盘出三个要动的点。第一个传输层收敛到 HTTP。我之前写 MCP Server 用的本地 stdio文章里还专门讨论过几种 transport 的取舍。Agents API 这侧场景是云上 agent 调你的服务stdio 直接没了意义必须把 Server 包成 HTTP 服务。本地开发期可以先跑隧道转发顶一段真上生产就得有固定公网入口。第二个给 Server 起个能看的 label。server_label 是 agent 配置里给这台 server 起的名字光看示例可能觉得它只是个摆设实际作用在出错排查时才体现出来——agent 任务一多官方还支持多子 agent 并行日志里要靠它分清工具调用来自哪个源。我的建议是别让一个名字通吃所有环境label 里带上环境标识排查事故能省很多事。第三个也是最花功夫的工具描述要按按需加载的规矩重写。这个单独展开说。三个改造点先汇总成一张表方便对照改造点做什么为什么传输层stdio 收敛到 HTTPagent 在云上跑你的 Server 得能被公网访问server_label给 Server 起个能看的名字任务并行时日志里分得清工具调用来自谁工具描述按按需加载的规矩重写描述从写清楚升级为会被检索选中工具描述从写给人看变成写给检索器看Agents API 自带一个 tool search 机制官方文档的原话是按需加载相关的工具定义省 token、保持缓存命中原文档在这里。我理解下来就是——agent 不会把你的所有工具一次性搬进上下文而是需要的时候再去选一批进来。这条规则对我这种写过 MCP Server 的人来说是实打实的变化。以前写工具描述目标是让 AI 理解这工具干嘛、参数别传错——这个我在写 MCP Server 那篇时做过三版对比验证过描述从粗到细对传参的影响。现在多了一件事描述得让检索认得出来在你需要它的时候选得中它。下面是我本地测试台里的观察不是官方算法说明// 改前名字和描述都太泛{name:query_orders,description:处理订单数据,inputSchema:{orderId:string}}// 改后描述的落点具体到什么场景会用到它{name:query_order_shipping_status,description:按订单号查询订单发货状态返回预计送达时间,inputSchema:{orderId:{type:string,description:订单号必填}}}为什么要看这段这是我在 Agent 需要查某个订单到没到时同一套底层方法换两种壳的对比。改前这版是我早期连 Agent 时真实用的描述后来在本地测试台反复跑同一批查询任务执行结果差异一眼能看出同一个查询任务在本地测试台反复跑 改前 query_orders → 没有一次产生工具调用直接作答 改后 query_order_shipping_status → 每次都先调工具拿数据再基于数据作答同样一个功能描述写成处理订单数据在按需加载的场景下容易被别的带数据字样的工具挤掉写成按订单号查询发货状态被挑中的概率明显更高。我这里不敢说内部是关键词匹配还是语义匹配官方没公开机制。但更具体的描述更不容易被跳过这个观测我在自己的 MCP 测试台里复现过很多轮下面把这个差异放进表里看维度普通 API 集成Agents API MCP工具怎么进上下文自己的编排代码显式调tool search 按需加载不是全量搬入描述的作用保证参数传对参数传对 还可能决定能不能被选中Server 地址怎么给代码里写死server_url 需要公网可达多工具并行自己写编排programmatic tool calling 帮你并行这张表基本就是我改造笔记的核心差异同样的工具评价尺度从用起来对不对加了半个维度——“在需要的时候找不找得到”。接入后怎么验证自己改对了改完别急着上生产按下面几步在自己环境里验一遍每一步都能看到明确结果。第一步确认 MCP Server 本身活着。用 MCP 官方提供的 Inspector一条 npx 命令就能拉起来打开你的 Server能看到工具列表正常返回说明服务端没问题。这一步跟 Agents API 无关纯验你 Server 这一端# Inspector 打开后看到的工具列表示意 query_order_shipping_status 按订单号查询订单发货状态 query_orders 处理订单数据改前准备下线第二步核对 agent 配置里的字段。把官方示例的结构和你的配置逐键对比type/server_label/transport.type/transport.server_url四个键名不能错server_url要能外网访问本地先 curl 一下确认能通。第三步跑一个描述对照实验。挑一个最常用的工具先用旧描述让 agent 跑一个非调它不可的任务记下有没有调用再把描述改具体同一个任务再跑一遍。这个实验我在本地测试台做过差异是明确的你自己环境里也能复现同一个任务查订单到哪了两次运行对比 旧描述 query_orders → 没有工具调用直接作答 新描述 query_order_shipping_status → 先调工具再基于数据作答第四步看 agent 日志里的 server_label。公开测试期里 agent 跑完任务后去日志里确认工具调用的来源标识是不是你配的 label——顺便就验证了 label 起得够不够清楚。哪些场景其实不用上 MCPMCP 接入看着规整别什么都往里塞。就一个函数能解决的事算个折扣、查个字典直接在 agent 配置里定义成普通函数更轻。MCP 这套的价值在复用已有的工具服务尤其是你已经有一批 HTTP 服务想给多个 agent 共用的时候。再交代几个硬前提都是实操里绕不开的你的 Server 必须公网可达或自托管环境能访问这一点官方托管沙箱的链路里绕不掉传输走 HTTP 后旧代码如果是纯 stdio要包的层不止一处鉴权也得提前想好如果你的 Server 用的是 SSE 这类更老的 MCP 传输形态别想当然觉得直接能用先对着 MCP 官方文档确认 HTTP transport 的要求该包的兼容层一个都不能少公开测试期接口和配置随时可能变生产接入前盯着更新日志再动手真要对 MCP 协议本身深入规范在 modelcontextprotocol.io 有完整文档这篇不展开。一份落地自查清单接之前对着这四条过一遍能少踩不少坑MCP Server 已经包成 HTTP 服务外网地址可达本地开发先用隧道顶一段server_label 带上了环境标识出错时日志里能分清是哪台每个工具的 description 写的是什么场景会用到它不是它是什么公开测试期的更新日志放进关注列表接口变了不慌回头看OpenAI 把 MCP 写进官方示例等于给这一届 agent 定了工具层的接口基调。对跑过 MCP Server 的人来说接入本身不麻烦真正要花心思的是把给 AI 看 API 文档升级成在按需加载的世界里让自己的工具被选中。前者是讲清楚后者是会被找到——两件事难度不一样。如果现在就要动手我的建议是先挑一个最常用的工具把 description 从它是什么改成什么场景会用到它跑一轮同样的任务对比调用情况。这个验证最直观比把全套工具重写一遍稳妥得多。「Agent 工程实战」系列路线工具链线MCP/测试脚本下一篇18 Agent 调 MCP 一个都没碰到系列索引21 篇阅读路线Agent 放权前先补权限、出站、发现这三道口子专栏Agent 工程实战如果这篇对你有用欢迎收藏想追更可以关注「Agent 工程实战」专栏。