使用 呼叫工具 Converse API

若要讓模型使用工具來完成訊息的回應，您可以將訊息和一或多個工具的定義傳送到模型。如果模型判斷其中一個工具可協助產生回應，則會傳回請求，讓您使用該工具並將工具結果傳回模型。模型接著會使用結果來產生對原始訊息的回應。

下列步驟說明如何搭配 使用工具 Converse API。 如需範例程式碼，請參閱 Converse API 工具使用範例。

步驟 1：傳送訊息和工具定義

若要傳送訊息和工具定義，您可以使用 Converse 或 ConverseStream（用於串流回應） 操作。

注意

Meta 有特定的建議，可用來建立使用工具搭配 的提示 Llama 3.1 （或更新版本） 模型。如需詳細資訊，請參閱 中的 JSON 型工具呼叫 Meta 文件中)。

工具的定義是您在 toolConfig(ToolConfiguration) JSON 請求參數中傳遞至 Converse操作的結構描述。如需結構描述的資訊，請參閱JSON結構描述。以下是工具的範例結構描述，該工具會取得在廣播台上播放的最熱門歌曲。

{
    "tools": [
        {
            "toolSpec": {
                "name": "top_song",
                "description": "Get the most popular song played on a radio station.",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "sign": {
                                "type": "string",
                                "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
                            }
                        },
                        "required": [
                            "sign"
                        ]
                    }
                }
            }
        }
    ]
}

在相同的請求中，您也會在 messages(訊息） 請求參數中傳遞使用者訊息。

[
    {
        "role": "user",
        "content": [
            {
                "text": "What is the most popular song on WZPZ?"
            }
        ]
    }
]

如果您使用的是 Anthropic Claude 3 模型，您可以在toolConfig請求參數中指定 toolChoice(ToolChoice) 欄位，強制使用工具。強制使用工具在開發期間測試您的工具非常有用。下列範例示範如何強制使用名為 top_song 的工具。

{"tool" : {"name" : "top_song"}}

如需您可以傳遞的其他參數的相關資訊，請參閱 與 進行對話 Converse API 操作。

步驟 2：從模型取得工具請求

當您使用訊息和工具定義叫用 Converse操作時，模型會使用工具定義來判斷是否需要工具來回應訊息。例如，如果您的聊天應用程式使用者傳送訊息 上最熱門的歌曲是什麼WZPZ？，則模型會將訊息與 top_song 工具定義中的結構描述相符，並判斷工具可協助產生回應。

當模型決定需要工具來產生回應時，模型會將stopReason回應欄位設定為 tool_use。回應也會識別模型希望您執行的工具 (top_song)，以及希望您使用工具查詢的廣播站 (WZPZ)。所請求工具的相關資訊位於模型在 output(ConverseOutput) 欄位中傳回的訊息中。特別是 toolUse(ToolUseBlock) 欄位。您可以在稍後的呼叫中使用 toolUseId 欄位來識別工具請求。

下列範例顯示當您傳遞 中討論的訊息Converse時，來自 的回應步驟 1：傳送訊息和工具定義。

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "toolUse": {
                        "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                        "name": "top_song",
                        "input": {
                            "sign": "WZPZ"
                        }
                    }
                }
            ]
        }
    },
    "stopReason": "tool_use"
}

步驟 3：為模型提出工具請求

從模型回應中的 toolUse 欄位，使用 name 欄位來識別工具的名稱。然後呼叫您實作工具，並從 input 欄位傳遞輸入參數。

接著，建構包含 toolResult(ToolResultBlock) 內容區塊的使用者訊息。在內容區塊中，包含工具的回應，以及您在上一個步驟中取得的工具請求 ID。

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "json": {
                            "song": "Elemental Hotel",
                            "artist": "8 Storey Hike"
                        }
                    }
                ]
            }
        }
    ]
}

如果工具中發生錯誤，例如對非現有廣播站的請求，您可以將錯誤資訊傳送至 toolResult 欄位中的模型。若要指出錯誤，請在 status error欄位中指定 。下列範例錯誤適用於工具找不到廣播站的情況。

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "text": "Station WZPA not found."
                    }
                ],
                "status": "error"
            }
        }
    ]
}

步驟 4：取得模型回應

透過包含您在對 的呼叫中上一個步驟中建立的使用者訊息，繼續與模型的對話Converse。模型接著會產生回應，以您在訊息toolResult欄位中提供的資訊來回答原始訊息 ( 上最熱門的歌曲是什麼WZPZ？)。

{
     "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
                }
            ]
        }
    },
    "stopReason": "end_turn"