[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Function Schema, Tool Runtime

Tool Argument Validation

一句话定义

Tool Argument Validation 是在执行工具前校验 LLM 输出的参数是否符合 JSON Schema 的过程。LLM 可能传入格式错误的参数（如日期格式错误、类型不对），校验可以提前发现问题。

核心原理

校验内容

校验项	例子	说明
类型	string vs int	参数类型是否正确
必填	query 是必填	required 字段是否都有
范围	limit 在 1-100	数值范围是否合法
格式	date 是 YYYY-MM-DD	格式是否正确
枚举	status 只能是 active/inactive	值是否在允许范围内

Python 实现

使用 jsonschema 的 Draft 2020-12 校验器。schema 来自受信工具定义，启动时先检查；format 需要显式启用检查器，且仅检查所支持的格式。具体模型接受的 schema 子集由接口适配层处理。

from jsonschema import Draft202012Validator, FormatChecker

schema = {
    "type": "object",
    "properties": {
        "query": {"type": "string", "minLength": 1},
        "limit": {"type": "integer", "minimum": 1, "maximum": 100},
        "date": {"type": "string", "format": "date"},
    },
    "required": ["query"],
    "additionalProperties": False,
}
Draft202012Validator.check_schema(schema)
validator = Draft202012Validator(schema, format_checker=FormatChecker())


def validate_arguments(arguments: object) -> tuple[bool, str]:
    error = next(validator.iter_errors(arguments), None)
    if error is None:
        return True, ""
    # 只反馈位置和规则，不回显完整实例或异常原文。
    return False, f"invalid at {list(error.absolute_path)} ({error.validator})"

assert validate_arguments({"query": "test", "limit": 200})[0] is False

示例错误路径也属于输入相关数据，转发前需限制长度并按业务筛选。schema 校验不完成对象归属、授权或当前业务状态检查；工具执行入口必须继续检查这些条件。

参数修复

修复只产生新候选，不授予执行权限：

限制原始输入大小 → JSON 解析 → schema 校验
失败且允许修复 → 返回必要的字段约束，要求模型修复
再次限制大小、解析与校验（每个候选都要检查）
通过 → 检查资源、权限、业务状态和既有授权
达到尝试数/时间预算或意图不明确 → 返回失败或请求澄清

不能把 llm.chat 的结果 json.loads 后直接执行，也不能让模型补造金额、对象身份或用户尚未决定的内容。完整 repair 与执行重试的区别见 参数校验与重试机制。

常见坑

1. 不做校验: LLM 传了非法参数直接执行
2. 校验错误信息不清楚: LLM 不知道怎么修复
3. 修复后不再校验：新的候选同样不可信
4. 把 schema 错误当用户错误：无效 schema 是服务端配置缺陷，应在注册时发现

参考资料

• jsonschema
• Function Schema