Agent 调错工具,先查你写的工具描述
Anthropic 把详细描述列为影响工具表现的首要因素,本文以一家物流公司的 API 为例逐步改写。
要点速览
- 模型只根据名称、描述和输入来选工具,所以描述是你最能掌控的部分。
- 把相关端点合并成更少的工具,名称用 acme_orders 这样的形式,参数用 order_id 而不是 order。
- 错误和响应同样是提示词:改写错误信息,让模型能自行纠正,并且只返回它真正需要的数据。
Anthropic 的工具调用文档指出,详细的描述是决定工具表现好坏的首要因素,而且远超其他因素。所以在换模型、换框架之前,先回头看看自己写的那几句话。
原因很简单。按照 Hugging Face Agents 课程的说法,工具描述会插入系统提示词,模型只知道写在那里的内容。Paragon 描述的也是同一机制:模型根据每个工具附带的名称、描述和输入来选择工具。
客户有一个内部 API,你需要把它封装起来供 Agent 使用。本指南用一个假设的例子逐步演示,每一步之后都有一项检查。
要做什么,需要准备什么?
假设客户是一家名为 Acme 的物流公司。它有三个端点:按 ID 查询订单、按电话号码查找订单、取消订单。目标是让客服 Agent 在用户用自然语言提问时,以正确的参数调用正确的端点。
先记住函数调用的工作方式。Prompting Guide 把它描述为把自然语言转换成有效 API 调用的方法,但模型只以 JSON 形式生成参数,真正调用 API 是你的代码的事。你需要熟悉 JSON Schema,手头有客户的 API 文档,并在模型和 API 之间放一层小小的封装。
第 1 步:看清初稿为什么失败
直接照搬端点名称时,常会写出这样的定义:
{
"name": "get",
"description": "获取订单",
"input_schema": {
"type": "object",
"properties": { "order": { "type": "string" } },
"required": ["order"]
}
}
名称“get”没说明获取的是什么,也没说明来自哪个系统。参数“order”可能是订单 ID,可能是整个订单对象,也可能是序号。只有几个字的描述,完全没说何时该用这个工具。
Anthropic 工程博客的一篇文章建议使用无歧义的参数名,比如用 user_id 而不是 user。这里同理,order_id 比 order 清楚得多。
**检查:**把定义念给一位从没见过 Acme API 的同事听。如果对方问“order 是什么?”,模型也会同样误解。
第 2 步:合并端点,名称加服务前缀
很多人的第一反应是每个端点对应一个工具。Anthropic 的文档建议反过来:把相关操作合并成更少的工具,用一个 action 参数区分,因为工具更少、能力更强,模型选择时需要权衡的就更少。
同一份文档还建议在名称前加服务前缀,例如 github_list_prs 或 slack_send_message,这样工具库变大后选择依然清晰。
用到 Acme 上,三个端点合并成一个名为 acme_orders 的工具,其 action 取三个值之一:get、search 或 cancel。如果 Agent 以后增加了 CRM 系统的工具,acme_ 前缀能让人一眼分清。
**检查:**列出 Agent 目前拥有的所有工具。如果要仔细读两个工具才能看出区别,就合并或重命名。
第 3 步:像给新同事交代工作那样写描述
Anthropic 建议,写描述就像向团队新人解释这个工具,把内部人员习以为常的背景都讲清楚。其文档列出了应包含的内容:工具做什么,何时用、何时不用,每个参数的含义,以及注意事项。
每个工具至少写 3-4 句,工具复杂就写更多。注意每个 JSON 字符串必须在一行内;描述中需要换行时,使用转义符 \n。
{
"name": "acme_orders",
"description": "在 Acme 系统中查询、查找或取消配送订单。用户提供了订单 ID 时,使用 action='get';只有收件人电话号码时,使用 action='search'。仅当用户明确表示要取消时才使用 action='cancel',且只适用于尚未出库的订单。\n\n不要用此工具回答运费或赔偿申请相关的问题。订单 ID 格式为 ORD- 加 8 位数字。",
"input_schema": {
"type": "object",
"properties": {
"action": { "type": "string", "enum": ["get", "search", "cancel"] },
"order_id": { "type": "string", "description": "订单 ID,格式为 ORD-12345678。get 和 cancel 必填。" },
"recipient_phone": { "type": "string", "description": "收件人电话号码,仅限数字。用于 search。" }
},
"required": ["action"]
}
}
订单 ID 格式、“尚未出库”规则和排除赔偿申请,都是为本例虚构的。在真实客户那里,这类规则要靠你从人那里问出来,它们通常存在于运营团队的脑子里,而不在 API 文档里。
**检查:**描述里有没有一句以“不要用……”开头的话?
第 4 步:为难以填写格式的输入加示例
对于输入复杂或对格式敏感的工具,Anthropic 的 API 提供可选字段 input_examples。每个示例都必须符合 input_schema,不符合会返回 400 错误。示例还会额外消耗提示词 token,所以只在某种格式确实经常填错时才用。下面的片段做了简化:
"input_examples": [
{ "action": "get", "order_id": "ORD-20481234" },
{ "action": "search", "recipient_phone": "0901234567" }
]
**检查:**发送请求。如果收到 400 错误,很可能是某个示例与 schema 不符,比如字段名写错,或 action 取值不在 enum 中。
第 5 步:响应和错误同样是提示词
API 返回的一切都会回到模型的上下文中。Anthropic 工程博客建议工具只返回高价值信息,并建议对大体量数据做分页、过滤和截断。同一篇文章还指出,可以改写错误信息,明确说明需要修正什么,帮助模型在下一次调用时调整。
下面的封装做了简化。它区分了两种不同的失败:ID 格式错误(在封装层拦截,不调用 API),以及 ID 格式正确但不存在(API 返回 404)。
import re
# 简化版:模型与客户 API 之间的封装层
ORDER_ID_PATTERN = re.compile(r"^ORD-\d{8}$")
def run_acme_orders(args):
if args["action"] in ("get", "cancel"):
order_id = args.get("order_id", "")
if not ORDER_ID_PATTERN.match(order_id):
return ("order_id 格式错误:必须是 ORD- 加 8 位数字,"
"例如 ORD-20481234。请再次向用户询问订单 ID。")
resp = call_customer_api(args) # 你自己的 HTTP 函数
if resp.status == 404:
return ("ID 格式正确,但没有找到对应订单。\n\n"
"如果用户有收件人电话号码,"
"请改用 action='search' 再次调用。")
order = resp.json()
return {"order_id": order["id"], "status": order["status"],
"eta": order["eta"]} # 丢弃模型用不到的内部字段
与一句光秃秃的“404 Not Found”相比,这里的每条信息都把模型引向不同的路径:ID 格式错误就重新询问,订单不存在就改用电话号码查找。把响应精简到三个字段,模型就不必在几十个内部字段里翻找。
**检查:**做两次测试调用,一次用格式错误的 ID,一次用格式正确但不存在的 ID。模型在两种情况下的下一次调用应该不同,而不是拿同一个错误 ID 反复重试。
第 6 步:别凭感觉,跑评测
Anthropic 指出,即使是对描述的细微改进,也可能大幅提升效果。这一点是双向的:改一句话可能让效果变好,也可能弄坏一个原本正常的用例。
实用的做法是从客户的客服记录中整理出约 20 个问题,事先为每个问题记下正确的工具、action 和参数。每次修改描述后,重跑整套问题,统计答对的数量。
要避开的坑
一个常见错误是用 OpenAPI 自动生成工具后原样使用。这恰好会导致 Anthropic 文档警告的情况:几十个工具,每个端点一个,描述照搬开发者注释,短到模型无法区分。另一个错误是参数名仍叫 id、user 或 data,且不说明格式。
也不要把 API 的原始 JSON 连同错误原样返回,然后奇怪模型为什么总在重复同一个错误调用。
这项技能在客户现场是什么样子?
在现场,难点很少是 JSON 语法,而是坐下来和运营团队一起,问出“订单出库后还能取消吗?”这类问题的答案,因为这些答案正是描述里“何时不用”那句话的内容。
如果你的目标是前线部署工程师(FDE)岗位,留意那些提到工具调用、Agent 集成或直接对接客户 API 的岗位描述。
简历上别只写“将 LLM 与内部 API 集成”。要写清你把多少个端点合并成了多少个工具,以及每轮修改描述后,评测集上的准确率如何变化。这样一组前后对比的数字,能让招聘方看到你能做客户愿意付钱的工作。
下次 Agent 调错 API 时,先别急着换模型。打开描述,像新同事入职第一天那样读一遍。
这篇文章对你有帮助吗?
感谢你的反馈!