开启 strict schema adherence 后，还需要做 Tool Contract Testing 吗？

需要。strict 只能约束一次调用生成的参数形状，无法解决新旧客户端并存、工具语义变化、返回结构变化、缓存的旧工具清单和灰度部署期间的版本错配。

Tool Schema 只增加一个可选字段，为什么也可能成为破坏性变更？

如果旧服务端使用 additionalProperties:false，而新客户端开始发送这个新字段，新客户端到旧服务端的混合版本调用会直接校验失败。因此兼容性必须按客户端与服务端的版本组合判断。

MCP tools/list 可以缓存后，工具升级应该怎么发布？

不要假设所有客户端会立即拿到新 Schema。发布期应缩短工具清单 TTL、记录 Schema Fingerprint、保留旧版本兼容窗口；真正破坏性的变化优先采用版本化工具名或兼容适配层。

Agent Tool Contract 演进生产实战：用 Schema Fingerprint、Compatibility Matrix 与 Shadow Replay 防止工具升级故障

Agent 工具升级最危险的不是接口报错，而是参数结构和返回语义变化之后，模型仍然按照旧契约继续调用。本文结合 MCP 最新规范，给出 Schema 指纹、兼容矩阵、影子回放、灰度门禁与快速回滚的一整套方法，让工具契约的演进不再靠运气。

为什么 Agent 的工具升级比普通 API 更容易出事故

普通 API 的调用者通常是确定性的代码。字段改名、参数新增、返回值变化，编译器、SDK 或集成测试往往能较早暴露问题。

Agent Tool Calling 不一样。调用者中间多了一层模型：模型根据 tool name、description、input schema 和上下文，动态决定是否调用、调用哪个工具以及生成什么参数。于是一个看似普通的接口改动，可能同时影响三件事：

结构兼容性：旧参数是否还能通过新 Schema，新参数能否被旧服务端接受。
模型行为兼容性：description、enum 或字段含义变化后，模型是否仍会做出同样的工具选择。
运行时版本兼容性：灰度发布期间，新客户端、旧客户端、新服务端、旧服务端会形成交叉组合。

MCP 在 2026-07-28 版本中把 Tool 的 inputSchema / outputSchema 提升到完整的 JSON Schema 2020-12 能力，并允许 tools/list 等列表结果携带缓存生命周期信息。这让工具契约更强，也意味着生产发布时必须认真处理 Schema 演进和旧目录缓存。

OpenAI 的 Function Calling 同样以 JSON Schema 描述函数参数，并提供 strict schema adherence。但 strict 解决的是「这次生成是否符合当前 Schema」，不是「当前 Schema 与上一版本是否兼容」。因此，Schema 校验不能替代 Contract Testing。

先把 Tool Contract 定义完整

很多团队只把 input_schema 当成 Tool Contract。生产环境里至少应该记录下面五类信息：

Tool Identity：name、逻辑版本、所属服务、owner。
Selection Contract：description、使用条件、禁用条件、重要示例。
Input Contract：inputSchema、默认值、required、enum、格式约束。
Output Contract：outputSchema、错误结构、空结果语义、分页语义。
Behavior Contract：是否只读、是否幂等、是否产生副作用、超时和重试语义。

建议维护两个 Hash，而不是只维护一个版本号。

Schema Fingerprint

只对输入和输出 Schema 做 canonicalization 后计算哈希，用于快速判断结构是否变化：

import hashlib
import json

def stable_json(value: dict) -> str:
    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)

def schema_fingerprint(input_schema: dict, output_schema: dict | None) -> str:
    payload = {"input": input_schema, "output": output_schema}
    return hashlib.sha256(stable_json(payload).encode("utf-8")).hexdigest()[:16]

Contract Fingerprint

Contract Fingerprint 除 Schema 外，还应该纳入 tool name、description、错误语义以及自己的行为元数据。原因很简单：Schema 没变不代表模型行为没变。例如把 description 从「查询订单」改成「查询当前用户最近订单」，模型的工具选择分布就可能发生变化。

