Agent工具定义标准–OpenAPI架构设计、参数描述、LLM调用准确性优化

Dify的Agent是一个允许LLM自主选择和执行工具来完成任务的功能。代理稳定性几乎与工具定义的质量直接相关。在本文中，我们将对定义标准、测试方法和操作指南进行实用的解释，以使LLM能够准确地调用工具。

1.Agent中工具定义的作用

1.1 为什么工具定义决定了 Agent 的准确性

Agent的操作流程如下。

flowchart LR
    U[ユーザー入力] --> A[Agent LLM]
    A --> TD{ツール選択判断}
    TD -->|ツールA| TA[ツールA実行]
    TD -->|ツールB| TB[ツールB実行]
    TD -->|ツール不要| DR[直接回答]
    TA --> A
    TB --> A
    DR --> R[最終回答]
    A --> R

当LLM选择工具时，是指工具的名称、描述和参数定义。换句话说，这些定义直接作为LLM决策的基础。

1.2 常见问题

• 工具描述不明确，LLM 选择了错误的工具
• 由于参数定义不足，LLM 传递了错误的值
• 多个工具的描述相似，导致LLM混乱
• 由于未定义的故障后备而导致代理循环

2. 如何定义自定义工具

2.1 Dify 中的工具添加流程

1.点击Dify控制台顶部的工具菜单 2. 选择 自定义工具 > 创建自定义工具 3. 输入工具名称和 OpenAPI 架构 4. 配置身份验证设置（API 密钥、Bearer Token等） 5. 通过运行测试验证操作 6. 将工具链接到代理应用程序

2.2 OpenAPI schema 的基本结构

Dify 自定义工具在 OpenAPI 3.0 / Swagger 2.0 格式架构中定义。

openapi: "3.0.0"
info:
  title: "社内チケット管理API"
  version: "1.0.0"
  description: "社内ITサポートチケットの作成・検索・更新を行うAPI"

servers:
  - url: "https://api.internal.example.com/v1"

paths:
  /tickets:
    post:
      operationId: "createTicket"
      summary: "新しいサポートチケットを作成する"
      description: |
        社内ITサポートチケットを新規作成します。
        ユーザーがIT機器の故障、ソフトウェアの不具合、アカウントの問題を
        報告する場合に使用してください。
        一般的な質問への回答や、IT以外の問題には使用しないでください。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - category
                - description
              properties:
                title:
                  type: string
                  description: "チケットのタイトル。問題を簡潔に表す30文字以内の文字列。"
                  example: "VPN接続エラー"
                category:
                  type: string
                  enum: ["hardware", "software", "network", "account", "other"]
                  description: |
                    問題のカテゴリ。以下から選択:
                    - hardware: PC、モニター、キーボード等の物理的な機器の問題
                    - software: アプリケーションのインストール、動作不良、ライセンス
                    - network: WiFi、VPN、インターネット接続の問題
                    - account: パスワードリセット、アカウントロック、権限の問題
                    - other: 上記に該当しない問題
                description:
                  type: string
                  description: "問題の詳細説明。発生状況、エラーメッセージ、影響範囲を含む。"
                priority:
                  type: string
                  enum: ["critical", "high", "medium", "low"]
                  default: "medium"
                  description: |
                    優先度。以下の基準で選択:
                    - critical: 業務が完全に停止している（全社影響）
                    - high: 業務に重大な支障がある（部門影響）
                    - medium: 業務に一部支障がある（個人影響）
                    - low: 改善要望、将来的な対応でよいもの
      responses:
        "201":
          description: "チケット作成成功"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket_id:
                    type: string
                    description: "作成されたチケットのID"
                  status:
                    type: string
                    description: "チケットのステータス"
        "400":
          description: "リクエストパラメータが不正"
        "401":
          description: "認証エラー"

  /tickets/search:
    get:
      operationId: "searchTickets"
      summary: "サポートチケットを検索する"
      description: |
        既存のサポートチケットを検索します。
        ユーザーが過去のチケットの状況を確認したい場合や、
        類似の問題が報告されていないか調べる場合に使用してください。
        新しいチケットを作成する場合は createTicket を使用してください。
      parameters:
        - name: keyword
          in: query
          required: false
          schema:
            type: string
          description: "検索キーワード。チケットのタイトルと説明文を全文検索。"
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: ["open", "in_progress", "resolved", "closed"]
          description: "チケットのステータスでフィルタリング"
        - name: created_after
          in: query
          required: false
          schema:
            type: string
            format: date
          description: "指定日以降に作成されたチケットを検索。ISO 8601形式（例: 2026-01-15）"
      responses:
        "200":
          description: "検索結果"
          content:
            application/json:
              schema:
                type: object
                properties:
                  tickets:
                    type: array
                    items:
                      type: object
                      properties:
                        ticket_id:
                          type: string
                        title:
                          type: string
                        status:
                          type: string
                        created_at:
                          type: string
                  total_count:
                    type: integer

3. 如何撰写有效的描述

3.1 描述三要素

工具描述必须包括以下三个要素：

1. このツールが「何をするか」（What）
2. 「いつ使うべきか」（When）
3. 「いつ使うべきでないか」（When NOT）

3.2 比较好的和坏的描述

不好的例子1：太模糊

# NG
description: "情報を検索します"

好例子1：具体清晰的界限

