AWS nova documentation change
Summary
Updated documentation for Web Grounding feature with code examples, clarified response structure, permissions requirements, and safety mechanisms. Changes include formatting fixes, expanded code samples for citation handling, and revised IAM policy guidance.
Security assessment
The changes include clarifications about data staying within AWS infrastructure, malicious content filtering, and protections against prompt injection (security features). However, these are explanations of existing safeguards rather than fixes for vulnerabilities. The IAM policy updates and 'aws:requestedRegion' condition key guidance add security documentation but do not indicate a resolved security issue.
Diff
diff --git a/nova/latest/nova2-userguide/web-grounding.md b/nova/latest/nova2-userguide/web-grounding.md index eedcd65fd..bb6ee59a2 100644 --- a//nova/latest/nova2-userguide/web-grounding.md +++ b//nova/latest/nova2-userguide/web-grounding.md @@ -5 +5 @@ -How Web Grounding worksHow to Use Web GroundingRegional availabilityResponse structureGrounding safetyError handlingPermissions Required for Built in Tools +How Web Grounding worksHow to use Web GroundingRegional availabilityResponse structureGrounding safetyError handlingPermissions required for built in tools @@ -9 +9 @@ How Web Grounding worksHow to Use Web GroundingRegional availabilityResponse str -Web Grounding enhances Nova models by connecting them to real-time information beyond their knowledge cutoff, which results in more accurate and reliable responses. +Web Grounding enables Amazon Nova to search the web for current information and provide responses with citations. This feature is useful for queries requiring up-to-date information beyond the model's training data. @@ -15 +15 @@ Web Grounding enhances Nova models by connecting them to real-time information b - * How to Use Web Grounding + * How to use Web Grounding @@ -25 +25 @@ Web Grounding enhances Nova models by connecting them to real-time information b - * Permissions Required for Built in Tools + * Permissions required for built in tools @@ -34 +34 @@ 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. + 1. **Request Configuration** : Your application sends a user prompt to the Amazon Bedrock API with nova_grounding enabled as a `systemTool`. @@ -36 +36 @@ When Web Grounding is enabled for a prompt, the following steps are performed: - 2. **Search &Analysis** \- The model determines if search is needed, performs one or more searches es for relevant information, and evaluates whether additional searches are required to expand its understanding or dive deeper on specific subtopics. + 2. **Search & Analysis**: The model determines if search is needed, performs one or more searches for relevant information, and evaluates whether additional searches are required to expand its understanding or dive deeper on specific subtopics. @@ -38 +38 @@ When Web Grounding is enabled for a prompt, the following steps are performed: - 3. **Response generation** \- Amazon Nova automatically synthesizes information from search results to generate a final API response grounded in real-time information, complete with citations to its sources. + 3. **Response generation** : Amazon Nova automatically synthesizes information from search results to generate a final API response grounded in real-time information, complete with citations to its sources. @@ -43 +43 @@ When Web Grounding is enabled for a prompt, the following steps are performed: -## How to Use Web Grounding +## How to use Web Grounding @@ -45 +45,3 @@ When Web Grounding is enabled for a prompt, the following steps are performed: -To include Web Grounding in your results, specify ty the following systemTool parameter in your toolConfig block: +For full examples of code that utilizes Web Grounding, see the Code Samples section. + +To include Web Grounding in your results, specify the following `systemTool` parameter in your toolConfig block: @@ -48,0 +51,10 @@ To include Web Grounding in your results, specify ty the following systemTool pa + from botocore.config import Config + + # Create the Bedrock Runtime client with extended timeout + bedrock = boto3.client( + "bedrock-runtime", + region_name="us-east-1", + config=Config(read_timeout=3600) + ) + + # Define the tool configuration @@ -51 +63,3 @@ To include Web Grounding in your results, specify ty the following systemTool pa - "systemTool": {"name": "nova_grounding"} + "systemTool": { + "name": "nova_grounding" + } @@ -55 +69,2 @@ To include Web Grounding in your results, specify ty the following systemTool pa - response = client.converse( + # Send the request + response = bedrock.converse( @@ -59,3 +74 @@ To include Web Grounding in your results, specify ty the following systemTool pa - "content": [{ - "text": "What is the latest news about renewable energy sources?" - }] + "content": [{"text": "What are the latest developments in quantum computing?"}] @@ -63,2 +76,14 @@ To include Web Grounding in your results, specify ty the following systemTool pa - toolConfig=tool_config, - inferenceConfig={"maxTokens": 10000, "temperature": 0} + toolConfig=tool_config + ) + + # Extract text with interleaved citations + output_with_citations = "" + content_list = response["output"]["message"]["content"] + for content in content_list: + if "text" in content: + output_with_citations += content["text"] + elif "citationsContent" in content: + citations = content["citationsContent"]["citations"] + for citation in citations: + url = citation["location"]["web"]["url"] + output_with_citations += f" [{url}]" @@ -70 +95 @@ To include Web Grounding in your results, specify ty the following systemTool pa -Web Grounding is currently only available in US regions and supported only by US CRIS profiles. You can use Web Grounding by calling the specific Nova 2 model with the cross-region inference profile: "us.amazon.nova-2-lite-v1:0" +Web Grounding is currently only available in US regions and supported only by US CRIS profiles. @@ -77,5 +102,7 @@ The following is an example response. The response has been shortened for brevit - n">{ - "text": ". - - **Solar energy** is leading growth with a 31% increase in generation in early 2025, outpacing wind's 7.7% growth", - "citationsContent": { - "citations": [ + { + "output": { + "message": { + "content": [ + { + "text": "Recent quantum computing developments include...", + "citationsContent": [ @@ -85,2 +112,3 @@ The following is an example response. The response has been shortened for brevit - "url": "rfi.fr/en/environment/20251008-renewables-overtake-coal-but-growth-slows-amid-us-and-china-report-shows", - "domain": "rfi.fr" + "url": "https://example.com/quantum-news", + "domain": "example.com" + } @@ -88,0 +117 @@ The following is an example response. The response has been shortened for brevit + ] @@ -92,0 +122 @@ The following is an example response. The response has been shortened for brevit + } @@ -96,2 +126 @@ Each citation includes: -text - + * `text`: A segment of the model's generated response. @@ -99 +128 @@ text -The response text incorporating information from web sources. + * `citationsContent`: The primary container for the citation data related to a text segment. @@ -101 +130 @@ The response text incorporating information from web sources. -citationsContent + * `citations`: A container within `citationsContent` that holds the location of a citation. @@ -102,0 +132 @@ citationsContent + * `location`: A container within `citations` that holds the source of a citation. @@ -104 +134 @@ citationsContent -Array of citations with source information. + * `web`: A container within `location` that holds the web source details. @@ -106 +136 @@ Array of citations with source information. -citations + * `url`: The full web address (URL) of the citation's source. @@ -107,0 +138 @@ citations + * `domain`: The root domain of the source url. @@ -109 +139,0 @@ citations -A container within citationsContent that holds the location of a citation. @@ -111 +140,0 @@ A container within citationsContent that holds the location of a citation. -location @@ -114,17 +142,0 @@ 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. - @@ -133 +145 @@ The root domain of the source url. -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.) +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. Finally, we protect your application against indirect prompt injection and misinformation with runtime filtering (note that this mitigation is limited for non-English languages). @@ -137,3 +149 @@ Your data never leaves AWS infrastructure. Model-generated queries stay within A -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 +Do not include a `toolSpec` entry with the name `nova_grounding`. Including a tool with this name will result in an error. @@ -140,0 +151 @@ malformed_tool_use +The following is a list of potential errors that can occur when using Web Grounding: @@ -142 +153 @@ malformed_tool_use -The model generated an invalid tool use request. Retry with a clearer prompt or different parameters. + * `malformed_tool_use` @@ -144 +155 @@ The model generated an invalid tool use request. Retry with a clearer prompt or -max_tokens + * `max_tokens` @@ -145,0 +157 @@ max_tokens + * `malformed_model_output` @@ -147 +158,0 @@ max_tokens -The response exceeded the maximum token limit. @@ -149 +159,0 @@ The response exceeded the maximum token limit. -malformed_model_output @@ -152 +162 @@ malformed_model_output -The model generated invalid output. This is typically a transient error - retry the request. +## Permissions required for built in tools @@ -154 +164 @@ The model generated invalid output. This is typically a transient error - retry -## Permissions Required for Built in Tools +To ensure your role can access Web Grounding on Amazon Bedrock, you have two options: @@ -156 +166 @@ The model generated invalid output. This is typically a transient error - retry - 1. **Enable BedrockFullAccess on your IAM role** \- If your role has BedrockFullAccess, it will have automatic access to Web Grounding. + 1. **Enable BedrockFullAccess on your IAM role** : If your role has BedrockFullAccess, it will have automatic access to Web Grounding. @@ -158 +168 @@ The model generated invalid output. This is typically a transient error - retry - 2. **Add Specific Permissions (if needed)** \- If you require more granular access control, add this policy to your role's IAM policy, replacing the account ID with your AWS account ID: + 2. **Add Specific Permissions (if needed)** : If you require more granular access control, add this policy to your role's IAM policy, replacing the account ID with your AWS account ID: @@ -174 +184 @@ The model generated invalid output. This is typically a transient error - retry -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. +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. @@ -182 +192 @@ If you enable the Web Grounding tool, you are responsible for your use, and any -Web Grounding is an additional cost. For more information see [Amazon Bedrock pricing page](https://aws.amazon.com/bedrock/pricing/). +Web Grounding is an additional cost. For more information, go to [AWS Bedrock pricing](https://aws.amazon.com/bedrock/pricing/).