feat(google): Adding new Google File search tool (#10051)

## Background

Google [released](https://x.com/_philschmid/status/1986506204240347520)
on the 6th of November then file search tool.

- [Documentation](https://ai.google.dev/gemini-api/docs/file-search)
- [Blog
post](https://blog.google/technology/developers/file-search-gemini-api/)


(Wasn't initially sure if this was pertinent but this the @ai-sdk/openai
already has a [tool for file
search](https://ai-sdk.dev/providers/ai-sdk-providers/openai#file-search-tool),
i decided to propose this PR)

## Summary

Add support for Gemini File Search so SDK users can ground Gemini 2.5
models on their own indexed documents.

## Manual Verification

Use the official `@google/genai` SDK only for the parts where you can
create a file search store and upload file to it.

```ts
import { GoogleGenAI } from "@google/genai";

const GEMINI_API_KEY = process.env.GEMINI_API_KEY;

const client = new GoogleGenAI({ vertexai: false, apiKey: GEMINI_API_KEY });

const fileSearchStore = await client.fileSearchStores.create({
  config: { displayName: "test_file_search_store" },
});
console.log(fileSearchStore);

let operation = await client.fileSearchStores.uploadToFileSearchStore({
  fileSearchStoreName: fileSearchStore.name!,
  file: "./README.md",
  config: {
    mimeType: "text/markdown",
  },
});

console.log(operation);

while (operation.done !== true) {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  operation = await client.operations.get({ operation: operation });
}
```

Then run this file 

```ts
import { google } from '@ai-sdk/google';
import { generateText } from 'ai';
import 'dotenv/config';

async function main() {
  const { text, sources, providerMetadata } = await generateText({
    model: google('gemini-2.5-pro'),
    tools: {
      file_search: google.tools.fileSearch({
        fileSearchStoreNames: [
          'fileSearchStores/testfilesearchstore-itgm4cn4ie11',
        ],
        // metadataFilter: 'author = "Robert Graves"',
        // topK: 8,
      }),
    },
    prompt: 'Tell me more about the project readme.',
  });
  console.log(text);
  console.log(sources);
  console.dir(providerMetadata, { depth: null });
}

main().catch(console.error);

```

---------

Co-authored-by: Gregor Martynus <[email protected]>

Author: titouv

.changeset/shy-emus-relax.md

@@ -0,0 +1,6 @@
+---
+'@ai-sdk/google': patch
+'@ai-sdk/google-vertex': patch
+---
+
+Add Google File search tool

content/providers/01-ai-sdk-providers/15-google-generative-ai.mdx

@@ -489,6 +489,31 @@ Example response:
 }
 ```
 
+### File Search
+
+The [File Search tool](https://ai.google.dev/gemini-api/docs/file-search) lets Gemini retrieve context from your own documents that you have indexed in File Search stores. Only Gemini 2.5 models support this feature.
+
+```ts highlight="9-13"
+import { google } from '@ai-sdk/google';
+import { generateText } from 'ai';
+
+const { text, sources } = await generateText({
+  model: google('gemini-2.5-pro'),
+  tools: {
+    file_search: google.tools.fileSearch({
+      fileSearchStoreNames: [
+        'projects/my-project/locations/us/fileSearchStores/my-store',
+      ],
+      metadataFilter: 'author = "Robert Graves"',
+      topK: 8,
+    }),
+  },
+  prompt: "Summarise the key themes of 'I, Claudius'.",
+});
+```
+
+File Search responses include citations via the normal `sources` field and expose raw [grounding metadata](#google-search) in `providerMetadata.google.groundingMetadata`.
+
 ### URL Context
 
 Google provides a provider-defined URL context tool.

packages/google-vertex/src/google-vertex-provider.test.ts

@@ -16,6 +16,7 @@ vi.mock('@ai-sdk/google/internal', () => ({
   googleTools: {
     googleSearch: vi.fn(),
     urlContext: vi.fn(),
+    fileSearch: vi.fn(),
     codeExecution: vi.fn(),
   },
 }));

packages/google-vertex/src/google-vertex-tools.ts

@@ -3,5 +3,6 @@ import { googleTools } from '@ai-sdk/google/internal';
 export const googleVertexTools = {
   googleSearch: googleTools.googleSearch,
   urlContext: googleTools.urlContext,
+  fileSearch: googleTools.fileSearch,
   codeExecution: googleTools.codeExecution,
 };

packages/google/src/google-generative-ai-language-model.ts

@@ -709,9 +709,15 @@ export const getGroundingMetadataSchema = () =>
           web: z
             .object({ uri: z.string(), title: z.string().nullish() })
             .nullish(),
-          retrievedContext: z
-            .object({ uri: z.string(), title: z.string().nullish() })
-            .nullish(),
+          retrievedContext: z.union([
+            z
+              .object({ uri: z.string(), title: z.string().nullish() })
+              .nullish(),
+            z.object({
+              title: z.string().nullish(),
+              text: z.string().nullish(),
+            }),
+          ]),
         }),
       )
       .nullish(),

packages/google/src/google-prepare-tools.test.ts

@@ -1,5 +1,6 @@
 import { expect, it } from 'vitest';
 import { prepareTools } from './google-prepare-tools';
+import { LanguageModelV3ProviderDefinedTool } from '@ai-sdk/provider';
 
 it('should return undefined tools and tool_choice when tools are null', () => {
   const result = prepareTools({
@@ -62,10 +63,24 @@ it('should correctly prepare provider-defined tools as array', () => {
         name: 'url_context',
         args: {},
       },
+      {
+        type: 'provider-defined',
+        id: 'google.file_search',
+        name: 'file_search',
+        args: { fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'] },
+      },
     ],
     modelId: 'gemini-2.5-flash',
   });
-  expect(result.tools).toEqual([{ googleSearch: {} }, { urlContext: {} }]);
+  expect(result.tools).toEqual([
+    { googleSearch: {} },
+    { urlContext: {} },
+    {
+      fileSearch: {
+        fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'],
+      },
+    },
+  ]);
   expect(result.toolConfig).toBeUndefined();
   expect(result.toolWarnings).toEqual([]);
 });
@@ -116,6 +131,69 @@ it('should add warnings for unsupported tools', () => {
   `);
 });
 
+it('should add warnings for file search on unsupported models', () => {
+  const tool: LanguageModelV3ProviderDefinedTool = {
+    type: 'provider-defined' as const,
+    id: 'google.file_search',
+    name: 'file_search',
+    args: { fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'] },
+  };
+
+  const result = prepareTools({
+    tools: [tool],
+    modelId: 'gemini-1.5-flash-8b',
+  });
+
+  expect(result.tools).toBeUndefined();
+  expect(result.toolWarnings).toMatchInlineSnapshot(`
+    [
+      {
+        "details": "The file search tool is only supported with Gemini 2.5 models.",
+        "tool": {
+          "args": {
+            "fileSearchStoreNames": [
+              "projects/foo/fileSearchStores/bar",
+            ],
+          },
+          "id": "google.file_search",
+          "name": "file_search",
+          "type": "provider-defined",
+        },
+        "type": "unsupported-tool",
+      },
+    ]
+  `);
+});
+
+it('should correctly prepare file search tool', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider-defined',
+        id: 'google.file_search',
+        name: 'file_search',
+        args: {
+          fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'],
+          metadataFilter: 'author=Robert Graves',
+          topK: 5,
+        },
+      },
+    ],
+    modelId: 'gemini-2.5-pro',
+  });
+
+  expect(result.tools).toEqual([
+    {
+      fileSearch: {
+        fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'],
+        metadataFilter: 'author=Robert Graves',
+        topK: 5,
+      },
+    },
+  ]);
+  expect(result.toolWarnings).toEqual([]);
+});
+
 it('should handle tool choice "auto"', () => {
   const result = prepareTools({
     tools: [

packages/google/src/google-prepare-tools.ts

@@ -50,6 +50,7 @@ export function prepareTools({
   const isGemini2 = modelId.includes('gemini-2') || isLatest;
   const supportsDynamicRetrieval =
     modelId.includes('gemini-1.5-flash') && !modelId.includes('-8b');
+  const supportsFileSearch = modelId.includes('gemini-2.5');
 
   if (tools == null) {
     return { tools: undefined, toolConfig: undefined, toolWarnings };
@@ -124,6 +125,18 @@ export function prepareTools({
             });
           }
           break;
+        case 'google.file_search':
+          if (supportsFileSearch) {
+            googleTools.push({ fileSearch: { ...tool.args } });
+          } else {
+            toolWarnings.push({
+              type: 'unsupported-tool',
+              tool,
+              details:
+                'The file search tool is only supported with Gemini 2.5 models.',
+            });
+          }
+          break;
         default:
           toolWarnings.push({ type: 'unsupported-tool', tool });
           break;

packages/google/src/google-tools.ts

@@ -1,4 +1,5 @@
 import { codeExecution } from './tool/code-execution';
+import { fileSearch } from './tool/file-search';
 import { googleSearch } from './tool/google-search';
 import { urlContext } from './tool/url-context';
 
@@ -14,6 +15,17 @@ export const googleTools = {
    * Must have name "url_context".
    */
   urlContext,
+  /**
+   * Enables Retrieval Augmented Generation (RAG) via the Gemini File Search tool.
+   * Must have name "file_search".
+   *
+   * @param fileSearchStoreNames - Fully-qualified File Search store resource names.
+   * @param metadataFilter - Optional filter expression to restrict the files that can be retrieved.
+   * @param topK - Optional result limit for the number of chunks returned from File Search.
+   *
+   * @see https://ai.google.dev/gemini-api/docs/file-search
+   */
+  fileSearch,
   /**
    * A tool that enables the model to generate and run Python code.
    * Must have name "code_execution".

packages/google/src/tool/file-search.ts

@@ -0,0 +1,52 @@
+import {
+  createProviderDefinedToolFactory,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+/** Tool to retrieve knowledge from the File Search Stores. */
+const fileSearchArgsBaseSchema = z
+  .object({
+    /** The names of the file_search_stores to retrieve from.
+     *  Example: `fileSearchStores/my-file-search-store-123`
+     */
+    fileSearchStoreNames: z
+      .array(z.string())
+      .describe(
+        'The names of the file_search_stores to retrieve from. Example: `fileSearchStores/my-file-search-store-123`',
+      ),
+    /** The number of file search retrieval chunks to retrieve. */
+    topK: z
+      .number()
+      .int()
+      .positive()
+      .describe('The number of file search retrieval chunks to retrieve.')
+      .optional(),
+
+    /** Metadata filter to apply to the file search retrieval documents.
+     *  See https://google.aip.dev/160 for the syntax of the filter expression.
+     */
+    metadataFilter: z
+      .string()
+      .describe(
+        'Metadata filter to apply to the file search retrieval documents. See https://google.aip.dev/160 for the syntax of the filter expression.',
+      )
+      .optional(),
+  })
+  .passthrough();
+
+export type GoogleFileSearchToolArgs = z.infer<typeof fileSearchArgsBaseSchema>;
+
+const fileSearchArgsSchema = lazySchema(() =>
+  zodSchema(fileSearchArgsBaseSchema),
+);
+
+export const fileSearch = createProviderDefinedToolFactory<
+  {},
+  GoogleFileSearchToolArgs
+>({
+  id: 'google.file_search',
+  name: 'file_search',
+  inputSchema: fileSearchArgsSchema,
+});