feat(amazon-bedrock): add Nova Web Grounding support

.changeset/fifty-beds-smell.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/amazon-bedrock': patch
+---
+
+Add Nova Web Grounding support for Amazon Bedrock

content/providers/01-ai-sdk-providers/08-amazon-bedrock.mdx

@@ -600,6 +600,59 @@ Parameters:
 
 These tools can be used in conjunction with the `anthropic.claude-3-5-sonnet-20240620-v1:0` model to enable more complex interactions and tasks.
 
+## Nova Web Grounding
+
+Amazon Nova models support Web Grounding, a built-in tool that provides real-time web search capabilities. Web Grounding is a turnkey Retrieval Augmented Generation (RAG) option that allows Nova models to intelligently decide when to retrieve and incorporate relevant up-to-date information based on the context of the prompt.
+
+### When to Use Web Grounding
+
+Web Grounding is particularly useful for:
+
+- Applications requiring access to current, factual information
+- Responses that need well-cited sources
+- Knowledge-based chat assistants providing up-to-date information
+- Content generation tools requiring fact-checking and source verification
+- Research assistants synthesizing information from multiple current sources
+- Customer support applications where accuracy and verifiability are crucial
+
+### Using Web Grounding
+
+Web Grounding is available via the `tools` property of the provider instance:
+
+```ts
+import { bedrock } from '@ai-sdk/amazon-bedrock';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: bedrock('us.amazon.nova-premier-v1:0'),
+  prompt: 'What are the current AWS Regions and their locations?',
+  tools: {
+    nova_grounding: bedrock.tools.nova_grounding(),
+  },
+});
+
+console.log(result.text);
+```
+
+When Web Grounding is enabled, the model will automatically:
+
+1. Determine when external information is needed based on the prompt
+2. Search for relevant, up-to-date information from the web
+3. Incorporate the retrieved information into its response
+4. Provide source citations for the information used
+
+### Availability
+
+- **Regions**: US East (N. Virginia), with US East (Ohio) and US West (Oregon) coming soon
+- **Models**: Currently available for Nova Premier, with support for other Nova models coming soon
+- **Pricing**: Web Grounding incurs additional costs. See the [Amazon Bedrock pricing page](https://aws.amazon.com/bedrock/pricing/) for details
+
+<Note>
+  Web Grounding represents a significant step forward in making AI applications
+  more reliable and current with minimum effort, eliminating the need to build
+  and maintain complex RAG pipelines.
+</Note>
+
 ### Model Capabilities
 
 | Model                                          | Image Input         | Object Generation   | Tool Usage          | Tool Streaming      |

packages/amazon-bedrock/src/bedrock-api-types.ts

@@ -63,8 +63,14 @@ export interface BedrockTool {
   };
 }
 
