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

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

技能指南 · 指南

百行脚本把客户的 OpenAPI 文件变成 Agent 工具草稿

脚本解析 $ref,同时输出 Claude 与 OpenAI 格式;挑端点、写描述仍归前线部署工程师(FDE)。

分享微博

要点速览

  • operationId 是工具名的天然候选,但规范中 operationId 缺失或重复时,脚本仍须自行命名。
  • 描述对工具效果影响最大,因此脚本同时读取 summary 和 description,并标出仍缺描述的工具。
  • 自动生成只是草稿:交给 Agent 之前,要筛到少数几个工具,并合并相关操作。
updateOrder 操作的前后对比图。左侧是 OpenAPI 规范,共四行:updateOrder、X-Api-Key header、$ref OrderPatch 和两句描述。右侧是给 Claude 的工具:crm_updateOrder,header 已移除,OrderPatch 已展开;描述行仍只有两句,以橙色高亮,并注明 Anthropic 建议写三到四句。
脚本负责给工具命名、去掉鉴权 header 并解析 $ref。工具描述仍只有两句,达不到 Anthropic 的建议,需要工程师改写。来源:文中 PATCH /orders/{id} 示例;Anthropic Engineering 指南。

到客户现场的第一天,拿到的往往是一个 openapi.json 文件链接,里面有几百个端点,外加一句“让 Agent 能用上这套系统”。手写每个工具定义要花一周,还容易出错。一个百行左右的 Python 脚本,一条命令就能生成草稿。

但草稿不是成品。Anthropic Engineering 的一篇文章提醒,常见错误是把现有 API 端点原样包装成工具。因此本文的脚本只承担重复劳动:展开 $ref、汇总参数、给工具命名。省下的时间留给挑选端点和撰写描述。

**要做什么:**一个脚本 gen_tools.py。它读取 JSON 格式的 OpenAPI 3.x 规范,输出两份工具列表:一份是 Claude 格式(name、description、input_schema),一份是 OpenAI 函数调用格式(type、name、description、parameters)。**需要准备:**Python 3 和一份规范文件。YAML 格式的规范先转成 JSON。脚本只用标准库。

第 1–2 步:读取规范,去掉所有 $ref

按 OpenAPI 3.1.0 规范,$ref 是指向被引用值的 URI。LLM 无法沿着这个指针去查找,发给模型的 schema 必须“拍平”,所以第一步是解析引用。

import json, re, sys

HTTP_METHODS = {"get", "post", "put", "patch", "delete"}

def load_spec(path):
    with open(path, encoding="utf-8") as f:
        return json.load(f)

def resolve(node, spec, seen=()):
    # 简化版:只处理 "#/components/..." 形式的内部 $ref
    if isinstance(node, dict):
        ref = node.get("$ref")
        if isinstance(ref, str) and ref.startswith("#/"):
            if ref in seen:
                return {"description": f"(递归 schema,位于 {ref})"}
            target = spec
            for part in ref[2:].split("/"):
                target = target[part.replace("~1", "/").replace("~0", "~")]
            return resolve(target, spec, seen + (ref,))
        return {k: resolve(v, spec, seen) for k, v in node.items()}
    if isinstance(node, list):
        return [resolve(x, spec, seen) for x in node]
    return node

**检查:**解析后打印一个请求体较复杂的操作。如果还残留 "$ref" 字符串,那就是指向其他文件的相对引用。规范允许这类引用,但这个精简版不处理。

seen 变量用来防止 schema 自引用时陷入死循环,比如 Category 的 children 列表元素也是 Category。

第 3 步:把多处参数合并成一个 schema

OpenAPI 把参数放在四个位置:query、header、path 和 cookie。上传的数据则单独放在 requestBody 里。Claude 只有一个 input_schema,即描述工具所需参数的单个 JSON Schema,所以脚本要把这些全部汇总到一个对象中。

SKIP_IN = {"header", "cookie"}  # 鉴权由你的代码附加,不要让模型来填

