AI Agent 工具参数经常缺字段时怎么收紧 schema

AI Agent 调工具时，最常见的失败不是模型不会调用，而是工具契约允许“看起来像参数、实际上缺字段”的请求进入执行层。收紧 schema 的关键也不是把提示词写得更长，而是把必填字段、字段类型、未知字段和错误回传固定成一份可校验的契约：先在参数校验器拦截，再把字段路径和修复建议交还给 Agent，只有通过校验的请求才进入工具执行器。

先把工具参数分成必填、可选和条件必填

工具定义里的 properties 只是声明字段形状，不代表字段一定存在。真正不能缺的字段要放进 required；不影响调用的字段保留为可选；只有在某个模式出现时才需要的字段，则要写成条件约束，而不是继续堆提示词。

例如“创建工单”至少需要标题和优先级，附件可以省略；当 channel 是 email 时，recipient 又必须出现：

{
  "type": "object",
  "properties": {
    "title": {"type": "string", "minLength": 1},
    "priority": {"type": "string", "enum": ["low", "normal", "high"]},
    "channel": {"type": "string", "enum": ["console", "email"]},
    "recipient": {"type": "string", "format": "email"},
    "attachment_url": {"type": "string", "format": "uri"}
  },
  "required": ["title", "priority", "channel"],
  "additionalProperties": false
}

这里的 required 解决“经常缺字段”，enum 和 format 解决“字段有了但值不对”，additionalProperties: false 则避免模型把未定义的 note、userId 等字段悄悄塞进执行层。条件必填不能靠这段基础对象规则硬凑，应在校验器里用 if/then 或等价的业务规则明确表达。

按负载、约束和失败代价选择严格程度

收紧 schema 不是所有字段都一律必填。先看工具的业务负载：写入、扣款、发消息这类有副作用的工具，宁可多拒绝一次，也不要猜默认值；只读搜索可以允许分页参数使用默认值，但查询主体仍要必填。

严格模式的代价是兼容性：旧 Agent 可能还会发送历史字段。迁移时可以先记录未知字段，再在灰度阶段拒绝；但不要在业务执行器里静默丢弃字段，否则调用方以为成功，实际数据已经不完整。

把校验错误写成模型可修复的回传

“invalid arguments” 对 Agent 几乎没有修复价值。错误至少应告诉它哪一个路径失败、失败类别是什么、期望值是什么，以及是否允许重试。下面是一个只包含公开信息的错误信封示例：

{
  "ok": false,
  "error": {
    "code": "SCHEMA_VALIDATION_FAILED",
    "path": "$.priority",
    "reason": "required",
    "expected": "one of low, normal, high",
    "repair": "补齐 priority，并重新提交原请求"
  },
  "retryable": true
}

校验器可以把多个字段错误合并成数组，避免 Agent 一次只修一个字段。不要把内部堆栈、数据库表名、令牌或第三方响应原样回传；外部错误是修复协议，内部日志才是诊断材料。

给重试加上边界，避免 Agent 自己循环

可以重试的通常是缺字段、类型不符、枚举值错误这类参数问题；鉴权失败、资源不存在、业务状态冲突和工具执行超时，处理方式不同，不能统一标成 retryable: true。建议把重试次数、错误码和调用 ID 写入 Telemetry，并让 RetryPolicy 只接受白名单错误。

def should_retry(error, attempt):
    # 只允许参数可修复错误重试，并限制次数
    repairable = {"SCHEMA_VALIDATION_FAILED", "INVALID_ENUM"}
    if error.get("code") not in repairable:
        return False
    return attempt 

真实系统还应给每次调用生成关联 ID，并区分“模型修复后再次提交”和“网络层重复提交”。对有副作用的工具，幂等键比单纯增加重试次数更重要。

常见问题

只写 properties，为什么 Agent 还是漏传字段？

因为 properties 只声明字段，未声明必填关系。没有合理默认值的字段要加入 required。

additionalProperties 设为 false 会不会太严格？

对写操作通常值得严格；对正在迁移的只读工具，可以先记录未知字段，再按兼容计划逐步拒绝。

缺字段时应该让模型自己补默认值吗？

只有默认值不会改变业务含义时才可以补。金额、收件人、权限范围等字段不要猜，直接返回可修复错误。

校验通过后还需要业务校验吗？

需要。schema 负责结构和基础取值，权限、资源存在性、状态冲突和幂等性仍应由业务层判断。

收紧 schema 的最终目标不是让 Agent 永远不出错，而是让错误尽早发生、信息足够具体、修复路径可控。把 schema、Validator、ErrorEnvelope 和 RetryPolicy 分开，工具执行器就能专注于业务结果，调用链也更容易定位。