Agent开发完全实战指南(三)工具设计
上一篇的 Agent 有两个工具:查时间、做加法。玩具而已。
真实的 Agent 动辄十几二十个工具:读文件、查数据库、发 HTTP、跑命令……这时候你会撞上一堆新问题:为什么模型该调工具时不调?为什么它传的参数总是错的?工具返回了 5MB 的日志把上下文撑爆了怎么办?工具执行报错了,是该 panic 还是返回给模型?
这些问题的答案,都藏在"工具设计"这四个字里。
工具是 Agent 与世界交互的唯一出口。工具设计的质量,直接决定了 Agent 能力的上限。 模型再强,工具设计得烂,Agent 也是个废物。
Anthropic 把这件事的重要性提到了和"写 prompt"同等的高度,专门造了个词叫 ACI(Agent-Computer Interface)——你精心设计人机界面(UI),现在也要同样精心设计"机器和机器"的界面。
一、六条核心原则
原则 1:描述即接口,像写 API 文档一样写它
模型靠什么决定"要不要调这个工具、怎么调"?只靠工具的 description 和参数说明。 它看不到你的代码,工具描述就是它唯一的说明书。
对比一下同一个工具的两种描述:
| 糟糕的描述 | 优秀的描述 |
|---|---|
"description": "查询" | "description": "根据订单号查询订单的当前状态。当用户询问某个订单的物流、支付或发货情况时使用。输入必须是完整的订单号(如 ORD-20260921-001)" |
关键洞察:工具描述不是写给人看的注释,是写给模型看的"操作手册"。要写清楚三件事——这个工具做什么、什么时候该用它、输入是什么格式。含糊的描述必然导致模型乱调或不调。
Anthropic 的建议:好的工具定义应包含用法示例、边界情况、输入格式要求。
原则 2:用 JSON Schema 精确约束参数
参数不要只写个 "type": "string" 就完事。能约束的都约束上,把模型犯错的空间压到最小:
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["pending", "shipped", "delivered"],
"description": "要筛选的订单状态"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "返回条数,1-100"
}
},
"required": ["status"]
}
- 用
enum锁死可选值,模型就不会传个"已发货"进来。 - 用
minimum/maximum约束范围。 - 用
required明确哪些必填。
原则 3:错误要"可操作",不要 panic
工具执行失败是常态(文件不存在、网络超时、参数越界)。千万不要让工具 panic 把整个循环搞崩,而要把错误作为一条普通结果喂回给模型,让它自己决定下一步。
// 错误做法:panic,整个 Agent 崩溃
data, err := os.ReadFile(path)
if err != nil {
panic(err)
}
// 正确做法:把错误变成可读信息返回给模型
data, err := os.ReadFile(path)
if err != nil {
return fmt.Sprintf("读取文件失败:%s。请检查路径是否正确。", err), nil
}
关键洞察:给模型一个"可操作的错误",它往往能自我纠正——换个路径、改个参数、或换个工具。给它一个 panic,你的 Agent 直接死给你看。 这是 Agent 鲁棒性的关键设计。
原则 4:控制输出大小
一个工具返回 5MB 的日志,会瞬间撑爆上下文窗口,又慢又贵。工具输出必须有节制:
- 截断:超过阈值就截断,并明确告知"(输出过长已截断,共 N 行)"。
- 结构化:与其返回一大坨原始文本让模型自己 parse,不如在代码里提取关键字段返回。
- 过滤:只返回模型需要的部分。查询数据库返回 1000 行?先聚合、先 TOP N。
原则 5:防呆设计(Poka-yoke)
把参数设计成"很难用错"的样子。 这是 Anthropic 特别强调的一条,源自丰田的防错思想。
他们的经典例子:一个改文件的工具,如果用相对路径,模型经常搞错工作目录导致改错文件;改成强制要求传绝对路径后,出错率大幅下降。
同理:
- 让危险操作需要显式的确认参数(
"confirm": true)。 - 让容易混淆的参数用
enum而不是自由文本。 - 给参数起无歧义的名字(
absolute_path比path好)。
原则 6:只读优先,副作用显眼
- 能只读就只读。查询类工具随便调,副作用小。
- 有副作用的工具(删除、支付、发消息)要在描述里显著标注,并考虑加 human-in-the-loop 确认(第 10 篇细讲)。
二、工具不是越多越好
新手容易走另一个极端:给模型塞 30 个工具,觉得"能力越全越好"。
恰恰相反。工具太多会稀释模型的注意力,降低它选对工具的准确率,还白白消耗上下文(每个工具声明都占 token)。
两个应对策略:
- 合并同类项:
get_user_name、get_user_age、get_user_email合成一个get_user_info。 - 按需暴露:根据当前任务只给模型它需要的那几个工具,而不是全量塞给它。(这点在第 07 篇多 Agent 里会大用。)
LangChain 有句话值得记:"加一个工具,比把推理拆到多个 Agent 里更便宜、更好调试。" 但前提是——加的是设计良好的工具。
三、动手:从玩具工具到真实工具
上一篇工具的"声明"和"执行函数"分散在两个地方(toolDefs 和 toolRegistry),加工具要改两处,容易漏。这一篇我们先做个小重构,把它们绑在一起。
3.1 重构:一个工具 = 声明 + 执行
// ToolSpec 把"给模型的声明"和"实际执行的函数"绑在一起
type ToolSpec struct {
Definition Tool
// Run 接收解析后的参数,返回结果字符串。
// 注意返回 error:业务错误应通过返回值告知模型,这里的 error 仅用于极端情况
Run func(args map[string]any) (string, error)
}
3.2 真实工具 1:读文件(带防呆 + 输出控制)
这个工具综合运用了原则 3、4、5:
import (
"os"
"path/filepath"
"strings"
)
// 沙箱根目录:只允许读这个目录下的文件(防呆:防止读到 /etc/passwd 之类)
const sandboxRoot = "./workspace"
func readFile(args map[string]any) (string, error) {
name, _ := args["path"].(string)
if name == "" {
return "错误:缺少 path 参数", nil // 可操作的错误,喂回给模型
}
// 防呆:把路径限制在沙箱内,挡住 ../ 逃逸
clean := filepath.Clean(filepath.Join(sandboxRoot, name))
if !strings.HasPrefix(clean, filepath.Clean(sandboxRoot)) {
return "错误:只允许访问 workspace 目录内的文件", nil
}
data, err := os.ReadFile(clean)
if err != nil {
return fmt.Sprintf("读取失败:%s。请确认文件是否存在。", err), nil
}
// 输出控制:超过 2000 字节就截断
const maxLen = 2000
content := string(data)
if len(content) > maxLen {
content = content[:maxLen] + fmt.Sprintf("\n...(文件过长,共 %d 字节,已截断)", len(data))
}
return content, nil
}
注意这里每一个"错误"都是 return 可读信息, nil——模型能读懂并自我纠正,而不是让程序崩溃。
3.3 真实工具 2:HTTP GET(带输出截断)
import "net/http"
func httpGet(args map[string]any) (string, error) {
url, _ := args["url"].(string)
if url == "" {
return "错误:缺少 url 参数", nil
}
resp, err := http.Get(url)
if err != nil {
return fmt.Sprintf("请求失败:%s", err), nil
}
defer resp.Body.Close()
body, _ := io.ReadAll(io.LimitReader(resp.Body, 4000)) // 输出控制:最多读 4000 字节
return fmt.Sprintf("HTTP %d\n%s", resp.StatusCode, string(body)), nil
}
3.4 用 Schema 精确声明
var tools = []ToolSpec{
{
Definition: Tool{
Type: "function",
Function: FunctionDefinition{
Name: "read_file",
Description: "读取 workspace 目录下的文本文件内容。当需要查看某个文件时使用。",
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{
"path": map[string]any{
"type": "string",
"description": "相对于 workspace 目录的文件路径,如 notes.txt",
},
},
"required": []string{"path"},
},
},
},
Run: readFile,
},
{
Definition: Tool{
Type: "function",
Function: FunctionDefinition{
Name: "http_get",
Description: "对指定 URL 发起 HTTP GET 请求并返回响应内容。当需要获取网页或接口数据时使用。",
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{
"url": map[string]any{"type": "string", "description": "完整的 URL,需以 http:// 或 https:// 开头"},
},
"required": []string{"url"},
},
},
},
Run: httpGet,
},
}
3.5 循环里适配新的工具结构
主循环基本不变,只是从 tools 里查找和执行,并处理返回的 error:
// 构造给模型的工具声明列表
func toolDefinitions() []Tool {
defs := make([]Tool, len(tools))
for i, t := range tools {
defs[i] = t.Definition
}
return defs
}
// 按名字查找并执行工具
func dispatch(name string, args map[string]any) string {
for _, t := range tools {
if t.Definition.Function.Name == name {
result, err := t.Run(args)
if err != nil {
return fmt.Sprintf("[工具执行异常] %s", err) // 兜底也变成可读信息
}
return result
}
}
return fmt.Sprintf("错误:未知工具 %s", name)
}
完整代码见 code/03-tool-design/。跑起来,你可以让 Agent "读一下 notes.txt 里写了什么" 或 "帮我获取 https://example.com 的内容并总结",观察它如何选择工具、处理错误。
四、决策指南:拆分还是合并工具
| 情况 | 建议 |
|---|---|
| 几个工具总是被连续调用、逻辑紧密 | 考虑合并成一个,减少轮次 |
| 一个工具参数超过 5-6 个、功能杂糅 | 考虑拆分,职责单一 |
| 工具返回大量数据 | 在工具内做聚合/过滤/截断,别甩给模型 |
| 工具很多但每次只用一部分 | 按任务/场景动态暴露子集(见第 07 篇) |
| 有危险副作用 | 单独标注 + 加确认参数 + human-in-the-loop |
五、常见坑速查
| 坑 | 后果 | 正确做法 |
|---|---|---|
| 工具描述含糊 | 模型该调不调、乱传参 | 写清"做什么/何时用/输入格式"+示例 |
| 参数不加约束 | 模型传非法值 | 用 enum / min-max / required |
| 工具里 panic | Agent 整体崩溃 | 错误作为可读结果返回给模型 |
| 输出不设上限 | 撑爆上下文、又慢又贵 | 截断 + 结构化 + 过滤 |
| 工具堆太多 | 选择准确率下降、浪费 token | 合并同类 + 按需暴露 |
| 相对路径等易错参数 | 模型频繁出错 | 防呆设计:强制绝对路径/无歧义命名 |
六、小结与下一篇
- 工具设计质量 = Agent 能力上限,值得像设计 API 一样认真对待(ACI)。
- 六原则:描述即接口、Schema 精确约束、错误可操作、输出可控、防呆设计、只读优先。
- 工具不是越多越好,注意注意力稀释和 token 消耗。
- 错误处理的黄金法则:把错误变成模型能读懂的信息喂回去,而不是 panic。
现在你的 Agent 有了真实、健壮的工具。但随着对话变长、工具输出累积,那个只增不减的 messages 数组迟早会撑爆模型的上下文窗口——轻则变慢变贵,重则直接报错。
下一篇预告——《上下文工程:让 Agent 不会失忆也不会撑爆》:这是 2025 年最热的 Agent 工程话题。我们会讲透 Context Engineering 的四板斧(Write / Select / Compress / Isolate),并给 Agent 加上 token 预算和历史压缩,让它能扛住长对话。
参考资料
| 资料 | 来源 |
|---|---|
| Building Effective Agents(ACI、防呆设计、工具文档) | anthropic.com/engineering/building-effective-agents |
| Writing effective tools for agents(工具设计专题) | anthropic.com/engineering/writing-tools-for-agents |
| OpenAI Function Calling(Schema、参数约束) | developers.openai.com/api/docs/guides/function-calling |
| JSON Schema 官方文档 | json-schema.org |