Files
agent/docs/tool-design.md
T

81 lines
3.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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 后追加句子——
追加会把回执变成不可解析的尾巴,等于把判定权又还给语义猜测。
- **回执是「那次调用」的历史事实,不是当前状态**:发送侧为了省 token 省略内容时,不要改写回执
(典型错例:把当时成功的图片投递改写成 `image_attached:false`)。模型会把历史读图当成失败,
于是反复重读同一条;省略、重放、缓存这类传输层细节不属于回执语义。
- `ok:true` 不等于「结果已送达」:另有字段(如 `image_attached`)描述投递状态,两者不要混成一个布尔。