Claude Academy
載入中

工具結構定義

第 24 課7 分鐘

在撰寫完您的工具函式後，下一步是建立一個 JSON 結構定義（schema），告訴 Claude 您的函式需要哪些參數以及如何使用它。這個結構定義就像是 Claude 閱讀的文件，用來理解何時以及如何呼叫您的工具。

理解 JSON Schema

JSON Schema 並非專屬於 AI 或工具呼叫——它是一個廣泛使用的資料驗證規範，已經存在多年。AI 社群採用它是因為它是描述函式參數和驗證資料的便利方式。

完整的工具規格有三個主要部分：

  • name - 函式名稱（例如「get_weather」）
  • description - 工具的功能以及何時使用它
  • input_schema - 描述參數的實際 JSON 結構定義

撰寫有效的描述

description 欄位對於幫助 Claude 理解您的工具至關重要。請遵循以下最佳實踐：

  • 說明工具的功能、何時使用它，以及它會回傳什麼
  • 目標是 3-4 句話
  • 同時為每個參數提供詳細的描述

input_schema 部分使用標準 JSON Schema 格式描述您函式的參數，包括類型資訊以及每個參數的詳細描述。

簡單的方法：讓 Claude 撰寫您的結構定義

您可以使用 Claude 本身來生成 JSON 結構定義，而不必從頭開始撰寫。以下是流程：

  1. 複製您的工具函式
  2. 前往 Claude，請它為工具呼叫撰寫一個 JSON 結構定義
  3. 將 Anthropic 關於工具使用的文件作為上下文提供
  4. 讓 Claude 依照最佳實踐生成一個格式正確的結構定義

提示應該類似於：「為這個函式撰寫一個有效的 JSON 結構定義規格，用於工具呼叫的目的。請遵循附件文件中列出的最佳實踐。」

在程式碼中實作結構定義

一旦 Claude 生成您的結構定義，將它複製到您的程式碼檔案中。使用一致的命名模式，例如 function_name_schema，以保持條理清晰：

python
get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "A string specifying the format of the returned datetime. Uses Python's strftime format codes.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

新增類型安全性

為了更好的類型檢查，請從 Anthropic 函式庫匯入並使用 ToolParam 類型：

python
from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    # 您的結構描述字典放在這裡
})

這對於功能性而言並非絕對必要，但它可以防止您稍後在程式碼中使用該結構定義時發生類型錯誤。

一個撰寫良好的工具函式與一個詳細的 JSON 結構定義相結合，為 Claude 提供了在對話中理解並正確使用您的工具所需的一切。