# Tool Use, RAG, and Agentic Flows with Amazon Nova Sonic
**Note**
This documentation is for Amazon Nova Version 1. For the Amazon Nova 2 Sonic guide, visit [Tool configuration](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-tool-configuration.html).
The Amazon Nova Sonic model extends its capabilities beyond pre-trained knowledge by supporting tool use. Tool use, sometimes called function calling, enables integration with external functions, APIs, and data sources. This section explains how to implement tool use, Retrieval-Augmented Generation (RAG), and agentic workflows with Amazon Nova Sonic.
![\[Diagram that explains how Amazon Nova Sonic calls a tool and uses it to generate results.\]](http://docs.aws.amazon.com/nova/latest/userguide/images/novaSonicDiagram.png)
You can control what tool the model uses by specifying the `toolChoice` parameter. For more information, see [Choosing a tool](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html).
**Topics**
+ [
# Using tools
](speech-tools-use.md)
+ [
# Controlling how tools are chosen
](speech-tools-choice.md)
+ [
# Tool choice best practices
](speech-tools-bp.md)
+ [
# Implementing RAG
](speech-rag.md)
+ [
# Building agentic flows
](speech-agentic.md)
# Using tools
**Note**
This documentation is for Amazon Nova Version 1. For the Amazon Nova 2 Sonic guide, visit [Tool configuration](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-tool-configuration.html).
In order to use a tool, it must be defined as part of the `promptStart` event in your session configuration. This is demonstrated in the following code:
```
{
"event": {
"promptStart": {
"promptName": "string",
"textOutputConfiguration": {
"mediaType": "text/plain"
},
"audioOutputConfiguration": {
"mediaType": "audio/lpcm",
"sampleRateHertz": 8000 | 16000 | 24000,
"sampleSizeBits": 16,
"channelCount": 1,
"voiceId": "matthew" | "tiffany" | "amy",
"encoding": "base64",
"audioType": "SPEECH"
},
"toolUseOutputConfiguration": {
"mediaType": "application/json"
},
"toolConfiguration": {
"tools": [
{
"toolSpec": {
"name": "string",
"description": "string",
"inputSchema": {
"json": "{}"
}
}
}
]
}
}
}
}
```
## Tool definition components
Each tool specification requires the following elements:
+ **Name** - A unique identifier for the tool.
+ **Description** - A explanation of what the tool does and when it should be used.
+ **Input schema** - The JSON schema that defines the required parameters.
## Basic tool example
Here's an example of a simple tool that retrieves information about the current date. For more information on how to define a tool, see [Defining a tool](https://docs.aws.amazon.com/nova/latest/userguide/tool-use-definition.html).
```
// A simple tool with no required parameters
const dateTool = {
toolSpec: {
name: "getDateTool",
description: "Get information about the current date",
inputSchema: {
json: JSON.stringify({
type: "object",
properties: {},
required: []
})
}
}
};
```
And here is what the `promptStart` event would look like:
```
{
event: {
promptStart: {
promptName: "string",
textOutputConfiguration: {
mediaType: "text/plain"
},
audioOutputConfiguration: {
mediaType: "audio/lpcm",
sampleRateHertz: 24000,
sampleSizeBits: 16,
channelCount: 1,
voiceId: "tiffany",
encoding: "base64",
audioType: "SPEECH"
},
toolUseOutputConfiguration: {
mediaType: "application/json"
},
toolConfiguration: {
tools: [
{
toolSpec: {
name: "getDateTool",
description: "get information about the current date",
inputSchema: {
json: JSON.stringify({
type: "object",
properties: {},
required: []
})
}
}
}
]
}
}
}
}
```
# Controlling how tools are chosen
**Note**
This documentation is for Amazon Nova Version 1. For the Amazon Nova 2 Sonic guide, visit [Tool configuration](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-tool-configuration.html).
Amazon Nova Sonic supports three tool choice parameters to help you manage tool execution. You can control which tool the model uses by specifying the `toolChoice` parameter.
+ **Tool** - The `tool` option ensures that the specific named tool is called exactly once at the beginning of the response generation. For example, if you specify a knowledge base tool, the model will query this knowledge base before responding, regardless of whether it thinks the tool is needed.
+ **Any** - The `any` option ensures at least one of the available tools is called at the beginning of the response generation, while allowing the model to select the most appropriate one. This is useful when you have multiple knowledge bases or tools and want to ensure the model leverages at least one of them without specifying which one.
+ **Auto** - With `auto`, the model has complete flexibility to determine whether any tools are needed at the beginning of the response generation and can call multiple tools if required. This is also the default behavior.
For more information, see [Tool use with Amazon Nova](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html).
**Multi-tool sequence behavior**
Amazon Nova Sonic handles tool execution intelligently within each response cycle. When you use the `tool` option, the model will first execute the specified tool, then evaluate whether additional tools are needed before generating its final response. Similarly, with the `any` option, the model first selects and calls one tool from the available options, then decides if additional tool calls would be needed before proceeding to generate its answer.
In all cases, the model manages the entire tool execution sequence within a single response generation cycle, determining when sufficient information has been gathered to generate an appropriate response.
Consider the following example scenarios:
------
#### [ Knowledge base example ]
+ With `toolChoice: "knowledge_tool"`, the model will always query the specified knowledge base first, then possibly use other tools before responding if needed.
+ With `toolChoice: "any"` and multiple knowledge bases available, the model will select the most relevant knowledge base, query it, and then possibly consult additional sources if needed.
+ With `toolChoice: "auto"`, the model may skip knowledge lookups entirely for questions it can answer directly, or query multiple knowledge bases for complex questions.
------
#### [ Multi-functional assistant example ]
+ A virtual assistant with weather, calendar, and knowledge tools could use `toolChoice: "auto"` to flexibly respond to diverse queries, calling only the necessary tools.
+ Using `toolChoice: "any"` would ensure at least one tool is always used, even for queries the model could potentially answer directly.
------
To learn more, please refer to [Tool Choice](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html).
# Tool choice best practices
**Note**
This documentation is for Amazon Nova Version 1. For the Amazon Nova 2 Sonic guide, visit [Tool configuration](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-tool-configuration.html).
When implementing tools with Amazon Nova Sonic, we recommend following these best practices to ensure optimal performance:
+ **Keep schema structure simple**: Limit top-level keys to 3 or fewer when possible.
+ **Create distinct parameter names**: Use clear, semantically different names between similar parameters to avoid confusion (that is, don't use both "product\$1id" and "cart\$1item\$1id" if they serve different purposes).
+ **Provide detailed tool descriptions**: Clearly describe each tool's purpose and when it should be used to help the model select the appropriate tool.
+ **Define input schemas precisely**: Specify parameter types and include descriptions for each parameter. Clearly indicate which parameters are required versus optional.
+ **Monitor context length**: Tool performance may degrade as context approaches larger tokens (that is, approximately 50K tokens). Consider breaking complex tasks into smaller steps when working with long contexts.
+ **Implement error handling**: Prepare for cases when tool execution fails by including appropriate fallback behaviors.
+ **Test thoroughly**: Verify your tools work across a variety of inputs and edge cases before deployment.
+ **Greedy decoding parameters**: Set the value of temperature to 0 for tool use.
We recommend that you avoid the following common issues:
+ When you encounter JSON schema adherence failures, you might need to simplify your schema structure or provide clearer instructions.
+ Be mindful that the model might omit optional parameters that would improve results (such as 'limit' parameters in queries).
By following these guidelines, you can leverage the full capabilities of the Amazon Nova Sonic model's tool use features to create powerful conversational AI applications that can access external data sources and perform complex actions.
# Implementing RAG
**Note**
This documentation is for Amazon Nova Version 1. For the Amazon Nova 2 Sonic guide, visit [Tool configuration](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-tool-configuration.html).
Retrieval-Augmented Generation (RAG) enhances responses by retrieving and incorporating information from your knowledge bases. With Amazon Nova Sonic, RAG is implemented through tool use.
## Knowledge base implementation outline
Implementing a RAG requires the following elements:
+ **Configure the tool** - Define a knowledge base search tool in your `promptStart` event.
+ **Receive Tool Use Request** - When the user asks a question, the model will call the knowledge base tool.
+ **Query Vector Database** - Execute the search query against your vector database.
+ **Return Results** - Send the search results back to the model.
+ **Generate Response** - The model incorporates the retrieved information in its spoken response.
## Knowledge base configuration
Here is an example configuration of a basic knowledge base tool:
```
{
toolSpec: {
name: "knowledgeBase",
description: "Search the company knowledge base for information",
inputSchema: {
json: JSON.stringify({
type: "object",
properties: {
query: {
type: "string",
description: "The search query to find relevant information"
}
},
required: ["query"]
})
}
}
};
```
# Building agentic flows
**Note**
This documentation is for Amazon Nova Version 1. For the Amazon Nova 2 Sonic guide, visit [Tool configuration](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-tool-configuration.html).
For more complex use cases, you can implement agentic flows by configuring multiple tools that work together to accomplish tasks. Amazon Nova Sonic can orchestrate these tools based on user requests.
## Knowledge base implementation outline
**Hotel Reservation Cancellation Agent Example**
Here is an example configuration of a hotel reservation cancellation system:
```
toolConfiguration: {
tools: [
{
toolSpec: {
name: "getReservation",
description: "Retrieves hotel reservation information based on the guest's name and check-in date",
inputSchema: {
json: JSON.stringify({
type: "object",
properties: {
name: {
type: "string",
description: "Full name of the guest who made the reservation"
},
checkInDate: {
type: "string",
description: "The check-in date for the reservation in YYYY-MM-DD format"
}
},
required: ["name", "checkInDate"]
})
}
}
},
{
toolSpec: {
name: "cancelReservation",
description: "Cancels a hotel reservation after confirming the cancellation policy with the guest",
inputSchema: {
json: JSON.stringify({
type: "object",
properties: {
reservationId: {
type: "string",
description: "The unique identifier for the reservation to be cancelled"
},
confirmCancellation: {
type: "boolean",
description: "Confirmation from the guest that they understand the cancellation policy and want to proceed",
default: false
}
},
required: ["reservationId", "confirmCancellation"]
})
}
}
}
]
}
```
**Hotel Search Agent Example**
And here is an example configuration of a hotel search agent:
```
toolSpec: {
name: "searchHotels",
description: "Search for hotels by location, star rating, amenities and price range.",
inputSchema: {
json: JSON.stringify({
type: "object",
properties: {
location: {
type: "string",
description: "City or area to search for hotels"
},
rating: {
type: "number",
minimum: 1,
maximum: 5,
description: "Minimum star rating (1-5)"
},
amenities: {
type: "array",
items: {
type: "string"
},
description: "List of desired amenities"
},
price_range: {
type: "object",
properties: {
min: {
type: "number",
minimum: 0
},
max: {
type: "number",
minimum: 0
}
},
description: "Price range per night"
}
},
required: []
})
}
}
```