FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

Agent 调错工具,先查你写的工具描述

Anthropic 把详细描述列为影响工具表现的首要因素,本文以一家物流公司的 API 为例逐步改写。

分享微博

要点速览

  • 模型只根据名称、描述和输入来选工具,所以描述是你最能掌控的部分。
  • 把相关端点合并成更少的工具,名称用 acme_orders 这样的形式,参数用 order_id 而不是 order。
  • 错误和响应同样是提示词:改写错误信息,让模型能自行纠正,并且只返回它真正需要的数据。
数据流示意图:工具定义(名称、描述、schema)插入模型的提示词,这一环节以橙色突出,因为调错工具通常从这里开始。模型为封装层生成 JSON 参数,封装层调用客户的 API,再把提示修正方法的错误信息和精简后的响应返回给模型。
模型既不读客户的代码,也不读其 Swagger。它只看到插入提示词的工具定义,也只读取封装层返回的内容。本图基于文中假设的 Acme 示例,综合自 Anthropic 的工具调用文档和 Hugging Face 的 Agents 课程。

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 时,先别急着换模型。打开描述,像新同事入职第一天那样读一遍。

这篇文章对你有帮助吗?

5 个信源
路线图上的下一篇 · 阶段 3: AI 应用越南语呼叫中心转写,模型反而是最简单的一环PhoWhisper 负责转写,WhisperX 区分说话人,真正的错误来自 8kHz 音频、抢话和拼接两者的代码。