《AI Agent 技术原理与架构·运行时、协议与系统架构》5.1 工具契约:schema、错误与版本

工具与 Agent 之间是契约,不是自由调用。契约由三部分构成:参数 schema、错误分类、版本演进。实验实现最小 JSON Schema 校验器与可重试/永久错误分类器,演示新增必填字段 mode 如何破坏旧调用。结论是参数在入口被拦截、错误在源头分类、版本破坏可被检出。

以下 schema、错误消息、版本号均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。RETRYABLE_KEYWORDS 的三组关键词是讲解用的启发式,真实系统用结构化错误码分类,但"新增必填字段会破坏旧调用"这一条不变。

Agent 调用工具,看起来是一次调用。但生产里这次调用是契约:工具方声明"我能接收什么参数、会怎样失败、怎么演进",Agent 方必须遵守。把工具当成自由调用,是工具层最常见的坑。

工具契约由三部分构成:参数 schema(调用必须符合)、错误分类(哪些可重试)、版本演进(新增必填字段会破坏旧调用)。这一节把三部分分别讲清,并给出最小实现。

参数 schema:在入口拦截,而不是在副作用之后

工具不能接收任意参数。schema 定义"哪些参数必填、每个参数什么类型"。

schema 声明含义
required: [“file”]file 必填
properties: {“file”: “string”, “limit”: “int”}file 是字符串,limit 是整数

schema 的价值在入口拦截:参数不合法,调用根本不该进入工具。如果等到工具执行到一半才发现参数类型错了,副作用可能已经发生——这正是 1.1 说的"副作用已发生未记录"的一种来源。校验器把"参数合法"变成调用前的硬前提。

错误分类:哪些值得重试

工具失败后,系统要决定是否重试。错误分类把失败分成两类:

分类例子重试
可重试timeout、rate_limit、busy、unavailable值得(见 5.2 退避)
永久invalid schema、unknown field不值得,重试也失败

永久错误重试是浪费。 参数非法、字段不存在,重试一百次也一样失败,只会放大副作用风险。分类的目的是让重试只花在"可能变好"的失败上。

版本演进:新增必填字段破坏旧调用

工具会演进:加参数、改类型、改必填。版本演进要回答"这个改动破坏旧调用吗"。

改动是否破坏例子
新增可选字段否加个可选的 trace_id
新增必填字段是mode 变成必填,旧调用没传就失败
移除字段可能移除必填字段,新调用读不到旧数据

破坏性改动最常见的形态就是"新增必填字段"。 工具方加了一个必填参数,觉得"反正新版本要它",但所有旧调用方都没传——调用在入口被 schema 拦截,报"missing required"。版本检查要提前检出这类破坏,而不是等上线后旧调用爆。

最小实验:校验、分类与版本检查

实验实现最小 JSON Schema 校验器、错误分类器与版本演进检查器。

# file: agp_lab/tool_contract.py | write
# tier: 3
# verify: python3 -m unittest tests.test_tool_contract
"""工具契约:参数校验、错误分类与版本演进。

工具与 Agent 之间是契约,不是自由调用。契约由三部分构成:
参数 schema(调用必须符合)、错误分类(哪些可重试)、
版本演进(新增必填字段会破坏旧调用)。

本模块实现一个最小 JSON Schema 校验器、可重试/永久错误
分类器,以及一个"新增必填字段破坏旧客户端"的演示。
"""
from __future__ import annotations

from typing import Any

RETRYABLE_KEYWORDS = ("timeout", "rate_limit", "throttl", "unavailable", "busy")


def validate(schema: dict[str, Any], params: dict[str, Any]) -> list[str]:
    """校验 params 是否符合 schema,返回错误列表。

    schema 形如 {"required": ["file"], "properties": {"file": "string"}}。
    """
    errors: list[str] = []
    for required in schema.get("required", []):
        if required not in params:
            errors.append(f"missing required '{required}'")
    for key, expected in schema.get("properties", {}).items():
        if key in params:
            actual = params[key]
            ok = isinstance(actual, str) if expected == "string" else isinstance(actual, (int, float))
            if not ok:
                errors.append(f"'{key}' 应为 {expected}")
    return errors


def classify_error(message: str) -> str:
    """把错误消息分为可重试(retryable)或永久(permanent)。"""
    lowered = message.lower()
    for keyword in RETRYABLE_KEYWORDS:
        if keyword in lowered:
            return "retryable"
    return "permanent"


