2026-09-11 · AI Agent · 约 7 分钟

给 Agent 设计工具接口的六个原则

给 Agent 写工具,和在框架里写一个函数是两件事。函数是给人用的:调用者知道上下文、看得懂类型、出错会去看堆栈。 工具是给模型用的:它只读得到名字、描述和参数 schema,然后据此决定调不调、怎么调。

换句话说,工具的描述本身就是提示词的一部分。下面是我踩过坑之后总结的六条。

一、名字要说明「做什么」,不是「怎么实现」

模型在选工具时,最先看的是名字。下面两组名字,效果差别很大:

# 差
db_query_v2 / do_thing / process

# 好
search_orders_by_customer / send_email / list_open_tickets

「动词 + 对象」比缩写好;避免版本号、内部代号和「process」这种万能词。 同一类工具用同一套前缀,模型更容易在它们之间做选择。

二、描述要写清楚边界、输入和失败

一段合格的描述至少回答四个问题:

我见过最典型的失败是「两个工具功能重叠,描述又都很含糊」,模型只能随机挑一个, 然后在参数上瞎猜。

三、参数宁少勿多,但要能表达约束

参数越多,模型填错的概率越高。能通过上下文推断的,就不要做成参数。 但必要的约束要显式写进 schema:枚举、范围、必填、格式。

{
  "name": "search_orders",
  "parameters": {
    "customer_id": { "type": "string", "required": true },
    "status": { "type": "string", "enum": ["open", "paid", "cancelled"] },
    "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
  }
}

有枚举就别用自由字符串;能限制范围就别让模型猜。 参数校验放在服务端,比在提示里写「请不要超过 100」可靠得多。

四、返回值要稳定、可读、可继续推理

工具返回的东西会直接进入模型的上下文,所以它应该:

{ "ok": true, "data": { "id": "o_123", "status": "open" }, "next": "可用 get_order 查看详情" }
{ "ok": false, "error": "invalid_status", "message": "status 只能是 open/paid/cancelled" }

失败信息要写「人能看懂、模型能据此改正」的话,而不是抛一个堆栈。

五、写操作要幂等或可确认

模型会重试,网络也会重试。发送消息、创建订单、转账这类操作,重复执行一次可能就是事故。

两个办法:

  1. 幂等键:客户端生成 request_id,服务端去重;
  2. 两段式:先 prepare 拿到确认令牌,再 commit 执行。

至少要做到:危险操作在描述里明确写「会写数据/会通知他人」,让模型知道后果。

六、最小权限:只暴露完成当前任务所需的工具

工具清单就是 Agent 的能力边界。给一个聊天机器人配上 exec 和 write_file, 等于把整台机器交给了任何能对它说话的人。

我的做法是分层的:

这一层往往由宿主程序实现,而不是靠提示词「请不要执行危险操作」——后者只能算礼仪,不能算安全。

补充:可观测性

每个工具调用都应该留下记录:谁调的、参数是什么(敏感字段脱敏)、耗时、结果。 出问题时,这是唯一能还原「Agent 到底做了什么」的证据。

小结

把工具当成给别人用的 API来设计:名字清楚、描述完整、参数受控、返回可读、 写操作安全、权限最小。做到这些,模型的工具调用成功率会明显提升, 而你在排查「它为什么乱调」时也会轻松很多。

← 返回首页