Tools are a way to provide external functionality to Amazon Nova such as an API call or a code function. This section will cover how you can define and integrate with tools when working with Amazon Nova models.
Tool use involves three high level steps:
-
User query - You define the tools that Amazon Nova can use by providing a JSON schema that describes each tool's functionality and input requirements.
-
Tool Selection - When a user sends a message, Amazon Nova will analyze it to determine if a tool is necessary to generate a response. This is referred to as
Autotool choice. See Choosing a tool for more information. If Amazon Nova identifies a suitable tool, it will "call the tool" and return the name of the tool and the parameters to use.You, as the developer, are responsible for executing the tool based on the model's request. This means you need to write the code that invokes the tool's functionality and processes the input parameters provided by the model.
Note
Like all LLM responses, it is possible for Amazon Nova to hallucinate a tool call. It is the responsibility of you, the developer, to validate that the tool exists, inputs are formatted correctly, and the appropriate permissions are already in place.
-
Return Results - After executing the tool, you must send the results back to Amazon Nova in a structured format. Valid formats include JSON or a combination of text and images. This allows Amazon Nova to incorporate the tool's output into the final response to the user.
If there are any errors during the tool's execution, you can denote this in the tool response to Amazon Nova, allowing Amazon Nova to adjust its response accordingly.
Consider a simple example of a calculator tool:
The first step in the tool calling workflow is the user query to Amazon Nova for the result of a math equation - 10 times 5. This query is sent as the prompt to Amazon Nova along with a tool specification that represents the calculator.
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"
]
}
}
}
}
]
}Amazon Nova allows tool use in both the Invoke and Converse API however, for full feature breadth we recommend using the Converse API and will be using examples with this API moving forward.
Topics
Additional references