def contract_version(schema_v1: dict[str, Any], schema_v2: dict[str, Any]) -> dict[str, str]:
    """版本演进:找出新增必填字段(会破坏旧客户端)与新增可选字段。"""
    required_v1 = set(schema_v1.get("required", []))
    required_v2 = set(schema_v2.get("required", []))
    added_required = sorted(required_v2 - required_v1)
    new_properties = set(schema_v2.get("properties", {})) - set(schema_v1.get("properties", {}))
    added_optional = sorted(new_properties - required_v2)
    return {"breaking": added_required, "compatible": added_optional}


def demo() -> dict[str, Any]:
    schema_v1 = {"required": ["file"], "properties": {"file": "string", "limit": "int"}}
    schema_v2 = {"required": ["file", "mode"], "properties": {"file": "string", "limit": "int", "mode": "string"}}
    return {
        "valid": validate(schema_v1, {"file": "a.txt", "limit": 5}),
        "missing": validate(schema_v1, {"limit": 5}),
        "bad_type": validate(schema_v1, {"file": 1}),
        "error_retryable": classify_error("upstream timeout after 30s"),
        "error_permanent": classify_error("invalid schema: unknown field"),
        "version_v1_v2": contract_version(schema_v1, schema_v2),
    }


if __name__ == "__main__":
    for key, value in demo().items():
        print(f"{key}: {value}")

运行:

cd private/labs/agp-lab
python3 -m agp_lab.tool_contract

输出:

valid: []
missing: ["missing required 'file'"]
bad_type: ["'file' 应为 string"]
error_retryable: retryable
error_permanent: permanent
version_v1_v2: {'breaking': ['mode'], 'compatible': []}

六行输出对应契约的三个部分:

  1. 参数校验:valid: [](无错误,通过);missing 检出缺了必填的 file;bad_type 检出 file 传成了整数('file' 应为 string)。三个场景覆盖"通过、缺必填、类型错"。
  2. 错误分类:error_retryable: retryable(upstream timeout 命中关键词)、error_permanent: permanent(invalid schema 不命中)。分类器把"哪个错误值得重试"变成自动决定。
  3. 版本演进:v1→v2 新增了必填字段 mode,breaking=['mode'];没有新增可选字段,compatible=[]。这一行是上线前的预警:升级到 v2 会破坏所有没传 mode 的旧调用。

一个值得点破的实现细节:版本检查里 added_optional = new_properties - required_v2——新增字段里刨掉必填的,剩下的才是兼容的。如果新加字段同时也是必填,它不算 compatible,会被正确归到 breaking。这个区分是"新增字段"不总是安全的直接解释。

工具契约的管理,在团队里最容易演变成"文档和代码各说一套"。schema 既要给 Agent 用(决定能不能调用),也要给人看(决定怎么实现)。单一权威来源是关键:schema 定义在工具实现里,文档和调用方都从它生成,而不是反过来。

schema 使用方消费方式违约后果
Agent 运行时校验调用参数坏参数进工具
工具实现作为实现的约定实现与契约不一致
测试生成用例测试覆盖不到契约
文档生成 API 文档文档与实际脱节

错误分类也一样要进契约。工具方有义务在契约里声明"哪些错误是可重试的",而不是让 Agent 方猜关键词。实验里的 RETRYABLE_KEYWORDS 是讲解用的启发式,生产里应该用结构化错误码——工具返回带语义的错误类型,Agent 侧据此决定重试策略,而不是去字符串匹配。

版本演进还有一个实践要点:兼容性检查要绑定发布流程。工具 schema 改动时,跑一次版本检查,如果检出 breaking 变更,就强制走"发布新版本 + 旧调用方迁移"的路径,而不是静默吞掉。

工具契约的测试策略是保证 schema 与实现一致的手段。三类测试各司其职:

测试验证什么失败信号
契约测试schema 与实现一致实现违背 schema
参数校验测试非法输入被拒坏参数穿透
生成用例按 schema 自动出用例覆盖不足

契约测试要双向跑:从 schema 生成对实现的测试(实现必须满足声明),也从实现生成对 schema 的测试(schema 必须真实反映实现)。单向测试只防一半——只测 schema 侧,实现悄悄加了约束却不在 schema 里声明,调用方按 schema 传参就会撞上未声明的失败。