def build_input_schema(op, path_item):
    props, required = {}, []
    params = path_item.get("parameters", []) + op.get("parameters", [])
    for p in params:
        if p.get("in") in SKIP_IN:
            continue
        schema = dict(p.get("schema", {}))
        if p.get("description"):
            schema["description"] = p["description"]
        props[p["name"]] = schema
        if p.get("required"):
            required.append(p["name"])
    body = op.get("requestBody", {})
    content = body.get("content", {}).get("application/json", {})
    if "schema" in content:
        props["body"] = content["schema"]
        if body.get("required"):
            required.append("body")
    return {"type": "object", "properties": props, "required": required}

这里有两个决定,面对真实系统时值得重新审视。跳过 header 和 cookie 是有意为之:鉴权 token 应由你的代码附加,而不是让模型填写。

第二个决定是如何处理重名。设想端点 PATCH /orders/{id},路径里有 id,请求体里也有一个 id 字段:把请求体包在 body 键下,两者就不会互相覆盖。Anthropic Engineering 建议参数名要清晰、无歧义,如果规范里用的是 q、p1 这类名字,就在这一步改掉。

第 4 步:工具名必须合法,描述不能为空

Claude 要求 name 匹配正则 ^[a-zA-Z0-9_-]{1,128}$。按 OpenAPI 3.1.0 规范,operationId 在整个 API 中必须唯一,因此是工具名的天然候选。不过 Redocly 指出,各类工具依赖 operationId 识别操作,而现实中的规范常常漏写或重复这个字段,所以脚本需要兜底方案。

NAME_RE = re.compile(r"^[a-zA-Z0-9_-]{1,128}$")

def tool_name(op, method, path, used, prefix):
    raw = op.get("operationId") or f"{method}_{path}"
    name = (prefix + re.sub(r"[^a-zA-Z0-9_-]+", "_", raw).strip("_"))[:128]
    base, i = name, 2
    while name in used:
        suffix = f"_{i}"
        name = base[:128 - len(suffix)] + suffix
        i += 1
    assert NAME_RE.match(name), name
    used.add(name)
    return name

def tool_description(op, method, path):
    text = " ".join(s.strip() for s in (op.get("summary"), op.get("description")) if s)
    return text or f"调用 {method.upper()} {path}。NEEDS DESCRIPTION."

prefix 遵循 Anthropic 的建议:按服务给工具加前缀,例如 crm_ 或 billing_,这样 Agent 同时连接多个系统时,模型能分清各个工具。关于描述,Anthropic 文档称其是影响工具效果最重要的因素,没有之一,并建议每个工具至少写 3–4 句。

客户的规范很少能达到这个水平。埋下 NEEDS DESCRIPTION 字符串,是为了方便 grep,避免误把描述为空的工具发布到生产环境。

第 5 步:一份数据,两种输出格式

OpenAI 函数调用使用 type、name、description、parameters 和 strict。上面准备好的同一个 schema 可以直接输出成两种格式,无需重新计算。

def main(spec_path, prefix="", allow=None):
    spec = load_spec(spec_path)
    used, claude, openai, strict_candidates = set(), [], [], []
    for path, item in spec.get("paths", {}).items():
        item = resolve(item, spec)
        for method, op in item.items():
            if method not in HTTP_METHODS:
                continue
            if allow and op.get("operationId") not in allow:
                continue
            name = tool_name(op, method, path, used, prefix)
            desc = tool_description(op, method, path)
            schema = build_input_schema(op, item)
            claude.append({"name": name, "description": desc, "input_schema": schema})
            openai.append({"type": "function", "name": name,
                           "description": desc, "parameters": schema})
            # 部分检查:只看最外层,不检查请求体内嵌套的 schema
            if set(schema["required"]) == set(schema["properties"]):
                strict_candidates.append(name)
    json.dump({"claude": claude, "openai": openai}, sys.stdout,
              ensure_ascii=False, indent=2)
    print("strict 候选工具,需进一步检查:", strict_candidates, file=sys.stderr)

if __name__ == "__main__":
    allow = set(sys.argv[3].split(",")) if len(sys.argv) > 3 else None
    main(sys.argv[1], sys.argv[2] if len(sys.argv) > 2 else "", allow)
python3 gen_tools.py openapi.json crm_ listOrders,getOrder,updateOrder > tools.json

**检查:**统计 tools.json 中的工具数、被标记为缺少描述的数量,以及打印到 stderr 的 strict 候选列表。下一步看一个具体工具长什么样。

