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"]
}

原则 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 的日志,会瞬间撑爆上下文窗口,又慢又贵。工具输出必须有节制:

原则 5:防呆设计(Poka-yoke)

把参数设计成"很难用错"的样子。 这是 Anthropic 特别强调的一条,源自丰田的防错思想。

他们的经典例子:一个改文件的工具,如果用相对路径,模型经常搞错工作目录导致改错文件;改成强制要求传绝对路径后,出错率大幅下降。

同理:

原则 6:只读优先,副作用显眼


二、工具不是越多越好

新手容易走另一个极端:给模型塞 30 个工具,觉得"能力越全越好"。

恰恰相反。工具太多会稀释模型的注意力,降低它选对工具的准确率,还白白消耗上下文(每个工具声明都占 token)。

两个应对策略:

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 有了真实、健壮的工具。但随着对话变长、工具输出累积,那个只增不减的 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