feat(js/plugins/google-genai): Support urlContext for googleAI Gemini (#3822)

Author: ifielker

js/plugins/google-genai/src/common/types.ts

@@ -153,6 +153,10 @@ export function isGoogleSearchRetrievalTool(
   );
 }
 
+export declare interface UrlContextTool {
+  urlContext?: {};
+}
+
 /**
  * The FileSearch tool that retrieves knowledge from Semantic Retrieval corpora.
  * Files are imported to Semantic Retrieval corpora using the ImportFile API
@@ -935,6 +939,7 @@ export declare type Tool =
   | GoogleMapsTool // Vertex AI Only
   | CodeExecutionTool // Google AI Only
   | FileSearchTool // Google AI Only
+  | UrlContextTool // Google AI Only
   | GoogleSearchRetrievalTool;
 
 /**

js/plugins/google-genai/src/googleai/gemini.ts

@@ -52,6 +52,7 @@ import {
   SafetySetting,
   Tool,
   ToolConfig,
+  UrlContextTool,
 } from './types.js';
 import {
   calculateApiKey,
@@ -221,6 +222,10 @@ export const GeminiConfigSchema = GenerationCommonConfigSchema.extend({
     })
     .passthrough()
     .optional(),
+  urlContext: z
+    .union([z.boolean(), z.object({}).passthrough()])
+    .describe('Return grounding metadata from links included in the query')
+    .optional(),
   temperature: z
     .number()
     .min(0)
@@ -567,6 +572,7 @@ export function defineModel(
         functionCallingConfig,
         googleSearchRetrieval,
         fileSearch,
+        urlContext,
         tools: toolsFromConfig,
         ...restOfConfigOptions
       } = requestOptions;
@@ -595,6 +601,12 @@ export function defineModel(
         });
       }
 
+      if (urlContext) {
+        tools.push({
+          urlContext: urlContext === true ? {} : urlContext,
+        } as UrlContextTool);
+      }
+
       let toolConfig: ToolConfig | undefined;
       if (functionCallingConfig) {
         toolConfig = {

js/plugins/google-genai/src/googleai/types.ts

@@ -36,6 +36,7 @@ import {
   TaskTypeSchema,
   Tool,
   ToolConfig,
+  UrlContextTool,
 } from '../common/types.js';
 
 // This makes it easier to import all types from one place.
@@ -60,6 +61,7 @@ export {
   type SafetySetting,
   type Tool,
   type ToolConfig,
+  type UrlContextTool,
 };
 
 export interface GoogleAIPluginOptions {

js/plugins/google-genai/tests/googleai/gemini_test.ts

@@ -282,6 +282,7 @@ describe('Google AI Gemini', () => {
             fileSearch: {
               fileSearchStoreNames: ['foo'],
             },
+            urlContext: {},
           },
         };
         await model.run(request);
@@ -290,7 +291,7 @@ describe('Google AI Gemini', () => {
           fetchStub.lastCall.args[1].body
         );
         assert.ok(Array.isArray(apiRequest.tools));
-        assert.strictEqual(apiRequest.tools?.length, 4);
+        assert.strictEqual(apiRequest.tools?.length, 5);
         assert.deepStrictEqual(apiRequest.tools?.[1], { codeExecution: {} });
         assert.deepStrictEqual(apiRequest.tools?.[2], {
           googleSearch: {},
@@ -300,6 +301,9 @@ describe('Google AI Gemini', () => {
             fileSearchStoreNames: ['foo'],
           },
         });
+        assert.deepStrictEqual(apiRequest.tools?.[4], {
+          urlContext: {},
+        });
       });
 
       it('uses baseUrl and apiVersion from call config', async () => {

js/testapps/basic-gemini/src/index.ts

@@ -178,6 +178,25 @@ ai.defineFlow('search-grounding', async () => {
   };
 });
 
+// Url context
+ai.defineFlow('url-context', async () => {
+  const { text, raw } = await ai.generate({
+    model: googleAI.model('gemini-2.5-flash'),
+    prompt:
+      'Compare the ingredients and cooking times from the recipes at ' +
+      'https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 ' +
+      'and https://www.allrecipes.com/recipe/70679/simple-whole-roasted-chicken/',
+    config: {
+      urlContext: {},
+    },
+  });
+
+  return {
+    text,
+    groundingMetadata: (raw as any)?.candidates[0]?.groundingMetadata,
+  };
+});
+
 // File Search
 ai.defineFlow('file-search', async () => {
   // Use the google/genai SDK to upload the story BLOB to a new