# Amazon Nova でのツールの使用 (関数呼び出し)
**注記**
このドキュメントは Amazon Nova バージョン 1 を対象としています。Amazon Nova 2 でツールを使用する方法については、「[ツールの使用 (関数呼び出し)](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-tools.html)」(Using tools (function calling)) を参照してください。
ツールは、API コールやコード関数などの外部機能を Amazon Nova に提供する方法です。このセクションでは、Amazon Nova モデルを使用する際にツールを定義して統合する方法について説明します。
ツールの使用には、次の 3 つの大まかなステップがあります。
+ **ユーザークエリ** – Amazon Nova が使用できるツールを定義するには、各ツールの機能と入力要件を説明する JSON スキーマを指定します。
+ **ツールの選択** – ユーザーがメッセージを送信すると、Amazon Nova はそれを分析して、レスポンスを生成するためにツールが必要かどうかを判断します。これは `Auto` ツール選択と呼ばれます。詳細については、「[ツールの選択](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html)」を参照してください。Amazon Nova が適切なツールを特定すると、「ツールを呼び出し」、使用するツールの名前とパラメータが返されます。
開発者は、モデルのリクエストに基づいてツールを実行する責任があります。つまり、ツールの機能を呼び出し、モデルによって提供される入力パラメータを処理するコードを記述する必要があります。
**注記**
すべての LLM レスポンスと同様に、Amazon Nova はツール呼び出しをハルシネーションする可能性があります。開発者は、ツールが存在し、入力が正しくフォーマットされ、適切なアクセス許可がすでに設定されていることを確認する責任があります。
+ **結果を返す** – ツールを実行したら、構造化された形式で結果を Amazon Nova に送り返す必要があります。有効な形式には、JSON またはテキストとイメージの組み合わせが含まれます。これにより、Amazon Nova はツールの出力をユーザーへの最終レスポンスに組み込むことができます。
ツールの実行中にエラーが発生した場合は、これを Amazon Nova へのツールレスポンスで示し、Amazon Nova がそれに応じてレスポンスを調整できるようにします。
計算ツールの簡単な例を考えてみましょう。
------
#### [ User query ]
ツール呼び出しワークフローの最初のステップは、数式「10 掛ける 5」の結果を尋ねる Amazon Nova へのユーザークエリです。このクエリは、計算ツールを表すツール仕様とともに、プロンプトとして Amazon Nova に送信されます。
```
user_query = "10*5"
messages = [{
"role": "user",
"content": [{"text": user_query}]
}]
tool_config = {
"tools": [
{
"toolSpec": {
"name": "calculator", # Name of the tool
"description": "A calculator tool that can execute a math equation", # Concise description of the tool
"inputSchema": {
"json": {
"type": "object",
"properties": {
"equation": { # The name of the parameter
"type": "string", # parameter type: string/int/etc
"description": "The full equation to evaluate" # Helpful description of the parameter
}
},
"required": [ # List of all required parameters
"equation"
]
}
}
}
}
]
}
```
------
#### [ Tool selection ]
Amazon Nova は、ツールのコンテキストとユーザープロンプトを使用して、使用する必要なツールと必要な設定を決定します。これは API レスポンスの一部として返されます。
```
{
"toolUse": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"name": "calculator",
"input": {
"equation": "10*5"
}
}
}
```
アプリケーションはツールを実行し、結果を保存する役割があります。
```
def calculator(equation: str):
return eval(equation)
tool_result = calculator("10*5")
```
------
#### [ Return results ]
ツールの結果を Amazon Nova に返すため、ツールの結果が新しい API リクエストに含まれます。ツール使用 ID は、前のレスポンスで Amazon Nova から返された ID と一致することに注意してください。
```
{
"toolResult": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"content": [
{
"json": {
"result": "50"
}
}
],
"status": "success"
}
}
```
+ Amazon Nova は、最初のユーザークエリ、ツールの使用、ツールの結果など、メッセージの完全なコンテキストを使用して、ユーザーへの最終応答を決定します。この場合、Amazon Nova はユーザーに「10 掛ける 5 は 50 です」と応答します。
------
Amazon Nova では、Invoke API と Converse API の両方でツールを使用できますが、フル機能の範囲では [Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use-inference-call.html) を使用することをお勧めします。今後の例では、この API を使用します。
**Topics**
+ [ツールの定義](tool-use-definition.md)
+ [ツールの呼び出し](tool-use-invocation.md)
+ [ツールの選択](tool-choice.md)
+ [ツールの結果を返す](tool-use-results.md)
+ [組み込みツールの使用](tool-built-in.md)
+ [エラーの報告](tool-use-error.md)
+ [その他のリファレンス](#tool-use-resources)
# ツールの定義
ツール呼び出しワークフローの重要なステップは、ツールを定義することです。ツール定義には、ツールを呼び出すのが適切なタイミングでモデルをガイドするために必要なコンテキストがすべて含まれている必要があります。
ツールを定義するには、ツール設定を作成し、ユーザーメッセージとともに API に渡します。[ツール設定](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html)スキーマには、ツールの配列と、オプションでツール選択パラメータが必要です。
**注記**
Amazon Nova は、`toolChoice` の `auto`、`any`、`tool` オプションをサポートしています。詳細については、「Amazon Bedrock API ドキュメント」の「[ToolChoice](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolChoice.html)」および「[ツールを使用して Amazon Bedrock モデルレスポンスを完成させる](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)」を参照してください。
ツールを定義する方法の例を次に示します。
```
tool_config = {
"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"
]
}
}
}
}
],
}
```
名前、説明、入力スキーマは、ツールの正確な機能を明示的に示す必要があります。ツールを使用するときの主要な差別化要因がツール設定に反映されていることを確認します。
**注記**
Amazon Nova の理解モデルは、現在、Converse API で [ToolInputSchema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolInputSchema.html) を定義する際に使用される、JsonSchema 機能のサブセットのみをサポートしています。
最上位スキーマは [Object](https://json-schema.org/understanding-json-schema/reference/object) 型である必要があります。
最上位のオブジェクトでは、type (「オブジェクト」に設定する必要がある)、[https://json-schema.org/understanding-json-schema/reference/object#properties](https://json-schema.org/understanding-json-schema/reference/object#properties)、および [https://json-schema.org/understanding-json-schema/reference/object#required](https://json-schema.org/understanding-json-schema/reference/object#required) の 3 つのフィールドのみがサポートされています。
ツール呼び出しでは、Greedy デコードを有効にするために温度を 0 に設定することをお勧めします。
Converse API を使用してツールを呼び出す例を次に示します。
```
import json
import boto3
client = boto3.client("bedrock-runtime", region_name="us-east-1")
input_text = "What is the most popular song on WZPZ?"
messages = [{
"role": "user",
"content": [{"text": input_text}]
}]
inf_params = {"maxTokens": 1000, "temperature": 0}
response = client.converse(
modelId="us.amazon.nova-lite-v1:0",
messages=messages,
toolConfig=tool_config,
inferenceConfig=inf_params
)
messages.append(response["output"]["message"])
# Pretty print the response JSON.
print("[Full Response]")
print(json.dumps(response, indent=2))
# Print the tool content for easy readability.
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
print("\n[Tool Response]")
print(tool)
```
# ツールの呼び出し
Amazon Nova がツールを呼び出すことにした場合、アシスタントメッセージの一部としてツール使用ブロックが返され、停止理由は「tool\$1use」になります。ツールブロックには、ツールの名前とその入力が含まれます。
**注記**
ツール呼び出しの精度を向上させるために行う Amazon Nova モデルのデフォルトの動作は、ツール呼び出しに思考連鎖の推論を使用することです。思考プロセスはアシスタントメッセージで利用可能になり、＜thinking> タグに含まれます。レスポンスには複数のツール呼び出しと思考ブロックを含めることができるため、アプリケーションはこれを考慮する必要があります。
ツールの選択が `any` または `tool` に設定されている場合、思考連鎖の動作は上書きされ、レスポンスには必要なツール呼び出しのみが含まれるようになります。
```
{
"toolUse":
{
"toolUseId": "tooluse_20Z9zl0BQWSXjFuLKdTJcA",
"name": "top_song",
"input": {
"sign": "WZPZ"
}
}
}
```
実際のツールの呼び出しにおいて、アプリケーションは、ツール名と引数をメッセージから抽出し、呼び出すことができます。
ツール呼び出しを処理する方法の例を次に示します。
```
def get_top_song(sign):
print(f"Getting the top song at {sign}")
return ("Espresso", "Sabrina Carpenter")
stop_reason = response["stopReason"]
tool, song, artist = None, None, None
if stop_reason == "tool_use":
thought_process = next(
block["text"]
for block in response["output"]["message"]["content"]
if "text" in block
)
print(thought_process)
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
if tool["name"] == "top_song":
song, artist = get_top_song(tool["input"]["sign"])
```
ツールを定義して呼び出すときは、セキュリティに留意することが重要です。Amazon Nova などの LLM はセッションの詳細にアクセスできないため、ツールを呼び出す前に必要に応じてアクセス許可を有効化する必要があります。プロンプトを拡張し、Amazon Nova にツール呼び出しへの挿入を許可するのではなく、セッションのユーザーの詳細を使用してください。
# ツールの選択
Amazon Nova モデルは、*ツール選択*の機能をサポートしています。ツールの選択により、開発者はツールの呼び出し方法を制御できます。ツールの選択には、`tool`、`any`、`auto` の 3 つのパラメータオプションがサポートされています。
+ **ツール** – 指定されたツールは 1 回呼び出されます。
+ **任意** – 提供されたツールの 1 つが少なくとも 1 回呼び出されます。
+ **自動** – モデルはツールを呼び出すかどうかを決定し、必要に応じて複数のツールが呼び出されます。
------
#### [ Tool ]
ツールの選択として `tool` を使用すると、モデルが呼び出す特定のツールを制御できます。以下の例では、レスポンスを一貫した方法でフォーマットする必要がある構造化された出力ユースケースを用いて、この点を明確に示しています。
```
tool_config = {
"toolChoice": {
"tool": { "name" : "extract_recipe"}
},
"tools": [
{
"toolSpec": {
"name": "extract_recipe",
"description": "Extract recipe for cooking instructions",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the recipe"
},
"description": {
"type": "string",
"description": "Brief description of the dish"
},
"ingredients": {
"type": "array",
"items": {
"type": "string",
"description": "Name of ingredient"
}
}
},
"required": ["name", "description", "ingredients"]
}
}
}
}
]
}
```
------
#### [ Any ]
ツールの選択として `any` を使用すると、毎回少なくとも 1 つのツールが呼び出されるようにできます。呼び出すツールの決定はモデルに委ねられますが、常にツールが返されます。以下の例では、API 選択エンドポイントのユースケースでのツール選択の使用に焦点を当てています。これは、モデルが特定のツールを返すように要求することが役立つ場合の例の 1 つです。
```
tool_config = {
"toolChoice": {
"any": {}
},
"tools": [
{
"toolSpec": {
"name": "get_all_products",
"description": "API to retrieve multiple products with filtering and pagination options",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sort_by": {
"type": "string",
"description": "Field to sort results by. One of: price, name, created_date, popularity",
"default": "created_date"
},
"sort_order": {
"type": "string",
"description": "Order of sorting (ascending or descending). One of: asc, desc",
"default": "desc"
},
},
"required": []
}
}
}
},
{
"toolSpec": {
"name": "get_products_by_id",
"description": "API to retrieve retail products based on search criteria",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Unique identifier of the product"
},
},
"required": ["product_id"]
}
}
}
}
]
}
```
------
#### [ Auto ]
ツールの選択として `auto` を使用することは、ツールサポートのデフォルトの機能であり、モデルはツールを呼び出すタイミングと呼び出すツールの数を決定できます。これは、リクエストにツールの選択を含めない場合の動作です。
**注記**
Amazon Nova ツール呼び出しのデフォルトの動作は、ツールの選択に思考連鎖を使用することです。デフォルトの動作またはツール選択 `auto` を使用する場合、 タグの思考プロセス出力もあります。
次の例では、モデルがインターネットで最新情報を検索したり、ユーザーに直接応答したりできるようにするチャットボットのユースケースを示しています。このツールの選択は柔軟性を提供し、推論をモデルに任せることになります。
```
tool_config = {
"toolChoice": {
"auto": {}
},
"tools": [
{
"toolSpec": {
"name": "search",
"description": "API that provides access to the internet",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Query to search by",
},
},
"required": ["query"]
}
}
}
}
]
}
```
------
**注記**
ツール選択パラメータを設定すると、元のツール選択後にモデル出力テキストが表示される、または連続したツール呼び出しが実行される可能性があります。ここで停止シーケンスを設定して、出力をツールのみに制限することをお勧めします。
```
“stopSequences”: [“”]
```
詳細については、「Amazon Bedrock API ガイド」の「[InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_InferenceConfiguration.html)」を参照してください。
# ツールの結果を返す
ツールがアプリケーションによって呼び出されたら、最後のステップはツールの結果をモデルに返すことです。これは、ツール呼び出しの ID とレスポンスコンテンツのツール結果を返すことによって行われます。このコンテンツは [ToolResultBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultBlock.html) スキーマに従います。
```
{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}],
"status": "success"
}
}
```
`ToolResultBlock` の内容は、単一の JSON またはテキストとイメージの組み合わせである必要があります。
ステータスフィールドを使用して、ツール実行のステータスをモデルに指定できます。ツールの実行が失敗した場合、失敗を示すことができ、Amazon Nova は元のツール呼び出しの変更を試みます。
スキーマの詳細については、[ToolResultContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultContentBlock.html) のドキュメントを参照してください。
Converse API を使用してツール結果を返す方法の例を次に示します。
```
messages.append({
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}],
"status": "success"
}
}
]
})
inf_params = {"maxTokens": 1000, "temperature": 0}
# Send the tool result to the model.
response = client.converse(
modelId="us.amazon.nova-lite-v1:0",
messages=messages,
toolConfig=tool_config,
inferenceConfig=inf_params
)
print(response['output']['message'])
```
ツールの活用方法の詳細については、「[Amazon Bedrock ツールの使用](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)」ドキュメントを参照するか、Amazon Nova サンプルリポジトリの[ツール使用のサンプル](https://github.com/aws-samples/amazon-nova-samples/blob/main/multimodal-understanding/repeatable-patterns/10-tool-calling-with-converse/10_tool_calling_with_converse.ipynb)を参照してください。
# 組み込みツールの使用
組み込みツールは、カスタム実装を必要とせずに、すぐに使用できるフルマネージドツールです。これらは、シンプルな切り替えで Converse API で有効にできます。
## コードインタープリタ
コードインタープリタを使用すると、Nova は分離されたサンドボックス環境で Python コードを安全に実行できます。これにより、コードの記述と実行、データの分析、視覚化の作成、数学的な問題の解決を行えるようになります。たとえば、コードインタープリタを使用して以下を行えます。
+ アップロードされたデータに基づいて財務レポートを生成する
+ 統計分析またはアルゴリズムシミュレーションを完了する
+ 分離された環境でデータベース移行スクリプトを実行する
+ 新しく生成されたコードのユニットテストを実行する
Converse API でコードインタープリタを有効にする方法の例を次に示します。
```
{
"messages": [
{
"role": "user",
"content": [{"text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82")}]
}
],
"toolConfig": {
"tools": [
{
"systemTool": {
"name": "nova_code_interpreter"
}
}
]
},
```
ここでは、モデルはリクエストに計算が必要であると判断し、必要な Python コードを生成してコードインタープリタツールを呼び出します。
```
{
"toolUse": {
"input": {
"code": "'''Calculate the average of the given numbers.'''\nnumbers = [10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82]\nsum_numbers = sum(numbers)\ncount = len(numbers)\naverage = sum_numbers / count\n(sum_numbers, count, average)"
},
"name": "nova_code_interpreter",
"toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ",
"type": "server_tool_use"
}
},
```
インタープリタはこのコードをサンドボックスで実行し、結果と出力を標準スキーマにキャプチャします。
```
{
"stdOut": String,
"stdErr": String,
"exitCode": int,
"isError": boolean
}
```
この場合、以下が返されます。
```
{
"toolResult": {
"content": [
{
"text": "{\"stdOut\":\"(1212, 12, 101.0)\",\"stdErr\":\"\",\"exitCode\":0,\"isError\":false}"
}
],
"status": "success",
"toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ",
"type": "nova_code_interpreter_result"
}
}
```
## モデルコンテキストプロトコル
モデルコンテキストプロトコル (MCP) は、開発者がデータソースと AI 搭載ツール間の安全な双方向接続を構築できるようにするオープンスタンダードです。API またはサービスごとにカスタムアダプターを記述する代わりに、MCP サーバーを実行し、Nova にクライアントブリッジを介してツールを自動的に検出させることができます。接続されると、Nova はこれらのツールを他の外部統合と同様に扱います。これらのツールを呼び出すタイミングを決定し、必要なパラメータを送信し、その結果をレスポンスに組み込みます。
# エラーの報告
Amazon Nova によって選択されたパラメータが外部エラーを引き起こす場合があります。このような場合、これを Amazon Nova にフィードバックして、リクエストを変更して再試行できるようにすることが有益です。エラーを通知するには、ツールの結果を返しつつも、ステータスを変更してエラーを報告し、例外メッセージを共有します。
エラーステータスのメッセージを報告する例を次に示します。
```
tool_result_message = {
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool["toolUseId"],
"content": [{"text": "A validation exception occured on field: sample.field"}],
"status": "error"
}
}
]
}
```
## その他のリファレンス
1. [ツールを使用してモデルレスポンスを完成させる](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)
1. [Amazon Nova を使用した AI エージェントの構築](agents.md)
1. [テキスト理解のプロンプトのベストプラクティス](prompting-text-understanding.md)
1. [ツール呼び出しのトラブルシューティング](prompting-tool-troubleshooting.md)