本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
使用工具 （函數呼叫）
工具透過將模型連接到 APIs、資料庫和程式碼執行環境等外部功能來擴展 Amazon Nova 功能。工具使用可讓 Amazon Nova 存取即時資訊、執行計算並與外部系統互動。
了解工具使用工作流程
搭配 Amazon Nova 使用工具涉及三個關鍵階段：
- 使用者查詢和工具定義
-
透過提供描述每個工具的功能和輸入要求的 JSON 結構描述來定義工具。工具組態必須包含有關何時及如何使用每個工具的明確詳細資訊。
- 工具選擇
-
當使用者傳送訊息時，Amazon Nova 會對其進行分析，以判斷是否需要工具。此自動工具選擇會檢查內容，並決定要叫用哪個工具 （如果有的話）。如果 Amazon Nova 識別合適的工具，則會傳回工具名稱和必要的參數。
您有責任根據模型的請求執行工具。這表示編寫程式碼來叫用工具的功能，並處理模型提供的輸入參數。
- 傳回結果
-
執行工具後，請使用 JSON 或文字和影像的組合，以結構化格式將結果傳回 Amazon Nova。Amazon Nova 會將工具的輸出納入最終回應。如果在執行期間發生錯誤，請在工具回應中指出這一點，以允許 Amazon Nova 相應地調整。
建立工具
使用工具組態來定義工具，其中包含一系列工具和選用的工具選擇參數。每個工具規格必須包含：
-
名稱：清除工具的識別符
-
描述：工具功能的簡要說明
-
輸入結構描述：定義必要和選用參數的 JSON 結構描述
範例工具組態範例
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 結構描述限制為兩層巢狀，以獲得最佳效能
-
使用結構描述類型 （例如列舉、整數、浮點數） 來限制輸入，而不是以純文字描述結構
-
使用 JSON 結構描述表示法 （例如，「必要」：【「param1」、「param2」】) 來表示必要參數與選用參數
-
在提交之前，使用標準驗證器驗證您的 JSON 結構描述
-
將長字串引數最後放在結構描述中，並避免將其巢狀化
具有限制解碼的結構式輸出
Amazon Nova 模型會利用限制解碼，以確保產生輸出中的高可靠性。此技術使用文法來限制每個產生步驟的可能字符，防止無效的金鑰，並根據您定義的結構描述強制執行正確的資料類型。
範例結構化輸出範例
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 支援三種工具選擇參數：
- 工具
-
指定的工具將呼叫一次，非常適合結構化輸出使用案例
- 任何
-
其中一個提供的工具至少會呼叫一次，適用於 API 選擇案例
- 自動
-
模型決定是否呼叫工具，以及要呼叫多少工具 （預設行為）
呼叫工具
當 Amazon Nova 決定呼叫工具時，它會傳回工具使用區塊，做為 stopReason 設定為 "tool_use" 之輔助訊息的一部分。工具區塊包含工具名稱及其輸入。
注意
在單一 Python 工作階段中依序執行下列程式碼區段 （呼叫工具 → 處理工具呼叫 → 傳回工具結果）。若要再次執行範例，請重新啟動 Python 工作階段。
範例呼叫工具
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 將使用者資訊注入工具呼叫
-
請記住，LLMs可以幻化工具呼叫；在執行之前一律驗證
內建系統工具
Amazon Nova 2.0 模型包含完全受管的內建工具，不需要自訂實作。在 Converse API 中使用簡單的切換來啟用這些工具。
程式碼解譯器
Code Interpreter 可讓 Nova 在隔離的沙盒環境中安全地執行 Python 程式碼。此工具專為數學運算、邏輯操作和迭代演算法而設計。
注意
程式碼解譯器適用於 IAD、PDX 和 NRT AWS 區域。若要確保您的請求路由到支援的 區域，請使用全域 CRIS。使用 Bedrock API 金鑰時，您需要手動將InvokeTool許可新增至政策定義。預設 Bedrock 角色不允許 InvokeTool動作。
透過指定 systemTool 參數啟用程式碼解譯器：
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" }
Web Grounding
Web 接地可讓 Amazon Nova 從網際網路存取即時資訊，提供up-to-date回應並減少幻覺。透過指定 nova_grounding 系統工具來啟用 ：
tool_config = { "tools": [{ "systemTool": {"name": "nova_grounding"} }] }
如需 Web Grounding 的詳細資訊，請參閱 Web Grounding。
模型內容通訊協定 (MCP)
模型內容通訊協定 (MCP) 是一種開放標準，可在資料來源和 AI 支援的工具之間啟用安全的雙向連線。執行 MCP 伺服器並讓 Amazon Nova 透過用戶端橋接自動探索其工具，而不是為每個 API 或服務撰寫自訂轉接器。
連線後，Amazon Nova 會將 MCP 工具視為任何其他外部整合：它會決定何時呼叫它們、傳送必要的參數，並將結果納入回應中。搭配 Strands 使用 Amazon Nova 可讓您更輕鬆地使用內建的 MCPClient，自動管理探索、連線和結果映射。
