Files
agent/docs/tool-design.md
T

66 lines
2.1 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 专属参数一律设为**可选**;
- 工具 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 数组每轮请求完整重发。新工具进来时,先问"能不能装进已有工具",再问"要不要新建"。