Add Google Search grounding toggle to Gemini nodes

Enable Google Search as a built-in tool on all Gemini text generation
and agent nodes via a hidden boolean toggle. When enabled, responses
are grounded in current web results. Grounding metadata (search queries,
sources, citations) is exposed as a new hidden output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bchapuis

apps/api/src/durable-objects/agent-runner.ts

@@ -65,6 +65,8 @@ export interface AgentRunRequest {
   tools: ToolReference[];
   /** Enable code mode for multi-tool orchestration */
   codeMode?: boolean;
+  /** Enable Google Search grounding (Gemini only) */
+  googleSearch?: boolean;
   /** Organization ID for credential access (integrations, secrets) */
   organizationId: string;
 }
@@ -194,6 +196,9 @@ export class AgentRunner extends DurableObject<Bindings> {
         ? `Context:\n${body.context}\n\nRequest:\n${body.input}`
         : body.input;
 
+      // Build built-in Gemini tools (only effective for google provider)
+      const geminiBuiltInTools = this.buildGeminiBuiltInTools(body);
+
       // Run the agent loop
       const result = await runAgentLoop({
         userMessage,
@@ -205,7 +210,8 @@ export class AgentRunner extends DurableObject<Bindings> {
             body.model,
             body.instructions,
             messages,
-            tools
+            tools,
+            geminiBuiltInTools
           ),
         onStepComplete: async (state) => {
           this.ctx.storage.sql.exec(
@@ -342,6 +348,8 @@ export class AgentRunner extends DurableObject<Bindings> {
         ? `Context:\n${body.context}\n\nRequest:\n${body.input}`
         : body.input;
 
+      const geminiBuiltInTools = this.buildGeminiBuiltInTools(body);
+
       const result = await runAgentLoop({
         userMessage,
         tools: toolDefinitions,
@@ -352,7 +360,8 @@ export class AgentRunner extends DurableObject<Bindings> {
             body.model,
             body.instructions,
             messages,
-            tools
+            tools,
+            geminiBuiltInTools
           ),
         onStepComplete: async (state) => {
           this.ctx.storage.sql.exec(
@@ -453,6 +462,16 @@ export class AgentRunner extends DurableObject<Bindings> {
     });
   }
 
+  // ── Built-in Gemini tools ─────────────────────────────────────────────
+
+  private buildGeminiBuiltInTools(
+    body: AgentRunRequest
+  ): Record<string, unknown>[] {
+    const tools: Record<string, unknown>[] = [];
+    if (body.googleSearch) tools.push({ googleSearch: {} });
+    return tools;
+  }
+
   // ── Code Mode wrapping ─────────────────────────────────────────────────
 
   /**
@@ -507,13 +526,20 @@ export class AgentRunner extends DurableObject<Bindings> {
     model: string,
     instructions: string,
     messages: AgentMessage[],
-    tools: ToolDefinition[]
+    tools: ToolDefinition[],
+    builtInTools?: Record<string, unknown>[]
   ): Promise<LLMResponse> {
     switch (provider) {
       case "anthropic":
         return this.callAnthropic(model, instructions, messages, tools);
       case "google":
-        return this.callGoogle(model, instructions, messages, tools);
+        return this.callGoogle(
+          model,
+          instructions,
+          messages,
+          tools,
+          builtInTools
+        );
       case "openai":
         return this.callOpenAI(model, instructions, messages, tools);
       case "workers-ai":
@@ -616,7 +642,8 @@ export class AgentRunner extends DurableObject<Bindings> {
     model: string,
     instructions: string,
     messages: AgentMessage[],
-    tools: ToolDefinition[]
+    tools: ToolDefinition[],
+    builtInTools?: Record<string, unknown>[]
   ): Promise<LLMResponse> {
     const ai = new GoogleGenAI({
       apiKey: "gateway-managed",
@@ -668,8 +695,12 @@ export class AgentRunner extends DurableObject<Bindings> {
     }));
 
     const config: Record<string, unknown> = {};
+    const allTools: Record<string, unknown>[] = [...(builtInTools ?? [])];
     if (functionDeclarations.length > 0) {
-      config.tools = [{ functionDeclarations }];
+      allTools.push({ functionDeclarations });
+    }
+    if (allTools.length > 0) {
+      config.tools = allTools;
     }
 
     const response = await ai.models.generateContent({

packages/runtime/src/nodes/agent/agent-gemini-2-5-flash-node.ts

@@ -1,6 +1,10 @@
 import type { NodeType } from "@dafthunk/types";
 
-import { BaseAgentNode, buildAgentNodeType } from "./base-agent-node";
+import {
+  BaseAgentNode,
+  buildAgentNodeType,
+  GEMINI_BUILTIN_TOOL_INPUTS,
+} from "./base-agent-node";
 
 export class AgentGemini25FlashNode extends BaseAgentNode {
   // https://ai.google.dev/pricing
@@ -18,5 +22,6 @@ export class AgentGemini25FlashNode extends BaseAgentNode {
     tags: ["AI", "Agent", "Google", "Gemini"],
     documentation:
       "This node runs a multi-turn agent loop using Gemini 2.5 Flash. The agent calls the LLM, executes tool calls, and iterates until the task is complete or the step limit is reached.",
+    extraInputs: GEMINI_BUILTIN_TOOL_INPUTS,
   });
 }

packages/runtime/src/nodes/agent/agent-gemini-3-1-pro-node.ts

@@ -1,6 +1,10 @@
 import type { NodeType } from "@dafthunk/types";
 
-import { BaseAgentNode, buildAgentNodeType } from "./base-agent-node";
+import {
+  BaseAgentNode,
+  buildAgentNodeType,
+  GEMINI_BUILTIN_TOOL_INPUTS,
+} from "./base-agent-node";
 
 export class AgentGemini31ProNode extends BaseAgentNode {
   // https://ai.google.dev/pricing
@@ -18,5 +22,6 @@ export class AgentGemini31ProNode extends BaseAgentNode {
     tags: ["AI", "Agent", "Google", "Gemini"],
     documentation:
       "This node runs a multi-turn agent loop using Gemini 3.1 Pro. The agent calls the LLM, executes tool calls, and iterates until the task is complete or the step limit is reached.",
+    extraInputs: GEMINI_BUILTIN_TOOL_INPUTS,
   });
 }

packages/runtime/src/nodes/agent/agent-gemini-3-flash-node.ts

@@ -1,6 +1,10 @@
 import type { NodeType } from "@dafthunk/types";
 
-import { BaseAgentNode, buildAgentNodeType } from "./base-agent-node";
+import {
+  BaseAgentNode,
+  buildAgentNodeType,
+  GEMINI_BUILTIN_TOOL_INPUTS,
+} from "./base-agent-node";
 
 export class AgentGemini3FlashNode extends BaseAgentNode {
   // https://ai.google.dev/pricing
@@ -18,5 +22,6 @@ export class AgentGemini3FlashNode extends BaseAgentNode {
     tags: ["AI", "Agent", "Google", "Gemini"],
     documentation:
       "This node runs a multi-turn agent loop using Gemini 3 Flash. The agent calls the LLM, executes tool calls, and iterates until the task is complete or the step limit is reached.",
+    extraInputs: GEMINI_BUILTIN_TOOL_INPUTS,
   });
 }

packages/runtime/src/nodes/agent/base-agent-node.ts

@@ -63,6 +63,18 @@ const AGENT_INPUTS: NodeType["inputs"] = [
   },
 ];
 
+/** Extra inputs for Gemini agent nodes — Google built-in tools */
+export const GEMINI_BUILTIN_TOOL_INPUTS: NodeType["inputs"] = [
+  {
+    name: "googleSearch",
+    type: "boolean",
+    description:
+      "Enable Google Search to ground responses in current web results",
+    required: false,
+    hidden: true,
+  },
+];
+
 /** Standard outputs shared by all agent nodes */
 const AGENT_OUTPUTS: NodeType["outputs"] = [
   {
@@ -106,6 +118,7 @@ export function buildAgentNodeType(meta: {
   description: string;
   tags: string[];
   documentation: string;
+  extraInputs?: NodeType["inputs"];
 }): NodeType {
   return {
     id: meta.id,
@@ -117,7 +130,7 @@ export function buildAgentNodeType(meta: {
     documentation: meta.documentation,
     usage: 1,
     functionCalling: true,
-    inputs: AGENT_INPUTS,
+    inputs: [...AGENT_INPUTS, ...(meta.extraInputs ?? [])],
     outputs: AGENT_OUTPUTS,
   };
 }
@@ -179,7 +192,7 @@ export abstract class BaseAgentNode extends ExecutableNode {
     config: AgentNodeConfig
   ): Promise<NodeExecution> {
     try {
-      const { instructions, input, max_steps, tools, code_mode } =
+      const { instructions, input, max_steps, tools, code_mode, googleSearch } =
         context.inputs;
       const agentContext = context.inputs.context as string | undefined;
 
@@ -212,6 +225,7 @@ export abstract class BaseAgentNode extends ExecutableNode {
           maxSteps: max_steps ?? 10,
           tools: tools ?? [],
           codeMode: code_mode ?? false,
+          googleSearch: googleSearch ?? false,
           organizationId: context.organizationId,
         }),
       });
@@ -253,7 +267,7 @@ export abstract class BaseAgentNode extends ExecutableNode {
     config: AgentNodeConfig
   ): Promise<NodeExecution> {
     try {
-      const { instructions, input, max_steps, tools, code_mode } =
+      const { instructions, input, max_steps, tools, code_mode, googleSearch } =
         context.inputs;
       const agentContext = context.inputs.context as string | undefined;
 
@@ -283,6 +297,7 @@ export abstract class BaseAgentNode extends ExecutableNode {
           maxSteps: max_steps ?? 10,
           tools: tools ?? [],
           codeMode: code_mode ?? false,
+          googleSearch: googleSearch ?? false,
           organizationId: context.organizationId,
         }),
       });

packages/runtime/src/nodes/gemini/execute-gemini-model.ts

@@ -40,6 +40,7 @@ export async function executeGeminiModel(
       maxOutputTokens,
       thinking_budget,
       tools,
+      googleSearch,
     } = context.inputs;
 
     if (!input) {
@@ -69,13 +70,25 @@ export async function executeGeminiModel(
         context
       );
 
+    // Build built-in tools array
+    const builtInTools: Record<string, unknown>[] = [];
+    if (googleSearch) builtInTools.push({ googleSearch: {} });
+
     let response: any;
     const executedToolCalls: any[] = [];
     let intermediaryMessages: any[] = [];
 
+    // Merge function declarations with built-in tools
+    const allTools: Record<string, unknown>[] = [...builtInTools];
     if (functionDeclarations.length > 0) {
-      genConfig.tools = [{ functionDeclarations }];
+      allTools.push({ functionDeclarations });
+    }
 
+    if (allTools.length > 0) {
+      genConfig.tools = allTools;
+    }
+
+    if (functionDeclarations.length > 0) {
       response = await ai.models.generateContent({
         model: config.modelId,
         contents: [{ text: input }],
@@ -152,6 +165,7 @@ export async function executeGeminiModel(
     const usageMetadata = response.usageMetadata;
     const promptFeedback = response.promptFeedback;
     const finishReason = candidate?.finishReason;
+    const groundingMetadata = candidate?.groundingMetadata;
 
     const usage = calculateTokenUsage(
       usageMetadata?.promptTokenCount ?? 0,
@@ -166,6 +180,7 @@ export async function executeGeminiModel(
         ...(usageMetadata && { usage_metadata: usageMetadata }),
         ...(promptFeedback && { prompt_feedback: promptFeedback }),
         ...(finishReason && { finish_reason: finishReason }),
+        ...(groundingMetadata && { grounding_metadata: groundingMetadata }),
         ...(executedToolCalls.length > 0
           ? { tool_calls: executedToolCalls }
           : {}),

packages/runtime/src/nodes/gemini/gemini-2-5-flash-node.ts

@@ -66,6 +66,14 @@ export class Gemini25FlashNode extends ExecutableNode {
         hidden: true,
         value: [] as any,
       },
+      {
+        name: "googleSearch",
+        type: "boolean",
+        description:
+          "Enable Google Search to ground responses in current web results",
+        required: false,
+        hidden: true,
+      },
     ],
     outputs: [
       {
@@ -98,6 +106,13 @@ export class Gemini25FlashNode extends ExecutableNode {
           "Reason why the generation finished (STOP, MAX_TOKENS, etc.)",
         hidden: true,
       },
+      {
+        name: "grounding_metadata",
+        type: "json",
+        description:
+          "Grounding metadata with search queries, sources, and citations from Google Search or Maps",
+        hidden: true,
+      },
       {
         name: "tool_calls",
         type: "json",

packages/runtime/src/nodes/gemini/gemini-2-5-pro-node.ts

@@ -66,6 +66,14 @@ export class Gemini25ProNode extends ExecutableNode {
         hidden: true,
         value: [] as any,
       },
+      {
+        name: "googleSearch",
+        type: "boolean",
+        description:
+          "Enable Google Search to ground responses in current web results",
+        required: false,
+        hidden: true,
+      },
     ],
     outputs: [
       {
@@ -98,6 +106,13 @@ export class Gemini25ProNode extends ExecutableNode {
           "Reason why the generation finished (STOP, MAX_TOKENS, etc.)",
         hidden: true,
       },
+      {
+        name: "grounding_metadata",
+        type: "json",
+        description:
+          "Grounding metadata with search queries, sources, and citations from Google Search or Maps",
+        hidden: true,
+      },
       {
         name: "tool_calls",
         type: "json",

packages/runtime/src/nodes/gemini/gemini-3-1-pro-node.ts

@@ -66,6 +66,14 @@ export class Gemini31ProNode extends ExecutableNode {
         hidden: true,
         value: [] as any,
       },
+      {
+        name: "googleSearch",
+        type: "boolean",
+        description:
+          "Enable Google Search to ground responses in current web results",
+        required: false,
+        hidden: true,
+      },
     ],
     outputs: [
       {
@@ -98,6 +106,13 @@ export class Gemini31ProNode extends ExecutableNode {
           "Reason why the generation finished (STOP, MAX_TOKENS, etc.)",
         hidden: true,
       },
+      {
+        name: "grounding_metadata",
+        type: "json",
+        description:
+          "Grounding metadata with search queries, sources, and citations from Google Search or Maps",
+        hidden: true,
+      },
       {
         name: "tool_calls",
         type: "json",