6.2 自定义工具：OpenAPI接进工作台

6.2 自定义工具：OpenAPI 接进工作台

自定义工具用一份 OpenAPI（Swagger）规范描述你的接口：地址、方法、参数、鉴权。Dify 解析这份规范后，接口就以工具的形式出现在 Agent 的工具清单里，模型按规范里的名称与描述决定何时调用、传什么参数。工具定义的质量直接决定调用准确率——模型眼里，你的接口长什么样，全由这份规范说了算。

6.1 讲完循环，本节给循环提供弹药：把公司内部的查订单、查物流接口接上工作台。这节的核心不是语法（语法半小时就会），是站在模型的视角写文档这门手艺。

一份能用的工具定义长什么样

查订单接口的 OpenAPI 规范，逐行带注释：

openapi: 3.0.0
info:
  title: 售后查询工具          # 工具集名称
  version: "1.0"
servers:
  - url: https://api.shop.example.com   # 内部网关地址
paths:
  /orders/query:                        # 查订单接口
    post:
      operationId: query_order          # 模型看到的"工具名"，
        # 命名动词加名词，模型靠它做第一层匹配
      summary: 按用户描述查询订单，返回订单号、商品、金额与状态
        # 一句话描述：写清"什么时候该用它"与"返回什么"，
        # 模型选工具的主要依据就是这句话
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                keyword:
                  type: string
                  description: 用户的原话或商品关键词，如"上周买的空气炸锅"
                  # 参数描述写"从哪来"，模型才知道把 user 的原话放这里
              required: [keyword]
      responses:
        "200":
          description: 订单列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id: { type: string }
                  status: { type: string }
                  amount: { type: number }
​

在控制台"工具-自定义-创建工具"粘贴这份规范，配好鉴权（API Key 放在鉴权配置里，不进规范文本——5.2 的密钥不入画布原则在这里同样生效），工具就上架了。上架后先在工具页做手动试调：填参数、看真实返回。这一步等价于 4.3 的命中测试——别等 Agent 上线才发现接口返回的是 HTML 登录页。

工具描述的三条军规

模型每轮决策的全部依据就是工具名、summary 与参数描述。写法上我有三条军规，每条都来自真实翻车：

军规一，summary 写"何时用"不写"是什么"。"查订单接口"是写给程序员看的；"当用户询问自己的订单、包裹或购买记录时使用，返回订单号与状态"是写给模型看的。前者让 Agent 在用户问"我的钱到账没"时也去调它。

军规二，参数描述写"数据从哪来"。keyword 的描述如果只写"关键词"，模型会传"空气炸锅"；写"用户的原话或商品关键词"，模型才知道整句原话更利于后端模糊匹配。参数描述是模型与你后端之间的交接单。

**军规三，两个工具的边界必须互斥。**查订单与查物流的描述如果都含"查询"，Agent 就会在边界问题上掷硬币。改法：查物流的 summary 明确写"已知订单号时查询物流轨迹；没有订单号时先用查订单工具"——一句话同时划清边界与顺序，误调率肉眼可见地降。

工具返回值：给模型看的报告单

定义好了入口，出口同样重要——返回 JSON 是模型的报告单，字段名要自解释，信息要一步到位。反例：后端原始返回用 d 表示状态码、t 表示时间戳，模型只能猜。正例：语义化字段名，附人类可读的状态文本：

{
  "order_id": "SO-1024",
  "status_text": "已发货",
  "carrier": "顺丰速运",
  "latest_trace": "08-25 14:20 杭州转运中心 已发出",
  "eta_text": "预计 08-27 送达"
}
​

如果后端接口改不动（遗留系统），在网关层加一个轻量适配层做字段翻译，成本一小时，换来的是 Agent 准确率的整档提升。这层适配在团队里常被叫"工具防腐层"——隔离后端的混乱，只给模型看干净的报告。

挂到 Agent 上并首跑

工具上架后，回小艺的编排面板：功能配置区"工具"里勾选两个自定义工具（Agent 授权可以是自动或需确认，生产环境起步建议"自动"只给只读工具，写操作走"需确认"——6.3 展开）。然后是激动人心的首跑：

首跑记录（调试面板）
输入：上周买的空气炸锅怎么还没到
轮次一：调用 query_order（keyword=原话）→ SO-1024 已发货
轮次二：调用 query_logistics（order_id=SO-1024）→ 在途轨迹
回答：您的订单已由顺丰承运，最新到达杭州转运中心，预计后天送达。
耗时 11 秒，约 3 次模型调用。自主决策，全程无误。
​

对照 6.1 的循环图逐轮核对：决策点一（信息不足调了）、决策点二（描述互斥所以选对）、决策点三（两次后收口）。首跑成功的功劳不在模型，在这份定义——这就是"站在模型的视角写文档"的回报。

⚠️ 常见坑一：规范里写了五个接口全挂上，Agent 开始乱选。工具不是越多越好，每个额外工具都在稀释决策注意力——按场景分工具集，一个 Agent 挂三到五个为宜。常见坑二：接口超时没设，后端偶发卡顿时 Agent 干等。自定义工具走平台统一的超时设置，慢接口先治理再上架。常见坑三：把写操作（退款、改址）当工具直接挂——这是事故级配置，写操作必须走需确认或干脆留在工作流里由条件分支把关。

本节要点回顾

• 定义即文档：OpenAPI 规范是模型眼中的接口全貌，operationId、summary、参数描述三处决定调用准确率；
• 三条军规：summary 写何时用、参数描述写数据从哪来、多工具边界互斥；
• 返回值自解释：语义化字段名加可读文本，改不动就加防腐层；
• 上架先手调：手动试调等于工具版的命中测试，别让 Agent 替你发现接口是坏的；
• 工具数量克制：三到五个为宜，多余的工具是决策噪声；
• 写操作隔离：只读工具才配自动授权，写操作走确认或留在工作流。

工具有了，循环也跑通了。但自主性是一把双刃剑——下一节装防护栏，确保它聪明但永不失控。