Table of Contents

Configuring Gemini Web Grounding for an Agent

This guide walks through enabling Gemini web grounding on an agent, from reusing the Google API endpoint and a completion Gemini model to adding the tool and testing it in the User Portal.

Overview

The Gemini Web Grounding tool (Platform-Tool-Gemini-Web-Grounding, in the Google tool family) answers questions with a dedicated Gemini completion that uses Google's native grounding. The agent keeps using FoundationaLLMFunctionCallingWorkflow: the routing model calls GeminiWebGrounding, and the tool runs its own Gemini completion and returns text, not an image.

The feature has three configuration layers, the same pattern as Gemini Image Generation:

  1. API Endpoint — Reuse the Google endpoint with service account credentials. No new endpoint type is needed.
  2. AI Model — A Completion model whose deployment supports grounding (for example gemini-2.5-flash or gemini-3.5-flash). Do not use an image generation deployment.
  3. Agent Tool — Gemini Web Grounding on the agent, with the completion model as its Main Model and a Grounding mode.

This is a native plugin, not an MCP server. Perplexity remains the MCP web search option.

Prerequisites

  • Access to the Management Portal with permission to manage API endpoints, AI models, and agents
  • A Google Cloud project with the Gemini (Vertex AI) API enabled
  • Google Search mode: Grounding with Google Search enabled on the project
  • Enterprise mode: Web Grounding for Enterprise entitlement on the project
  • A service account that can call generateContent on the completion model (the image generation service account works if it has that permission), stored as a Key Vault secret and referenced by an App Configuration key

The Context API is not required for this tool.

Grounding Modes

Mode Grounding mode value Gemini tool Use when
Google Search (default) google_search google_search (optional excluded domains) Live public web facts, current events, citations
Web Grounding for Enterprise enterprise_web_search enterprise_web_search Curated enterprise index with no customer-data logging

Exclude domains is a comma-separated list of domains excluded from Google Search grounding. It is ignored in Enterprise mode.

Google recommends temperature=1.0 for Search grounding. The tool applies that value to its own completion.

Note: Gemini 3 bills per generated search query. FoundationaLLM does not add separate metering for this tool.

Step 1: Configure the Google API Endpoint

If you already have a Google endpoint for Gemini image generation (check Platform > API Endpoints), reuse it and skip to Step 2. Otherwise, create one as described in Configuring Gemini Image Generation: Provider Google Agent Platform, Category General, Subcategory AIModel, Authentication type Google Service Account, and a service_account_credentials authentication parameter.

Step 2: Create a Completion Gemini AI Model

  1. In the sidebar, select Agents > Models, and then select Create Model.
  2. Configure the following settings:
Field Value
Display name / Name For example Gemini25Flash or Gemini35Flash
Model Type Completion. Do not use ImageGeneration.
Model Endpoint The Google endpoint from Step 1
Model deployment name A grounding-capable Gemini chat model, for example gemini-2.5-flash or gemini-3.5-flash
Model version Required by the form
  1. Select Create Model.

Tip: Image generation deployments (Nano Banana, gemini-*-flash-image*) are the wrong model family for this tool. If the completion returns no text, the tool fails with a clear error.

Step 3: Add the Tool to an Agent

The agent needs a function-calling workflow.

  1. In the sidebar, select Agents > Agents, and then select the pencil icon for the agent (or select Create Agent).
  2. On the Basic Settings tab, choose a chat Main model for reasoning and tool routing. This is separate from the grounding model.
  3. On the Workflow tab, set Workflow package name to foundationallm_agent_plugins, Workflow class name to FoundationaLLMFunctionCallingWorkflow, and Workflow host to LangChain.
  4. On the Tools tab, select Add Tool.
  5. Expand the Google folder, select Select on Gemini Web Grounding, and then select Add to Agent. The Edit Agent Tool dialog opens with the agent tool name GeminiWebGrounding.
  6. Under Resource References, confirm:
    • Main Prompt = Platform-Agent-Tool-GeminiWebGrounding-Main
    • Router Prompt = Platform-Agent-Tool-GeminiWebGrounding-Router
    • Main Model = the completion model from Step 2
  7. Under Settings, confirm Grounding mode is Google Search, and optionally enter Exclude domains. For Enterprise grounding, select Web Grounding for Enterprise.
  8. Select Save changes, and then save the agent.

Switching models or modes

Open the tool from the agent's Tools tab, change the Main Model or Grounding mode, and save the tool and the agent. The new settings apply on the next request.

Step 4: Test in the User Portal

  1. Open the User Portal and start a new chat with the agent.
  2. Ask a current-facts question, such as When is the next total solar eclipse visible from the United States?
  3. The agent calls GeminiWebGrounding and returns a text answer, with sources when the API provides them.

What to Expect

  • The routing model chooses web grounding for research questions and the image tool (GeminiImageGen) for image prompts when both are on the agent.
  • A "Running agent tools..." status appears while Gemini completes the grounded request.
  • A ToolExecution content artifact records the grounding mode, the prompt, the excluded domains, and token counts.

Current Capabilities

  • Text completion grounded on Google Search or Web Grounding for Enterprise
  • Optional excluded domains for Search mode
  • No image output and no Context API file upload

Citation chips and Google Search Suggestion rendering are not included in this version. The tool returns grounded text to the agent.

Troubleshooting

The tool has no model

The tool needs a Main Model. Open the tool from the agent's Tools tab, select a completion model in Resource References, and save the tool and the agent.

"No grounded text was generated in the response." error

  • The Main Model may be an image generation deployment instead of a completion model.
  • The project may not have Grounding with Google Search (or the Enterprise entitlement) enabled.
  • Check the LangChain API logs for the Gemini tools payload (google_search or enterprise_web_search).

"Failed to retrieve service account credentials" error

  • The service_account_credentials authentication parameter is missing, or its App Configuration key is wrong.
  • Verify the Key Vault secret exists and contains valid service account JSON.

The agent does not call the web grounding tool

  • Try an explicit prompt, such as Search the web for... or What is the latest....
  • Verify the tool appears on the agent's Tools tab with the name GeminiWebGrounding.
  • Check that the workflow class is FoundationaLLMFunctionCallingWorkflow.

Enterprise mode fails

Enterprise mode requires the project entitlement. Without it the call fails; it does not fall back to Google Search.