翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
モデルにツールを使用してメッセージに対するレスポンスを完了させるには、メッセージと 1 つ以上のツールの定義をモデルに送信します。ツールの 1 つがレスポンスの生成に役立つとモデルが判断した場合、そのツールを使用してツールの結果をモデルに送り返すようリクエストを返します。モデルはその結果を使用して元のメッセージに対するレスポンスを生成します。
次の手順は、 Converse API でツールを使用する方法を示しています。サンプルコードについては、「Converse API ツールの使用例」を参照してください。
ステップ 1: メッセージとツールの定義を送信する
メッセージとツールの定義を送信するには、Converse または ConverseStream (ストリーミングレスポンス用) オペレーションを使用します。
注記
Meta には、Llama 3.1 (またはそれ以降) のモデルのツールを使用するプロンプトを作成するための具体的な推奨事項があります。詳細については、Meta ドキュメントの「JSON based tool calling
ツールの定義は、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
への呼び出しに含めることで、モデルとの会話を続けます。次に、モデルは、メッセージの toolResult
フィールドに提供された情報を使用して、元のメッセージ (WZPZ で最も人気のある曲は何ですか?) に答えるレスポンスを生成します。
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
}
]
}
},
"stopReason": "end_turn"