用 Converse 调用工具 API

要让模型使用工具完成对消息的响应，您需要将消息以及一个或多个工具的定义发送给模型。如果模型确定其中一个工具可以帮助生成响应，则它会返回一个请求，要求您使用该工具并将工具结果发送回模型。然后，模型使用结果生成对原始消息的响应。

以下步骤显示了如何在 Converse API 上使用工具。有关代码示例，请参阅 匡威API工具使用示例。

第 1 步：发送消息和工具定义

要发送消息和工具定义，请使用 C onverse 或 ConverseStream（用于流式响应）操作。

注意

Meta 为创建使用工具的提示提供了具体建议 Llama 3.1（或更高版本）型号。有关更多信息，请参阅中的JSON基于工具的调用 Meta 文档中）。

该工具的定义是您在 toolConfig (ToolConfiguration) 请求参数中传递给Converse操作的JSON架构。有关架构的信息，请参阅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_s ong 的工具。

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

有关您可以传递的其他参数的信息，请参阅与匡威进行对话。

第 2 步：从模型那里获取工具请求

当您使用消息和工具定义调用Converse操作时，模型将使用工具定义来确定是否需要该工具来回答消息。例如，如果您的聊天应用程序用户发送消息最受欢迎的歌曲WZPZ是什么？ ，模型将消息与 top_song 工具定义中的架构进行匹配，并确定该工具可以帮助生成响应。

当模型决定需要工具来生成响应时，模型会将stopReason响应字段设置为tool_use。响应还标识了模型希望您运行的工具 (top_songWZPZ) 以及它希望您使用该工具查询的广播电台 ()。有关所请求工具的信息位于模型在 output (ConverseOutput) 字段中返回的消息中。具体而言，是 toolUse (ToolUseBlock) 字段。在以后的调用中，您可以使用该toolUseId字段来识别工具请求。

以下示例显示了您传递中讨论的消息Converse时的响应第 1 步：发送消息和工具定义。

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "toolUse": {
                        "toolUseId": "tooluse_hbTgdi0CSLq_hM4P8csZJA",
                        "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。然后，模型会生成一个回复原始信息的响应（最受欢迎的歌曲WZPZ是什么？ )，其中包含您在消息toolResult字段中提供的信息。

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