Files
agent/docs/tool-design.md
T

3.2 KiB
Raw Blame History

LLM 工具接口设计规范

一、合并还是分开

共享同一标识空间 + 同一生命周期 → 合并为一个工具,用 op 分派。否则分开。

二、动词表

按资源性质选:

资源性质 动词
持久化资源(存在/不存在两态) list / get / create / update / delete
可开关资源 上面 + enable / disable
瞬时动作(无持久状态) run,单独成工具

表按资源选动词:动作作用于持久资源时(如技能的 run)并入该资源工具的 op 集;「run 单独成工具」只针对资源本身无持久状态、只剩动作的情形(terminal、fetch 类)。

跨工具统一用词:枚举 list、读单个 get、新建 create、删除 delete。

三、参数的放置

默认全部展开为顶层 properties。

  • 跨 op 共享的参数放顶层,description 说明哪些 op 用它;
  • op 专属参数也放顶层,description 说明 op=X 时必填;
  • 仅当参数结构在工具定义时无法确定时,才用自由对象 { "type": "object" }。
  • 互斥的多动作一律用枚举开关 op + 各自顶层参数,不要把动作编码进键名:键名方案无法用 required 约束(漏键只能到运行时才发现),弱模型也更容易漏写。

四、条件必填

  • op 专属参数一律设为可选;
  • 工具 description 用紧凑格式列依赖:
op=list    无参数。
op=create  需要 A 和 B。
op=delete  需要 id。
  • 参数 description 补一句"op=X 时使用"。

五、错误处理

  • 分派的 default 分支列出可用 op;
  • 报错回显:哪个 op、缺哪个字段;
  • 代码里做校验,不只依赖 schema。

六、内容分工

内容 位置
有哪些 op、每个 op 要什么参数 tool schema
op 之间的依赖 tool description
跨工具的动作指令 system prompt
动词表、命名约定 开发文档

system prompt 不重复 schema 已表达的内容。

七、配套工具

成对出现的工具("执行动态能力" + "查询其 schema")相互依赖。删一个前先确认另一个的定位是否随之改变。

八、上下文成本

tools 数组每轮请求完整重发。新工具进来时,先问"能不能装进已有工具",再问"要不要新建"。

九、回执形态

  • 内容型工具(read_file 的文本、fetch 的正文、db 的查询结果)回执就是内容本身,不要套 JSON 信封。
  • 结果型动作(读图、裁剪、转换)回执用单个 JSON 对象,把判定写进字段,不写自然语言:模型按字段分支, 不要再让它从句子里猜。字段名跨工具保持一致:ok(调用是否成功)/ reason(稳定枚举)/ retryable / width height 之类的事实字段 / hint(仅解释,不承载判定)。
  • 回执可能被多层改写(发送前裁剪、同回合去重、投递失败降级):改写只动字段,不得在 JSON 后追加句子—— 追加会把回执变成不可解析的尾巴,等于把判定权又还给语义猜测。
  • ok:true 不等于「结果已送达」:另有字段(如 image_attached)描述投递状态,两者不要混成一个布尔。