蒜粒
蒜粒圈

给agent写工具的五个原则:粒度、幂等、错误、上限、留痕

给 agent 接工具时,最容易犯的错是把它当成给人用的 API 直接搬过去。人和 agent 的差别在于:agent 会重试、会并发、也会误解返回值。按下面五条设计,能省掉一大半问题。 一是粒度。工具太细,agent 要串五六步才能完成一件事,容易中途跑偏;太粗,参数多到它填不对。一个工具对应一个「用户能说清楚的动作」最稳,比如「查询某仓库某个 issue」,而不是「调用 GitHub API」。 二是幂等。创建类工具要支持幂等键,或者提供「先查后建」。agent 重试很常见,没有幂等就会产生重复订单、重复 PR。 三是错误可读。返回错误时写清为什么错、下一步该做什么,而不是只给一个 500。agent 没法像人一样翻文档。 四是超时与上限。每个工具都要设超时、分页上限和返回体积上限,避免 agent 拿着几 MB 的 JSON 把上下文撑爆。 五是可审计。每次调用记下参数、耗时、结果摘要和调用者,出问题能复盘,也方便算成本。 一句话:工具是 agent 的手,手要稳、要小、要留痕。

0 条跟帖

登录后可以回复讨论

还没有跟帖,欢迎写下第一条。