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 校验是模型输出和工具执行之间的重要安全层。
- 参数规则应该同时约束类型、范围和业务边界。
- 结构化错误信息可以帮助智能体自动修正调用。
下一课预告
下一课将继续完善工具调用系统,学习如何处理工具执行失败、重试和异常恢复。
按自己的节奏,确认真正理解。