契约的失败模式还有一个常见形态:工具返回错误时绕过契约。工具实现里 if 失败直接抛异常,schema 里的错误声明形同虚设;Agent 侧拿到的不是结构化错误,是原始异常。契约要把错误也声明进去(见实验的错误码思路),实现必须从声明的错误路径返回。

工具契约还有一个被低估的消费方:人。schema 不只是给 Agent 看的,也是给人(实现者、审核者、文档读者)看的。一个 schema 字段名模糊、缺描述、没有示例,Agent 能调用但人看不懂,工具实现就会偏离契约。schema 的可读性直接决定契约能否被维护——给字段加描述、加示例,是契约工程的一部分。

schema 消费方需要什么缺失后果
Agent 运行时结构完整调用失败
工具实现者字段语义实现偏离
审核者能力边界越权漏审
文档读者示例误解用法

版本与弃用也要写进 schema。 字段加 deprecated 标记、工具版本字段显式声明,消费者才能做迁移决策——Agent 侧看到 deprecated 就换新字段,实现侧看到版本号就知道该往哪迁移。schema 是契约,契约就要带演化信息,而不是只有当前快照。

工具契约还有一个边界:工具返回体的 schema。 参数 schema 决定"怎么调用",返回 schema 决定"结果怎么解析"。Agent 侧解析返回结构,若返回 schema 不声明(自由文本返回),Agent 只能靠猜测解析。返回 schema 缺失是契约最容易被忽略的半边——工具方常只声明入参,把返回当"自由发挥",结果 Agent 侧的解析逻辑跟着漂。

契约半边声明什么缺失后果
入参 schema怎么调用参数错、调用失败
返回 schema结果怎么解析解析乱、结果误用
错误 schema失败怎么表达错误被当正常结果

契约与文档的同步是另一个运维点:schema 变了文档没变,新 Agent 按文档调用旧参数就出错。契约单一权威 + 文档从契约生成(见 5.1 的"单一权威来源"),才能保证文档与 schema 永远一致——schema 是源代码,文档是产物。

工具契约的变更要像接口变更一样走流程。 加字段、改必填、删字段,不是"改个 schema 就完"——契约变更影响所有已接入的 Agent 与工具实现(见 6.3 版本兼容)。生产上契约变更走"变更单 → 兼容评估 → 灰度 → 全量"的路径,破坏性变更要有显式标记,不能静默升级。

契约变更兼容性处理
加可选字段兼容直接发布
改必填破坏向后版本 + 迁移窗口
删字段破坏向前版本 + 兼容层

架构判据

工具契约是否合格,用五条判据检查:

判据合格的样子不合格的样子
参数入口校验调用前拦下非法参数副作用发生后才报参数错
错误分类可重试/永久明确区分全部当可重试处理
版本检查破坏性改动上线前检出上线后旧调用爆了才发现
契约单源schema 有一份权威定义schema 散落、口径不一
兼容性口径新增必填=破坏,新增可选=兼容把新增必填当兼容

判据第三条"版本检查"特别重要:工具演进要在发布前用版本检查器验证兼容性,而不是靠测试撞出来。判据第五条澄清一个常见误区:不是"新增字段就兼容",而是"新增可选字段兼容,新增必填字段破坏"。

小结

  • 工具契约由 schema、错误分类、版本演进三部分构成;工具不是自由调用。
  • 参数在入口拦截,避免"副作用已发生才发现参数错"。
  • 错误分类决定哪些值得重试:永久错误重试是浪费。
  • 新增必填字段会破坏旧调用;版本检查要在上线前检出破坏,而不是上线后爆。

阅读导航:上一节:4.3 能力边界与逃逸面 · 下一节:5.2 校验、幂等与重试 。

常见错误与边界

  1. 把工具当自由调用。 没有 schema 的调用是拿副作用赌运气;契约要让参数合法成为入口前提。
  2. 所有错误都重试。 永久错误重试只会放大副作用风险;分类器要区分可重试与永久。
  3. 新增必填字段当兼容。 新增可选才兼容,新增必填即破坏;版本检查要刨掉必填再判。
  4. 版本破坏上线后才发现。 版本检查进发布流程,破坏性改动要在发布前被拦截。
  5. schema 散落多份。 工具方、Agent 方、文档各一份 schema,迟早口径不一;要单一权威定义。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图