Grounding responses with real-time search results

Note

This documentation is for Amazon Nova Version 1. For information about using Web Grounding with Amazon Nova 2, visit Web Grounding.

Web Grounding enhances Nova models by connecting them to real-time information beyond their knowledge cutoff, which results in more accurate and reliable responses.

How Web Grounding works

When Web Grounding is enabled for a prompt, the following steps are performed:

1. Request Configuration — Your application sends a user prompt to the Amazon Bedrock API with nova_grounding enabled as a systemTool.

2. Search Assessment — The model analyzes the prompt and determines if search is needed to improve the response.

3. Search Execution — When required, the model automatically performs one or more searches for relevant information.

4. Result Analysis — The model decides whether additional searches are required, to expand its understanding or dive deeper on specific subtopics.

5. Response Generation — Nova automatically synthesizes information from search results to generate a final API response grounded in real-time information, complete with citations to its sources.

How to use Web Grounding

To include Web Grounding in your results, specify the following systemTool parameter in your toolConfig block:

"toolConfig": {
    "tools": [
        {"systemTool": {"name": "nova_grounding"}}
    ]
}

In your toolConfig, add a tool with the systemTool parameter as in the example above. This parameter allows you to specify system-defined tools. System-defined tools are tools that are provided and invoked by the model provider. For details on using the systemTool parameter, see SystemTool in the Amazon Bedrock API reference.

Note

Web Grounding is only available in US regions. You can use Web Grounding by calling Amazon Nova Premier with the cross-region inference profile us.amazon.nova-premier-v1:0.

The following example is an AWS CLI command using Web Grounding:

aws --profile 111122223333 --region us-east-1 bedrock-runtime converse --model-id us.amazon.nova-premier-v1:0 --tool-config '{"tools":[{"systemTool":{"name":"nova_grounding"}}]}' --messages '[{"role":"user","content":[{"text":"What is the latest news about renewable energy sources?"}]}]'

The following is an example response. The response has been shortened for brevity:

...
{
    "text": ".\n- **Solar energy** is leading growth with a 31% increase in generation in early 2025, outpacing wind's 7.7% growth "
},
{
    "citationsContent": {
        "citations": [
            {
                "location": {
                    "web": {
                        "url": "https://www.rfi.fr/en/environment/20251008-renewables-overtake-coal-but-growth-slows-amid-us-and-china-report-shows",
                        "domain": "rfi.fr"
                    }
            }
         }
        ]
    }
},
...

This response contains two components: the text generated by the model and the citation information for that text. Included elements are:

• text — A segment of the model's generated response.

• citationsContent — The primary container for the citation data related to a text segment.

• citations — A container within citationsContent that holds the location of a citation.

• location — A container within citations that holds the source of a citation.

• web — A container within location that holds the web source details.

• url — The full web address (URL) of the citation's source.

• domain — The root domain of the source url.

Grounding Safety

Your data never leaves AWS infrastructure. Model-generated queries stay within AWS services and are never sent to the broader internet. Our expansive internal web search index and knowledge graphs prioritize trustworthy and high quality sources and filter malicious content on ingress. Web Grounding further refines the information at runtime by cross-referencing from multiple sources. Finally, we protect your application against indirect prompt injection and misinformation with runtime filtering (note that this mitigation is limited for non-English languages).

Error Handling

Do not include a toolSpec entry with the name nova_grounding. Including a tool with this name will result in an error.

The following is a list of potential errors that can occur when using Web Grounding:

• malformed_tool_use

• max_tokens

• malformed_model_output

Debugging Tool Access

To ensure your role can access Web Grounding on AWS Bedrock, you have two options:

1. Enable BedrockFullAccess on your IAM role: If your role has BedrockFullAccess, it will have access automatically to Web Grounding.

2. Add Specific Permissions (if needed): If you require more granular access control, add this policy to your role's IAM policy, replacing the red text with your AWS account ID:

   
   { 
       Statement: [ 
         { 
           Effect: "Allow", 
           Action: [ "bedrock:InvokeTool" ], 
           Resource: [ "arn:aws:bedrock::{111122223333}:system-tool/amazon.nova_grounding" ] 
          } 
         ] 
   }
                           

Web Grounding has the aws:requestedRegion condition key set to “unspecified”. If your existing policies or Service Control Policies (SCPs) enforce this condition, you may encounter access issues. Updating the condition to allow an "unspecified" requestedRegion can resolve this problem.

Important

If you enable the Web Grounding tool, you are responsible for your use, and any use by your end users, of output that incorporates grounded information. You will know when your output includes grounded information from citations or links to the source material. You must retain and display these citations and links in the output you provide to your end users.

Note

Web Grounding is an additional cost. For more information see https://aws.amazon.com//bedrock/pricing/