# OK
description: |
  社内ナレッジベースから技術文書を検索します。
  ユーザーが製品の仕様、設定手順、トラブルシューティング方法を
  尋ねている場合に使用してください。
  料金、契約、人事に関する質問には使用しないでください。

糟糕的例子2：多种工具之间的界限不明确

# NG: ツールA
description: "データを取得します"

# NG: ツールB
description: "情報を返します"

好例子2：清晰的差异化

# OK: ツールA - チケット検索
description: |
  過去のサポートチケットをキーワードやステータスで検索します。
  ユーザーが「前に報告した問題のステータスを知りたい」
  「同じ問題が報告されていないか確認したい」場合に使用してください。

# OK: ツールB - ナレッジ検索
description: |
  社内技術ドキュメントから解決方法を検索します。
  ユーザーが「この問題をどう解決すればよいか」
  「設定手順を教えてほしい」場合に使用してください。

3.3 参数描述指南

4. 认证设置

4.1 Dify 支持的认证方式

4.2 身份验证配置最佳实践

# Dify カスタムツール認証設定
authentication:
  type: "api_key"
  api_key_header: "X-API-Key"
  # API Key は環境変数またはシークレットマネージャーから取得
  # ハードコーディングしない

• 在 Dify 身份验证设置屏幕上输入 API 密钥（不要直接将其写入架构中）
• 在生产环境中，提供定期轮换密钥的机制。
• 最小权限（如果只读就可以，则不要授予写入权限）

5. Agent指令设计

除了工具定义之外，Agent的系统提示（指令）也极大地影响了工具选择的准确性。

5.1 代理指令模板

あなたはITサポートアシスタントです。
社員からのIT関連の問い合わせに対応します。

## 対応可能な業務
- 技術的な問題のトラブルシューティング
- サポートチケットの作成と状況確認
- 社内技術ドキュメントの検索

## ツール使用のルール
1. まず searchKnowledge で解決方法を検索してください
2. 解決方法が見つかった場合は、ツールの結果に基づいて回答してください
3. 解決方法が見つからない場合は、createTicket でチケットを作成してください
4. ユーザーが過去のチケットについて尋ねた場合は searchTickets を使用してください

## ツール使用の制約
- チケット作成前に必ずユーザーに内容を確認してください
- 1回の会話で同じツールを3回以上呼び出さないでください
- ツールの実行に失敗した場合は、エラー内容をユーザーに伝えてください

## 回答の制約
- IT以外の質問（人事、経理等）は対応範囲外であることを伝えてください
- 不明な点がある場合は推測せず、ユーザーに確認してください

5.2 确定工具使用的优先级

当代理拥有多个工具时，在说明中指定使用顺序可以提高准确性。

## ツール使用の優先順位
1. searchKnowledge（最優先）: まず社内ナレッジを検索
2. searchTickets: ナレッジで解決しない場合、類似チケットを検索
3. createTicket（最後の手段）: 上記で解決しない場合のみ新規チケット作成

6.测试方法

6.1 工具定义的测试矩阵

6.2 测试执行流程

1.在Dify控制台的调试面板发送测试消息 2.查看工具调用日志：

• 选定的工具名称
• 传递的参数
• 工具响应

3. 通过与预期结果比较来发现问题 4.修改描述或参数定义
4. 重新测试

6.3 逐步测试方法

Phase 1: 単体テスト
├── 各ツールが正しく呼び出されるか（10ケース/ツール）
├── パラメータが正しく渡されるか
└── エラーレスポンスの処理

Phase 2: 統合テスト
├── 複数ツールの選択判断（20ケース）
├── ツール間の連携（検索→作成の流れ）
└── 会話のマルチターンでの一貫性

Phase 3: エッジケーステスト
├── 曖昧な入力への対応
├── 複数ツールが該当しうる入力
├── 大量の出力を返すツール
└── タイムアウト・エラーケース

7. 管理和扩展工具数量

7.1 刀具数量与精度的关系

7.2 代理嵌套模式

如果您有大量工具，请将代理分层。

flowchart TD
    U[ユーザー入力] --> RA[ルーティング Agent]
    RA -->|IT関連| ITA[IT Agent]
    RA -->|人事関連| HRA[HR Agent]
    RA -->|経理関連| FNA[Finance Agent]
    ITA --> T1[チケットAPI]
    ITA --> T2[ナレッジ検索]
    HRA --> T3[勤怠API]
    HRA --> T4[休暇API]
    FNA --> T5[経費API]
    FNA --> T6[請求API]

8. 常见问题及解决方法

9. 清单

在将工具定义投入生产之前，请检查以下内容：

模式质量

• operationId 是一个唯一且易于理解的名称吗？
• 摘要是否在一行中表示了该功能？
• 描述是否包括什么/何时/何时不？
• 参数类型、格式和约束是否准确？
• 所需标志设置正确吗？
• 是否涵盖了枚举的所有可能值？
• 它包含示例吗？

代理指令

• 是否明确说明了使用工具的规则和优先级？
• 是否定义了工具使用限制（次数限制等）？
• 问题的行为是否超出了定义的范围？

测试

• 您是否为每个工具执行了至少 10 个测试用例？
• 是否涵盖正常系统、异常系统和边缘情况？
• 多种工具之间的选择判断是否准确？
• 在错误情况下我们是否正确回退？

10. 总结

Agent工具定义的质量直接关系到Agent的可靠性。

构建稳定的Agent的关键是将工具定义设计为不仅是“API规范”，而且是“LLM的说明”。