多模型网关接入 Agent 后，最容易坏在哪里：5 个兼容性排障点

把 OpenAI、Anthropic、Google 或其他模型放到一个 API 入口后，最先出现的故障通常不是“模型不可用”，而是请求看起来成功，Agent 却在下一步做错了事。

原因在于，OpenAI 兼容只描述了请求的外形。真正的 Agent 调用还包含流式事件、工具结果、推理状态、重试和用量记录。只要网关在不同协议之间做了转码，任何一个细节丢失，都可能表现为重复调用、错误结果被当成成功、上下文突然失效，甚至账单无法解释。

8 月 7 日，开源 AI Gateway Bifrost 发布 HTTP Transport v1.6.9。这个版本一次性修复了 SSE 心跳打断 JSON、MCP 工具错误被重放成成功、跨供应商回退时加密推理内容无法验证、服务端工具搜索字段未正确转发等问题，还补充了按团队和业务单元切分的 OpenTelemetry 指标。它不是一份通用标准，却很适合作为排障样本：生产网关真正难维护的，是行为兼容，而不只是 URL 兼容。

1. SSE 心跳不能插进数据行

MCP 的 Streamable HTTP 允许服务器使用 SSE 返回多个 JSON-RPC 消息。规范要求客户端能够处理断开、重连和可恢复事件；一个断开的连接也不能直接被解释为请求已取消。LLM 网关通常还要在长响应期间发送心跳，避免中间代理关闭空闲连接。

风险在于心跳的写入和 JSON 数据的写入如果没有共同的帧边界保护，心跳注释可能落在一行 data: 中间。客户端收到的就不再是合法 JSON，而是一个无法解析的半截事件。Bifrost v1.6.9 的修复正是针对这种 mid-line corruption，并兼容了会把空心跳事件误认为 JSON 的旧版 SSE 解码器。

网关侧至少要做到三点：

在字节或事件层完成 framing，再做心跳插入，不要在字符串拼接后“顺手”写入注释。
为每个事件保留可追踪的 request id、上游 provider 和模型，不要用连接 id 代替请求 id。
将“连接断开”“上游明确取消”“客户端发送取消通知”分成三个状态，分别决定是否重试和是否计费。

2. 推理状态不是普通文本，不能随意跨供应商重放

OpenAI Responses API 把 reasoning tokens 作为额外输出用量，OpenAI 也建议长任务保留上一轮响应上下文；Anthropic 的扩展思考接口则会返回带签名的 thinking block。它们都说明：推理状态是下一轮工具调用的一部分，不是可以随意截断的展示文本。

当一个请求从供应商 A 回退到供应商 B 时，网关若原样转发 A 的加密推理内容，B 可能无法验证；若直接丢弃，又可能让下一轮工具调用失去必要上下文。Bifrost 的做法是在特定上游 400 场景下去掉无法验证的 encrypted_content 后重试一次，这是一个明确的 fail-soft 策略，但不能被误解成所有模型都能安全这样处理。

更稳妥的路由记录应包括：

字段	用途
`provider`、`model`、协议版本	判断哪些响应字段可以回放
reasoning 类型和是否加密	决定保留、摘要或清除
回退原因与重试次数	解释延迟、成本和质量变化
工具调用阶段	避免把已执行的副作用再次提交

跨供应商 fallback 前，先判断请求是否含有不可移植的推理或工具状态。对于支付、写库、发消息等有副作用的工具，宁可返回可恢复错误，也不要在不确定执行结果时自动重放。

3. HTTP 200 不等于工具调用成功

MCP 官方工具规范把真正的业务失败放在结果里的 isError 字段。一次 tools/call 可以在传输层返回 200，但工具结果仍然是错误；客户端应该把它作为失败反馈给模型，而不是当成正常数据继续规划。

这也是 Bifrost v1.6.9 修复的另一类问题：失败的 MCP 执行在 Agent loop 中被重放成成功结果。后果并不只是日志难看，模型可能据此声称“文件已修改”或继续调用依赖该结果的工具。

建议在网关建立两层状态：

传输状态：HTTP、SSE 或 JSON-RPC 是否成功收发。
业务状态：工具是否执行、是否返回 isError、是否产生副作用。

只有业务状态明确成功，才推进 Agent 的下一步；遇到参数错误、权限拒绝或上游超时，应把结构化错误和可重试性传回模型，并在审计记录中保留原始工具名与参数摘要。

4. 工具搜索也需要路由策略

MCP 的 tools/list 支持分页，工具列表还可能通过 notifications/tools/list_changed 动态变化。把所有工具描述一次性塞进模型上下文，既增加 token 成本，也会让相似工具更难区分。

Bifrost 文档把 MCP Client、MCP Server、工具过滤和 Code Mode 放在同一网关中，并建议在连接多个 Server 时使用按需发现。其近期版本还修复了服务端工具搜索字段在转换链路中没有正确到达下游的问题。

工具发现应该像模型选择一样有明确规则：

按租户、项目和请求身份过滤可见工具。
先返回名称、用途和风险等级等短描述，需要时再加载完整 schema。
将工具版本和 schema 哈希写入请求日志，防止同名工具变更后无法复盘。
对高风险工具保留人工确认或显式的自动执行白名单。

这样做的目标不是让网关替 Agent 决策，而是把“哪些工具可以被看见、何时加载、谁能执行”变成可审计的路由输入。

5. 成本治理必须跟着 Agent 步骤走

Agent 的一次用户任务可能包含多次模型请求、工具发现、工具执行、重试和回退。只按 API key 或 HTTP 请求数汇总，无法回答“这次任务为什么这么贵”。Bifrost v1.6.9 为 OTEL 指标补充了服务实例、团队、客户和业务单元维度，同时修复了配置同步覆盖实时预算计数器的问题。

网关可以把一次任务拆成可计算的账本：

事件	至少记录
模型请求	输入、输出、推理 token，provider，模型，延迟
工具发现	Server、工具数量、schema token 或缓存命中
工具执行	工具名、成功/失败、副作用、耗时
重试与回退	触发原因、目标模型、是否重复计费

预算规则也要明确“按什么停”：总 token、模型费用、工具次数，还是任务时长。达到上限时返回可识别的 incomplete 或业务错误，并保留已经完成的步骤，避免客户端因为看不到结果而整条任务重跑。

上线前的最小兼容性清单

把多模型 Agent 接入统一网关前，可以用下面的测试集验收，而不是只发一个普通聊天请求：

SSE 中途插入心跳，检查每个 data 事件是否仍可独立解析，并验证断线后的重连游标。
同一工具分别返回 HTTP 200 + isError: true、超时和权限拒绝，检查 Agent 是否会正确停止或重试。
在含 reasoning 和工具调用的多轮请求中切换供应商，确认不可移植字段不会被无条件重放。
动态更新 tools/list，检查过滤、schema 版本和缓存失效是否生效。
让一次任务触发多次模型调用、工具调用和 fallback，核对 token、预算和租户归因是否只记一次。
对写库、发消息等副作用工具注入断线，确认“不确定结果”不会触发自动重复执行。

统一入口的价值，是让这些检查可以在一个地方完成。真正可靠的模型网关，应把协议转码、工具执行、回退和成本记录视为同一条 Agent 事务链路来设计，而不是四个互不相干的中间件功能。