使用 Converse API 调用工具

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

以下步骤展示了如何通过 Converse API 使用工具。有关代码示例，请参阅 Converse API 工具使用示例。

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

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

工具的定义是您通过 toolConfig（ToolConfiguration）请求参数传递给 Converse 操作的 JSON 架构。有关架构的更多信息，请参阅 JSON Schema。以下是一个工具的示例架构，该工具可以获取电台播放的最受欢迎的歌曲。

{
    "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（Message）请求参数传递用户消息。

[
    {
        "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 字段来识别工具请求。

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

{
    "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 的调用中。然后，模型会生成一个响应来回答原始消息中的问题（WZPZ 上最受欢迎的歌曲是什么？），其中包含您在消息的 toolResult 字段中提供的信息。

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