第 6 步:跟踪一个操作从规范到 JSON 的全过程

拿一份假设的规范来试。端点 PATCH /orders/{id} 的 operationId 是 updateOrder,有一个路径参数,请求体指向 OrderPatch schema:

"/orders/{id}": {
  "patch": {
    "operationId": "updateOrder",
    "summary": "Update an order.",
    "description": "Changes the status or adds an internal note.",
    "parameters": [
      {"name": "id", "in": "path", "required": true,
       "description": "Order ID", "schema": {"type": "string"}},
      {"name": "X-Api-Key", "in": "header", "required": true,
       "schema": {"type": "string"}}
    ],
    "requestBody": {"required": true, "content": {"application/json": {
      "schema": {"$ref": "#/components/schemas/OrderPatch"}}}}
  }
}

假设在 components/schemas 中,OrderPatch 是一个对象,有两个可选字段:status(字符串,枚举值 pending、shipped、refunded)和 note(字符串)。用前缀 crm_ 运行脚本,claude 数组中对应的元素是:

{
  "name": "crm_updateOrder",
  "description": "Update an order. Changes the status or adds an internal note.",
  "input_schema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Order ID"},
      "body": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "enum": ["pending", "shipped", "refunded"]},
          "note": {"type": "string"}
        }
      }
    },
    "required": ["id", "body"]
  }
}

openai 数组中的元素有相同的 name、description 和 schema,只是外层结构不同:多了 "type": "function",schema 放在 parameters 键下,而不是 input_schema。

从这份输出可以核对四点。$ref 已经消失,OrderPatch 被直接复制进 body。X-Api-Key header 没有出现,符合预期。id 参数的描述已移入它的 schema。

第四点是,工具描述只有两句,达不到 Anthropic 建议的 3–4 句。好的改写应当说明何时调用这个工具、每个 status 值会带来什么结果,以及这个工具做不到什么。

为什么脚本不自动开启 strict

上面这个工具进入了 strict 候选列表,因为在最外层,required 与 properties 完全一致。但在 body 内部,status 和 note 都不在 required 中,而 OpenAI 的 strict 模式要求 properties 中的每个字段都标为 required。代码里的比较只看最外层,发现不了这个问题。

所以候选列表只是起点。

note 这类可选字段要先手动转换,然后再手动加上 "strict": true。

Claude 更简单:在工具定义上设置 strict: true 即可开启 schema 校验。如果想用规范中的 example 字段生成 input_examples,发送前要逐个对照 input_schema 校验,因为无效示例会让 API 返回 400 错误。

最大的坑是生成太多工具

在一份上百个端点的规范上不加白名单直接运行,就会得到上百个工具。OpenAI 建议每轮开始时函数数量保持在 20 个以内。这是软性建议,但有其道理:Anthropic 同样认为,工具更少、每个工具承担更多,模型在选择时就更不容易犹豫。

因此 allow 参数不是附属功能,而是核心工作。设想客户需要一个处理退款请求的 Agent:查询订单、查看详情、更新订单这三个操作就够了;如果流程总是按固定顺序走,再加一个合并后的工具。

还有几个常见错误:有人让鉴权 header 混进了 schema;有人发布了描述为空的工具;有人想当然地认为 operationId 总是唯一,从不运行检查。

在客户现场,写代码之前先问清楚:规范由谁维护,它和实际运行的 API 是否一致。用 Redocly 这类 linter 检查重复的 operationId,很快就能知道这份规范有多可信。

如果想把这项技能写进简历,别写“将 OpenAPI 与 LLM 集成”。要写你把一份数百个端点的规范精简成一小套工具,描述由你亲自撰写,并配有 schema 测试集;再把脚本放到 GitHub 上,针对一份公开规范运行。

在 FDE 面试中,多谈你砍掉了哪些工具、为什么砍,而不是炫耀生成了多少工具。

运行脚本只需一条命令。客户真正付费购买的,是之后那个下午:决定保留哪些工具。

这篇文章对你有帮助吗?

5 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力用 Greenhouse 自建 FDE 薪资表,别忘了单位是分约 40 行 Python 抓取薪酬透明法强制公开的薪资范围,并写入 CSV。