面向 Agent 的工具设计

面向 agent 的工具设计关注的不只是 API 能不能用，而是模型能不能稳定理解、正确调用并从结果中继续推进任务。

#tech / ai #type / concept #status / growing

[!info] related notes

面向 Agent 的工具设计

一句话定义

面向 Agent 的工具设计是为 AI Agent 设计可调用工具的原则与方法，核心目标是让模型能稳定理解、正确调用工具，并从返回结果中继续推进任务。

核心机制 / 工作原理

核心原则

一个给人类工程师用起来还行的 API，不一定适合 agent。面向 agent 的工具设计强调：

  1. 清晰描述：工具名称和描述必须准确反映功能，让模型无需猜测
  2. 最小参数：只暴露必要参数，减少模型犯错的表面面积
  3. 错误处理：返回结构化错误信息，让模型能理解失败原因并重试
  4. 幂等性：相同调用多次执行结果一致，允许安全重试
  5. 职责单一：一个工具做一件事，避免语义重叠导致模型选择困难

工具描述设计

自然语言描述

{
  "name": "search_files",
  "description": "在项目目录中搜索文件内容。返回匹配的文件路径和行号。用于查找函数定义、变量引用或配置项。",
  "parameters": {
    "query": {
      "type": "string",
      "description": "搜索关键词或正则表达式"
    },
    "path": {
      "type": "string",
      "description": "搜索的根目录路径，必须是绝对路径"
    }
  }
}

参数 Schema 设计要点

  • 用 description 字段解释每个参数的含义和格式约束
  • 对枚举值用 enum 限制，而非仅靠描述
  • 必填参数标 required，可选参数给默认值
  • 路径参数要求绝对路径，避免相对路径歧义

返回值格式

{
  "success": true,
  "results": [
    {"file": "/src/app.ts", "line": 42, "content": "function main() {"}
  ],
  "total": 1
}

返回值应包含：操作是否成功、结果数据、错误信息（失败时）。

常见工具模式

模式示例设计要点
搜索文件搜索、grep、数据库查询返回摘要而非全文，支持分页
读取读文件、查日志限制返回行数，支持 offset
写入创建/编辑文件幂等、返回 diff 或确认
执行运行命令、调用 API超时控制、输出截断、错误码

与 Function Calling 的关系

Function Calling 是 LLM 暴露工具调用意图的接口协议（模型输出结构化的函数名 + 参数）。工具设计是在此之上决定”工具长什么样”。

Function Calling schema 只是接口外壳，不覆盖可用性细节。面向 agent 的工具设计是让这个外壳对模型真正友好。

最小例子

反面：文件编辑工具要求模型自己数清行号、写容易错位的 diff header、路径基于当前目录推断 — 模型很容易在格式和路径上犯错。

正面：工具要求绝对路径、接受自然语言补丁格式（如 “在第 42 行后插入以下内容”）、返回明确的错误信息 — 稳定性显著提升。

设计反模式

  • 参数过多：超过 5 个必填参数时模型出错率显著上升
  • 描述模糊："process data" 这种描述无法让模型判断何时该调用
  • 错误信息不结构化：返回 Error 而非 {"error": "file not found", "path": "/foo"} 让模型无法自主恢复
  • 语义重叠：search_files 和 find_in_files 功能重叠，模型不知选哪个
  • 脆弱格式要求：要求模型精确拼装 diff header、JSON 嵌套等易错格式
  • 不幂等：创建操作不检查是否已存在，重试导致重复

边界与常见误解

  • 不等于”多写一点文档”：还包括参数、格式和错误面的结构设计
  • 不等于单纯的 function schema 定义：schema 只是接口外壳，不覆盖可用性细节
  • 如果工具本身难用，再强的模型也会被接口摩擦拖垮
  • 工具设计是迭代的：观察 agent 的实际调用失败模式，持续优化描述和参数
创建于 2026/5/4 更新于 2026/5/27