# ツールの使用 (関数呼び出し)
ツールは、モデルを API、データベース、コード実行環境などの外部機能と連携させることで、Amazon Nova の機能を拡張します。ツールを使用すると、Amazon Nova はリアルタイム情報にアクセスし、計算を実行し、外部システムとやり取りできます。
## ツール使用ワークフローについて
Amazon Nova でのツール使用には、次の 3 つの重要なフェーズがあります。
ユーザークエリとツールの定義
各ツールの機能および入力要件を記述する JSON スキーマを指定してツールを定義します。ツール設定には、各ツールをいつ、どのように使用するかについての明示的な詳細を含める必要があります。
ツールの選択
ユーザーがメッセージを送信すると、Amazon Nova はそれを分析して、ツールが必要かどうかを判断します。この自動ツール選択は、コンテキストを調べ、呼び出すツール (ある場合) を決定します。Amazon Nova が適切なツールを特定すると、ツール名と必要なパラメータを返します。
モデルのリクエストに基づいてツールを実行する責任は、ユーザーにあります。つまり、ツールの機能を呼び出し、モデルによって提供される入力パラメータを処理するコードを記述することになります。
結果を返す
ツールを実行したら、JSON またはテキストとイメージの組み合わせを使用して、構造化された形式で結果を Amazon Nova に送信します。Amazon Nova はツールの出力を最終レスポンスに組み込みます。実行中にエラーが発生した場合は、これをツールレスポンスで示して、Amazon Nova がそれに応じて調整できるようにします。
## ツールを作成する
ツールの配列とオプションでツール選択パラメータを含むツール設定を使用してツールを定義します。各ツール仕様には、以下を含める必要があります。
+ **名前**: ツールの明確な識別子
+ **説明:** ツールの機能の簡潔な説明
+ **入力スキーマ:** 必須パラメータとオプションパラメータを定義する JSON スキーマ
**Example ツール設定の例**
```
tool_config = {
"tools": [
{
"toolSpec": {
"name": "calculator",
"description": "A calculator tool that can execute a math equation",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"equation": {
"type": "string",
"description": "The full equation to evaluate"
}
},
"required": ["equation"]
}
}
}
}
]
}
```
### ツール定義のベストプラクティス
+ 名前と説明がツールの正確な機能を明示的に伝えるようにします。意味的に類似しすぎるツールにならないようにします
+ モデルが類似ツールを区別するのに役立つように、説明に主要な差別化要因を含めます
+ JSON スキーマを 2 つのネストレイヤーに制限して最高のパフォーマンスを実現します
+ プレーンテキストで構造を記述するのではなく、スキーマタイプ (enum、int、float など) を使用して入力を制限します
+ JSON スキーマ表記を使用して必須パラメータとオプションパラメータを指定します (例:「required」: [「param1」、「param2」])
+ 送信する前に標準バリデータを使用して JSON スキーマを検証します
+ 長い文字列引数をスキーマの最後に配置し、ネストを避けます
### 制約付きデコードを使用した構造化出力
Amazon Nova モデルは、制約付きデコードを活用して、生成された出力の信頼性を高めます。この手法では、文法を使用して各生成ステップで可能なトークンを制限し、無効なキーを防ぎ、定義されたスキーマに基づいて正しいデータ型を適用します。
**Example 構造化出力の例**
```
tool_config = {
"tools": [
{
"toolSpec": {
"name": "ProductAnalysis",
"description": "Analyze product information from text.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Product name"
},
"rating": {
"maximum": 5,
"description": "Customer rating 1-5",
"type": ["number", "null"],
"minimum": 1
},
"features": {
"description": "Key product features",
"type": "array",
"items": {"type": "string"}
},
"category": {
"type": "string",
"description": "Product category"
},
"price": {
"type": "number",
"description": "Price in USD"
}
},
"required": ["name", "category", "price", "features"]
}
}
}
}
],
"toolChoice": {
"tool": {"name": "ProductAnalysis"}
}
}
```
### ツール選択オプション
Amazon Nova は、次の 3 つのツール選択パラメータをサポートしています。
ツール
指定されたツールは 1 回呼び出され、構造化された出力のユースケースに最適です
いずれか
提供されているツールの 1 つが少なくとも 1 回呼び出され、API 選択シナリオに役立ちます
自動
モデルは、ツールを呼び出すかどうか、および呼び出すツールの数を決定します (デフォルトの動作)
## ツールを呼び出す
Amazon Nova がツールを呼び出す際、アシスタントメッセージの一部としてツール使用ブロックが返され、stopReason は「tool\$1use」になります。ツールブロックには、ツール名とその入力が含まれます。
**注記**
次のコードセクションを 1 つの Python セッションで順番に実行します (ツールの呼び出し → ツールの呼び出しの処理 → ツールの結果を返す)。例を再度実行するには、Python セッションを再起動します。
**Example ツールの呼び出し**
```
import boto3
import json
# Create Bedrock client
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
# Complex calculation that benefits from precise computation
messages = [{
"role": "user",
"content": [{
"text": "Calculate the compound interest on $10,000 invested at 4.75% annual rate for 7 years, compounded quarterly. Use the formula A = P(1 + r/n)^(nt) where P=10000, r=0.0475, n=4, t=7"
}]
}]
# Define tool configuration with calculator
tool_config = {
"tools": [{
"toolSpec": {
"name": "calculator",
"description": "Perform mathematical calculations",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "Mathematical expression to evaluate"
}
},
"required": ["expression"]
}
}
}
}]
}
# Invoke Model
response = bedrock.converse(
modelId="us.amazon.nova-2-lite-v1:0",
messages=messages,
toolConfig=tool_config
)
# Extract tool use from response
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
print(f"Tool: {tool['name']}")
print(f"Expression: {tool['input']['expression']}")
```
### ツール呼び出しの処理
メッセージからツール名と引数を抽出し、ツールを呼び出します。
```
def calculate(expression):
"""Evaluate mathematical expression"""
print(f"Calculating: {expression}")
P = 10000
r = 0.0475
n = 4
t = 7
result = P * (1 + r/n) ** (n*t)
return result
stop_reason = response["stopReason"]
if stop_reason == "tool_use":
if tool["name"] == "calculator":
result = calculate(tool["input"]["expression"])
```
### ツールの結果を返す
ToolResultBlock スキーマを使用してツールの結果を返します。
```
messages.append(response["output"]["message"])
# Add the tool result
messages.append({
"role": "user",
"content": [{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"result": result}}],
"status": "success"
}
}]
})
# Send the tool result to the model
response = bedrock.converse(
modelId="us.amazon.nova-2-lite-v1:0",
messages=messages,
toolConfig=tool_config
)
# Extract and display final response
final_text = next(
block["text"]
for block in response["output"]["message"]["content"]
if "text" in block
)
print(f"\nFinal Response:\n{final_text}")
```
### エラー処理
Amazon Nova にエラーを報告して、リクエストの変更と再試行を許可します。
```
tool_result_message = {
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool["toolUseId"],
"content": [{"text": "A validation exception occurred on field: sample.field"}],
"status": "error"
}
}
]
}
```
### セキュリティに関する考慮事項
+ 呼び出す前にツールが存在することを確認します
+ 入力が正しくフォーマットされていることを確認します
+ ツールを実行する前に、適切なアクセス許可が設定されていることを確認します
+ Amazon Nova がユーザー情報をツール呼び出しに挿入できるようにするのではなく、セッションの詳細を利用します
+ LLM がツール呼び出しをハルシネーションする可能性があることに注意し、実行前に必ず検証してください
## 組み込みシステムツール
Amazon Nova 2.0 モデルには、カスタム実装を必要としないフルマネージドの組み込みツールが含まれています。Converse API でシンプルな切り替えでこれらのツールを有効にします。
### コードインタープリタ
コードインタープリタを使用すると、Nova は分離されたサンドボックス環境で Python コードを安全に実行できます。このツールは、数学的計算、論理演算、反復アルゴリズム用に設計されています。
**注記**
コードインタープリタは、IAD、PDX、および NRT AWSリージョンで使用できます。リクエストがサポートされているリージョンにルーティングされるようにするには、グローバル CRIS を使用します。Bedrock API キーを使用する場合は、ポリシー定義に `InvokeTool` アクセス許可を手動で追加する必要があります。デフォルトの Bedrock ロールでは、`InvokeTool` アクションは許可されません。
systemTool パラメータを指定して Code Interpreter を有効にします。
```
import boto3
import json
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
tool_config = {
"tools": [{
"systemTool": {
"name": "nova_code_interpreter"
}
}]
}
response = bedrock.converse(
modelId="us.amazon.nova-2-lite-v1:0",
messages=[{
"role": "user",
"content": [{
"text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82"
}]
}],
toolConfig=tool_config,
inferenceConfig={"maxTokens": 10000, "temperature": 0}
)
# Pretty print the response
for block in response["output"]["message"]["content"]:
if "toolUse" in block:
print("=== Tool Use ===")
print(f"Tool: {block['toolUse']['name']}")
print(f"Code:\n{block['toolUse']['input']['snippet']}\n")
elif "toolResult" in block:
print("=== Tool Result ===")
result = block['toolResult']['content'][0]['json']
print(f"Output: {result['stdOut']}")
if result['stdErr']:
print(f"Error: {result['stdErr']}")
print(f"Exit Code: {result['exitCode']}\n")
elif "text" in block:
print("=== Final Answer ===")
print(block["text"])
```
インタープリタはコードをサンドボックスで実行し、結果を標準スキーマで返します。
```
{
"stdOut": "String",
"stdErr": "String",
"exitCode": "int",
"isError": "boolean"
}
```
### ウェブグラウンディング
ウェブグラウンディングにより、Amazon Nova はインターネットからリアルタイムの情報にアクセスし、最新のレスポンスを提供し、ハルシネーションを軽減できます。nova\$1grounding システムツールを指定して有効にします。
```
tool_config = {
"tools": [{
"systemTool": {"name": "nova_grounding"}
}]
}
```
ウェブグラウンディングの詳細については、「[ウェブグラウンディング](web-grounding.md)」を参照してください。
### モデルコンテキストプロトコル (MCP)
モデルコンテキストプロトコル (MCP) は、データソースと AI 搭載ツール間の安全な双方向接続を行えるオープンスタンダードです。API またはサービスごとにカスタムアダプターを記述する代わりに、MCP サーバーを実行し、Amazon Nova にクライアントブリッジを介してツールを自動的に検出させます。
接続されると、Amazon Nova は MCP ツールを他の外部統合と同様に扱います。これらのツールを呼び出すタイミングを決定し、必要なパラメータを送信し、その結果をレスポンスに組み込みます。Strands で Amazon Nova を使用すると、検出、接続、結果マッピングを自動的に管理する組み込み MCPClient でこれが簡単になります。