Compatibility Matrix：不要只问「新版本兼不兼容」

灰度发布时至少有四种组合：

Client Tool Catalog	Tool Server	必须验证什么
old	old	线上基线
old	new	新服务端能否继续接受历史调用
new	old	灰度期间最容易被忽略的反向兼容
new	new	新功能正确性

真正实用的兼容性判断必须落到具体变更。

通常较安全的变化

在输出中增加消费者会忽略的可选字段。
改善 description 的措辞，但不改变业务边界，并通过 Shadow Replay 验证工具选择没有明显漂移。
服务端新增对旧参数的兼容解析。

明确的破坏性变化

新增 required 输入字段。
删除或重命名已有字段。
缩小 enum 范围。
把 string 改成 object、number 改成 string 等类型变化。
改变错误返回结构，导致 Agent 无法识别可重试与不可重试错误。
同名工具的业务语义发生改变。

最容易被误判的一类：增加「可选字段」

假设 v1 的旧服务端使用：

{ "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], "additionalProperties": false }

v2 新客户端增加可选参数 unit：

{ "type": "object", "properties": { "city": {"type": "string"}, "unit": {"type": "string", "enum": ["c", "f"]} }, "required": ["city"], "additionalProperties": false }

从「旧客户端调用新服务端」的方向看，这是兼容的；但新客户端一旦生成 unit，请求打到旧服务端就会因为 additionalProperties:false 失败。

所以，兼容性是一个矩阵，不是一个布尔值。

Shadow Replay：用真实 Agent 流量验证候选契约

单元测试只能覆盖你想到的参数组合。Agent 的真实调用里往往有长尾：模型生成的可选参数组合、边缘枚举值、历史 Prompt 造成的旧式调用方式，都可能进入线上。

建议持续保留一份经过脱敏的 Tool Call Corpus，至少包含 tool name、schema fingerprint、arguments、服务端状态、output shape、调用耗时、客户端/模型版本以及是否进入 fallback。

候选工具契约进入 CI 后，先对这批历史调用做 deterministic replay：

from jsonschema import Draft202012Validator

def validate_history(calls, candidate_schema):
    validator = Draft202012Validator(candidate_schema)
    failures = []
    for item in calls:
        errors = list(validator.iter_errors(item["arguments"]))
        if errors:
            failures.append({
                "call_id": item["call_id"],
                "errors": [e.message for e in errors],
            })
    return failures

对于有副作用的工具，不要在 Shadow 阶段真的执行。只做 Schema、routing 和 adapter 层验证，或者接入 sandbox / mock downstream。对于明确只读、可安全重复执行的工具，可以进一步比较候选版本的状态码、output schema、关键字段和延迟分位数。

MCP 2026-07-28 带来的新问题：Tool Catalog 可能是旧的

MCP 2026-07-28 让 tools/list、prompts/list、resources/list 等结果可以通过 ttlMs 和 cacheScope 表达缓存建议。这个能力能降低重复发现开销，但它会扩大工具升级时的 Schema Drift Window。

例如：客户端在 10:00 缓存了 search v1 Schema；服务端在 10:02 原地替换成 v2；客户端缓存直到 10:10 才过期。中间 8 分钟，它仍可能按 v1 契约生成参数。

因此工具发布不能只更新服务端。建议：

发布窗口前临时缩短 Tool Catalog TTL。
每次调用记录 client-observed schema_fingerprint。
服务端同时接受上一版参数一段时间。
breaking change 不原地覆盖同名 Tool，优先提供版本化名称或兼容 adapter。
待旧目录缓存自然消退，再移除旧 Tool。

一套可落地的 CI Quality Gate

Gate 1：Schema 静态检查。校验 JSON Schema 本身合法，并生成 schema_fingerprint。同时自动做 Schema Diff，把变更标为 additive、potentially-breaking 或 breaking。
Gate 2：Backward / Forward Compatibility。至少验证 old→new 与 new→old 两个方向。只测试新版本自身能跑通是不够的。
Gate 3：Historical Shadow Replay。历史 Tool Call Corpus 对候选 Schema 的验证失败数应为 0；如果允许兼容 adapter，则应验证 adapter 后失败数为 0。
Gate 4：Model Behavior Replay。固定一组真实用户意图，让当前模型分别看到旧 Tool Catalog 和新 Tool Catalog，比较 tool selection、arguments shape、无工具场景误调用率，以及应该调用工具却未调用的情况。这里重点是行为 Diff，不需要 LLM-as-a-Judge；能用确定规则判断的结果，优先用确定规则。
Gate 5：Canary + Contract Telemetry。灰度阶段每个 Tool Call 至少上报：

tool_name
tool_contract_version
schema_fingerprint
client_version
model_version
validation_result
server_version
error_class
latency_ms

只要 validation_error_rate、unknown field、missing required field 或 adapter fallback 异常，就停止放量。

Breaking Change 应该怎么发布

对于明确的破坏性变更，最稳妥的方式通常不是「原地升级」，而是版本化工具 + 双运行窗口：

get_policy_quote    -> 保留旧契约
get_policy_quote_v2 -> 新契约，Canary

先让少量 Agent 看见 v2，旧 Agent 继续使用 v1。等新版本的工具选择、参数校验、业务成功率和延迟稳定后，再扩大 v2 暴露范围。

如果工具名称必须保持不变，则需要在服务端放 Compatibility Adapter：识别旧 arguments，转换成新内部 DTO，再调用新实现。Adapter 的移除时间应该晚于 Tool Catalog 缓存、客户端升级和回滚窗口三者中的最长时间。

适用场景

这套方法特别适合：

MCP Server 有多版本客户端同时接入。
Agent 平台由多个团队独立发布 Tool。
Schema 经常增加业务字段。
金融和企业 SaaS 等不能接受静默失败的系统。
Tool Catalog 被网关或客户端缓存的场景。

常见误区

误区一：有 strict 就不会出问题。strict 约束的是单次生成结果是否符合当前 Schema，不解决旧客户端、新服务端、缓存旧 Schema 和语义变化。
误区二：只要新增字段不是 required 就一定兼容。在 rolling deployment 中不成立。新客户端可能把新增字段发送给旧服务端，尤其当旧 Schema 设置 additionalProperties:false 时。
误区三：只给 Tool 增加一个 version 字段就算版本治理。如果 version 没进入流量日志、兼容矩阵、灰度策略和回滚机制，它只是元数据，不是治理能力。
误区四：Shadow Replay 可以直接执行所有工具。不可以。任何写操作、支付、删除、消息发送、下单或外部副作用工具，都应该使用 mock、sandbox 或只做契约验证。
误区五：删除旧 Tool 后客户端会立刻刷新。在 Tool Catalog 可缓存的体系里，这个假设很危险。发布设计必须显式考虑 TTL 和旧目录存活时间。

上线检查清单

总结

工具契约一旦成为 Agent 的运行时依赖，就应该像数据库 Schema 和公开 API 一样治理。真正可靠的升级标准不是「新版本能跑」，而是旧世界和新世界在整个灰度窗口内都不会互相打坏。

参考资料

Model Context Protocol — The 2026-07-28 Specification：https://blog.modelcontextprotocol.io/posts/2026-07-28/
Model Context Protocol — Tools Specification：https://modelcontextprotocol.io/specification/draft/server/tools
MCP SEP-2106 — Tools inputSchema & outputSchema Conform to JSON Schema 2020-12：https://modelcontextprotocol.io/seps/2106-json-schema-2020-12
MCP SEP-2596 — Specification Feature Lifecycle and Deprecation Policy：https://modelcontextprotocol.io/seps/2596-spec-feature-lifecycle-and-deprecation
OpenAI API Reference — Function Tool Schema and strict：https://platform.openai.com/docs/api-reference/fine-tuning/list
JSON Schema — Additional Properties：https://tour.json-schema.org/content/03-Objects/02-Additional-Properties