AI Agent / 系统课时

校验工具参数

校验工具参数

本篇解决智能体调用工具时参数不可靠的问题,通过 Schema 在执行前检查输入结构、类型和约束。完成后,工具系统可以拒绝缺失字段和非法数据,避免错误请求进入真实执行阶段。

学习目标

  • 理解为什么工具调用需要参数校验
  • 使用 Schema 定义工具输入规则
  • 在执行前拦截非法参数

工具调用中的参数风险

语言模型生成的参数来自概率预测,即使工具描述清晰,也可能出现字段遗漏、类型错误或格式不符合要求的情况。

例如 Git 工具需要接收路径参数时,模型可能生成空路径、错误类型或者不存在的字段。如果直接执行,会导致运行失败甚至产生安全问题。

参数校验层应该位于模型和工具执行器之间:

模型输出 → Schema 校验 → 工具执行 → 返回结果

使用 Schema 定义输入规则

可以使用 Pydantic 定义工具参数模型,将字段要求集中管理。

python
from pydantic import BaseModel, Field


class GitDiffInput(BaseModel):
    # 限制查询范围,避免传入未知目录
    path: str = Field(default=".")
    max_lines: int = Field(default=200, ge=1, le=1000)


params = GitDiffInput(path="src", max_lines=100)
print(params.model_dump())

预期输出

text
{'path': 'src', 'max_lines': 100}

Schema 不仅描述字段存在性,还可以表达取值范围。

在执行前拦截错误输入

工具执行器应该先验证参数,再调用实际逻辑。

python
from pydantic import ValidationError

try:
    GitDiffInput(path="src", max_lines=5000)
except ValidationError as error:
    print(error.errors()[0]["msg"])

预期输出

text
Input should be less than or equal to 1000

这样错误会在进入 Git 执行阶段前被发现。

设计校验规则

不同工具需要不同级别的约束。

参数类型 校验重点
路径 是否允许访问、是否存在
数字 范围限制
枚举 是否属于允许集合
字符串 长度和格式

对于高风险工具,还需要增加权限检查。例如文件修改工具不仅要检查参数格式,还要确认用户是否授权。

常见失败处理

参数校验失败后,不应该直接返回模糊错误。工具系统应返回结构化信息,让 Agent 能够修正调用。

例如:

json
{
  "error": "invalid_parameter",
  "field": "max_lines",
  "message": "value must be between 1 and 1000"
}

预期结果

text
Agent receives validation error and can regenerate corrected arguments.

本课总结

  • Schema 校验是模型输出和工具执行之间的重要安全层。
  • 参数规则应该同时约束类型、范围和业务边界。
  • 结构化错误信息可以帮助智能体自动修正调用。

下一课预告

下一课将继续完善工具调用系统,学习如何处理工具执行失败、重试和异常恢复。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

校验工具参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通