+export interface BedrockSystemTool {
+  systemTool: {
+    name: string;
+  };
+}
+
 export interface BedrockToolConfiguration {
-  tools?: Array<BedrockTool | BedrockCachePoint>;
+  tools?: Array<BedrockTool | BedrockSystemTool | BedrockCachePoint>;
   toolChoice?:
     | { tool: { name: string } }
     | { auto: {} }

packages/amazon-bedrock/src/bedrock-nova-tools.ts

@@ -0,0 +1,38 @@
+import { LanguageModelV3ProviderDefinedTool } from '@ai-sdk/provider';
+
+/**
+ * Nova-specific tools that can be used with Nova models on Amazon Bedrock.
+ * These are system tools that are executed by the Bedrock service.
+ */
+export const novaTools = {
+  /**
+   * Nova Web Grounding tool for real-time web search and information retrieval.
+   * This is a system tool that is executed by the Bedrock service.
+   *
+   * Web Grounding provides a turnkey RAG option that allows Nova models to
+   * intelligently decide when to retrieve and incorporate relevant up-to-date
+   * information based on the context of the prompt.
+   *
+   * @example
+   * ```typescript
+   * import { bedrock } from '@ai-sdk/amazon-bedrock';
+   * import { generateText } from 'ai';
+   *
+   * const result = await generateText({
+   *   model: bedrock('us.amazon.nova-premier-v1:0'),
+   *   prompt: 'What are the current AWS Regions and their locations?',
+   *   tools: {
+   *     nova_grounding: bedrock.tools.nova_grounding(),
+   *   },
+   * });
+   * ```
+   */
+  nova_grounding: (
+    args: Record<string, unknown> = {},
+  ): LanguageModelV3ProviderDefinedTool => ({
+    type: 'provider-defined' as const,
+    id: 'nova.nova_grounding',
+    name: 'nova_grounding',
+    args,
+  }),
+};

packages/amazon-bedrock/src/bedrock-prepare-tools.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest';
+import { prepareTools } from './bedrock-prepare-tools';
+
+describe('prepareTools', () => {
+  it('should return empty toolConfig when tools are null', async () => {
+    const result = await prepareTools({
+      tools: undefined,
+      modelId: 'us.amazon.nova-premier-v1:0',
+    });
+    expect(result).toEqual({
+      toolConfig: {},
+      additionalTools: undefined,
+      toolWarnings: [],
+      betas: new Set(),
+    });
+  });
+
+  it('should return empty toolConfig when tools are empty', async () => {
+    const result = await prepareTools({
+      tools: [],
+      modelId: 'us.amazon.nova-premier-v1:0',
+    });
+    expect(result).toEqual({
+      toolConfig: {},
+      additionalTools: undefined,
+      toolWarnings: [],
+      betas: new Set(),
+    });
+  });
+
+  it('should correctly prepare function tools', async () => {
+    const result = await prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'A test function',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+      modelId: 'us.amazon.nova-premier-v1:0',
+    });
+
+    expect(result.toolConfig.tools).toEqual([
+      {
+        toolSpec: {
+          name: 'testFunction',
+          description: 'A test function',
+          inputSchema: {
+            json: { type: 'object', properties: {} },
+          },
+        },
+      },
+    ]);
+    expect(result.toolWarnings).toEqual([]);
+  });
+
+  describe('Nova provider-defined tools', () => {
+    it('should correctly prepare nova_grounding tool', async () => {
+      const result = await prepareTools({
+        tools: [
+          {
+            type: 'provider-defined',
+            id: 'nova.nova_grounding',
+            name: 'nova_grounding',
+            args: {},
+          },
+        ],
+        modelId: 'us.amazon.nova-premier-v1:0',
+      });
+
+      expect(result.toolConfig.tools).toEqual([
+        {
+          systemTool: {
+            name: 'nova_grounding',
+          },
+        },
+      ]);
+      expect(result.toolWarnings).toEqual([]);
+      expect(result.betas.size).toBe(0);
+    });
+
+    it('should warn when mixing Nova tools with function tools', async () => {
+      const result = await prepareTools({
+        tools: [
+          {
+            type: 'provider-defined',
+            id: 'nova.nova_grounding',
+            name: 'nova_grounding',
+            args: {},
+          },
+          {
+            type: 'function',
+            name: 'testFunction',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ],
+        modelId: 'us.amazon.nova-premier-v1:0',
+      });
+
+      expect(result.toolWarnings).toContainEqual({
+        type: 'unsupported-setting',
+        setting: 'tools',
+        details:
+          'Mixed Nova provider-defined tools and standard function tools are not supported in a single call to Bedrock. Only Nova tools will be used.',
+      });
+    });
+
+    it('should not use Nova tools with non-Nova models', async () => {
+      const result = await prepareTools({
+        tools: [
+          {
+            type: 'provider-defined',
+            id: 'nova.nova_grounding',
+            name: 'nova_grounding',
+            args: {},
+          },
+        ],
+        modelId: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
+      });
+
+      expect(result.toolConfig.tools).toBeUndefined();
+      expect(result.toolWarnings).toContainEqual({
+        type: 'unsupported-tool',
+        tool: {
+          type: 'provider-defined',
+          id: 'nova.nova_grounding',
+          name: 'nova_grounding',
+          args: {},
+        },
+      });
+    });
+  });
+
+  describe('Anthropic web_search tool filtering', () => {
+    it('should filter out web_search_20250305 and add warning', async () => {
+      const result = await prepareTools({
+        tools: [
+          {
+            type: 'provider-defined',
+            id: 'anthropic.web_search_20250305',
+            name: 'web_search',
+            args: {},
+          },
+        ],
+        modelId: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
+      });
+
+      expect(result.toolConfig.tools).toBeUndefined();
+      expect(result.toolWarnings).toContainEqual({
+        type: 'unsupported-tool',
+        tool: {
+          type: 'provider-defined',
+          id: 'anthropic.web_search_20250305',
+          name: 'web_search',
+          args: {},
+        },
+        details:
+          'The web_search_20250305 tool is not supported on Amazon Bedrock.',
+      });
+    });
+  });
+});

