at dawn技术手记
← 返回文章

工具调用的关键,是一份清楚的接口契约

让参数可验证、操作可重试、结果可理解。工具接口决定了 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 令牌和文件系统权限都应限制在任务所需范围。模型只能提出调用请求,不能自行扩大自己的权限。

先把一个小工具做得清楚、稳定、可审计,往往比一次接入很多工具更有价值。