工具调用的关键,是一份清楚的接口契约
让参数可验证、操作可重试、结果可理解。工具接口决定了 Agent 能走多远。
工具是模型与真实系统之间的边界。这个边界越明确,系统越容易预测,也越容易修复。
参数需要表达约束
一个好的工具定义不只是函数名和描述。它还应该约束参数类型、可选值、必要字段,以及允许访问的资源范围。读取日志的工具可以接收时间范围和服务名称,而不必直接接收任意 shell 命令。
{
"name": "read_service_logs",
"parameters": {
"service": "api",
"since_minutes": 30,
"max_lines": 100
}
}
模型生成的参数始终需要在服务端再次校验。界面上隐藏一个选项,并不能阻止无效参数被发送到接口。
重试必须考虑副作用
读取操作通常可以安全重试。发送邮件、创建订单和修改权限等操作,则需要幂等键或重复检测。网络超时只表示客户端没有收到确定结果,不能据此判断服务端没有执行。
对会改变外部状态的动作,可以分成准备与执行:先生成可审阅的草稿,再根据任务授权执行。这样能让使用者理解系统即将做什么。
错误也属于接口
错误返回应当区分参数错误、权限不足、资源不存在和临时服务故障。明确标记哪些错误可以重试,能减少模型反复尝试同一个无效请求。
{
"ok": false,
"error": {
"code": "RATE_LIMITED",
"retryable": true,
"retry_after_seconds": 20
}
}
把权限交给执行层
提示词可以解释规则,但权限检查必须由工具服务执行。数据库账号、API 令牌和文件系统权限都应限制在任务所需范围。模型只能提出调用请求,不能自行扩大自己的权限。
先把一个小工具做得清楚、稳定、可审计,往往比一次接入很多工具更有价值。