packages/amazon-bedrock/src/bedrock-prepare-tools.ts

@@ -9,7 +9,12 @@ import {
   anthropicTools,
   prepareTools as prepareAnthropicTools,
 } from '@ai-sdk/anthropic/internal';
-import { BedrockTool, BedrockToolConfiguration } from './bedrock-api-types';
+import { novaTools } from './bedrock-nova-tools';
+import {
+  BedrockTool,
+  BedrockSystemTool,
+  BedrockToolConfiguration,
+} from './bedrock-api-types';
 
 export async function prepareTools({
   tools,
@@ -62,18 +67,19 @@ export async function prepareTools({
       toolWarnings,
     };
   }
-
+  const isNovaModel = modelId.includes('nova');
   const isAnthropicModel = modelId.includes('anthropic.');
   const providerDefinedTools = supportedTools.filter(
     t => t.type === 'provider-defined',
   );
   const functionTools = supportedTools.filter(t => t.type === 'function');
 
   let additionalTools: Record<string, unknown> | undefined = undefined;
-  const bedrockTools: BedrockTool[] = [];
+  const bedrockTools: Array<BedrockTool | BedrockSystemTool> = [];
 
   const usingAnthropicTools =
     isAnthropicModel && providerDefinedTools.length > 0;
+  const usingNovaTools = isNovaModel && providerDefinedTools.length > 0;
 
   // Handle Anthropic provider-defined tools for Anthropic models on Bedrock
   if (usingAnthropicTools) {
@@ -128,8 +134,38 @@ export async function prepareTools({
         toolWarnings.push({ type: 'unsupported-tool', tool });
       }
     }
+  } else if (usingNovaTools) {
+    // Handle Nova provider-defined tools for Nova models on Bedrock
+    if (functionTools.length > 0) {
+      toolWarnings.push({
+        type: 'unsupported-setting',
+        setting: 'tools',
+        details:
+          'Mixed Nova provider-defined tools and standard function tools are not supported in a single call to Bedrock. Only Nova tools will be used.',
+      });
+    }
+
+    // Process Nova tools and convert to Bedrock system tools
+    for (const tool of providerDefinedTools) {
+      const toolFactory = Object.values(novaTools).find(factory => {
+        const instance = (factory as () => any)();
+        return instance.id === tool.id;
+      });
+
+      if (toolFactory != null) {
+        const toolInstance = (toolFactory as () => any)();
+        // Nova tools are system tools - they use a different format
+        bedrockTools.push({
+          systemTool: {
+            name: toolInstance.name,
+          },
+        });
+      } else {
+        toolWarnings.push({ type: 'unsupported-tool', tool });
+      }
+    }
   } else {
-    // Report unsupported provider-defined tools for non-anthropic models
+    // Report unsupported provider-defined tools for non-anthropic/non-nova models
     for (const tool of providerDefinedTools) {
       toolWarnings.push({ type: 'unsupported-tool', tool });
     }
@@ -148,9 +184,14 @@ export async function prepareTools({
     });
   }
 
-  // Handle toolChoice for standard Bedrock tools, but NOT for Anthropic provider-defined tools
+  // Handle toolChoice for standard Bedrock tools, but NOT for Anthropic/Nova provider-defined tools
   let bedrockToolChoice: BedrockToolConfiguration['toolChoice'] = undefined;
-  if (!usingAnthropicTools && bedrockTools.length > 0 && toolChoice) {
+  if (
+    !usingAnthropicTools &&
+    !usingNovaTools &&
+    bedrockTools.length > 0 &&
+    toolChoice
+  ) {
     const type = toolChoice.type;
     switch (type) {
       case 'auto':