给 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」可靠得多。
四、返回值要稳定、可读、可继续推理
工具返回的东西会直接进入模型的上下文,所以它应该:
- 结构稳定:成功和失败用同一种外层结构;
- 信息足够:包含 ID、关键字段、以及「下一步能做什么」;
- 不要塞无关的大段文本:上下文是稀缺资源。
{ "ok": true, "data": { "id": "o_123", "status": "open" }, "next": "可用 get_order 查看详情" }
{ "ok": false, "error": "invalid_status", "message": "status 只能是 open/paid/cancelled" }
失败信息要写「人能看懂、模型能据此改正」的话,而不是抛一个堆栈。
五、写操作要幂等或可确认
模型会重试,网络也会重试。发送消息、创建订单、转账这类操作,重复执行一次可能就是事故。
两个办法:
- 幂等键:客户端生成
request_id,服务端去重; - 两段式:先
prepare拿到确认令牌,再commit执行。
至少要做到:危险操作在描述里明确写「会写数据/会通知他人」,让模型知道后果。
六、最小权限:只暴露完成当前任务所需的工具
工具清单就是 Agent 的能力边界。给一个聊天机器人配上 exec 和 write_file,
等于把整台机器交给了任何能对它说话的人。
我的做法是分层的:
- 只读层:查询、搜索、读配置;
- 受限写层:只能改自己会话内的数据,带白名单;
- 管理操作:不暴露给模型,只留给人在后台做。
这一层往往由宿主程序实现,而不是靠提示词「请不要执行危险操作」——后者只能算礼仪,不能算安全。
补充:可观测性
每个工具调用都应该留下记录:谁调的、参数是什么(敏感字段脱敏)、耗时、结果。 出问题时,这是唯一能还原「Agent 到底做了什么」的证据。
小结
把工具当成给别人用的 API来设计:名字清楚、描述完整、参数受控、返回可读、 写操作安全、权限最小。做到这些,模型的工具调用成功率会明显提升, 而你在排查「它为什么乱调」时也会轻松很多。