From 738d04fac41726ff3f228a14ecb7e5800cd77524 Mon Sep 17 00:00:00 2001
From: Dustin Healy <54083382+dustinhealy@users.noreply.github.com>
Date: Tue, 1 Jul 2025 15:00:18 -0700
Subject: [PATCH] =?UTF-8?q?=F0=9F=94=8D=20feat:=20Add=20Google=20Search=20?=
 =?UTF-8?q?Grounding=20Toggle=20(#8174)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* ✨ feat: Add Google Search Grounding Feature and Update Agent Tool Initialization

- Introduced a new grounding option in the Google configuration to enable real-time web search results.
- Updated the agent initialization to concatenate additional tools from options.
- Enhanced translation files to include descriptions for the new grounding feature.
- Modified relevant schemas and parameter settings to support the grounding functionality.

* 🔑 chore: Update @librechat/agents dependency to version 2.4.50

* ✅ fix: Ensure tools array is initialized before concatenation in initializeAgent function

* chore: Update version of librechat-data-provider to 0.7.899 and add GOOGLE_TOOL_CONFLICT error type

* fix: Adjust label class for better text wrapping in DynamicSwitch component

* fix: Handle Google tool conflict error and update error messages in translation

* fix: Restore grounding setting in googleCol2 configuration

---------

Co-authored-by: Danny Avila <danny@librechat.ai>
---
 api/package.json                                  |  2 +-
 api/server/services/Endpoints/agents/agent.js     | 10 +++++++++-
 client/src/components/Messages/Content/Error.tsx  |  1 +
 .../SidePanel/Parameters/DynamicSwitch.tsx        |  2 +-
 client/src/locales/en/translation.json            |  3 +++
 package-lock.json                                 | 12 ++++++------
 packages/api/package.json                         |  2 +-
 packages/api/src/endpoints/google/llm.ts          | 10 ++++++++++
 packages/data-provider/package.json               |  2 +-
 packages/data-provider/src/config.ts              |  4 ++++
 packages/data-provider/src/parameterSettings.ts   | 15 +++++++++++++++
 packages/data-provider/src/schemas.ts             |  6 ++++++
 packages/data-schemas/src/types/convo.ts          |  1 +
 13 files changed, 59 insertions(+), 11 deletions(-)

diff --git a/api/package.json b/api/package.json
index fd002d58ce..6621b37fd9 100644
--- a/api/package.json
+++ b/api/package.json
@@ -48,7 +48,7 @@
     "@langchain/google-genai": "^0.2.13",
     "@langchain/google-vertexai": "^0.2.13",
     "@langchain/textsplitters": "^0.1.0",
-    "@librechat/agents": "^2.4.49",
+    "@librechat/agents": "^2.4.50",
     "@librechat/api": "*",
     "@librechat/data-schemas": "*",
     "@node-saml/passport-saml": "^5.0.0",
diff --git a/api/server/services/Endpoints/agents/agent.js b/api/server/services/Endpoints/agents/agent.js
index a3523605db..469cacd0e4 100644
--- a/api/server/services/Endpoints/agents/agent.js
+++ b/api/server/services/Endpoints/agents/agent.js
@@ -140,6 +140,14 @@ const initializeAgent = async ({
     agent.provider = options.provider;
   }
 
+  if (
+    (agent.provider === Providers.GOOGLE || agent.provider === Providers.VERTEXAI) &&
+    options?.tools?.length &&
+    tools?.length
+  ) {
+    throw new Error(`{ "type": "${ErrorTypes.GOOGLE_TOOL_CONFLICT}"}`);
+  }
+
   /** @type {import('@librechat/agents').ClientOptions} */
   agent.model_parameters = { ...options.llmConfig };
   if (options.configOptions) {
@@ -162,10 +170,10 @@ const initializeAgent = async ({
 
   return {
     ...agent,
-    tools,
     attachments,
     resendFiles,
     toolContextMap,
+    tools: options.tools ?? tools,
     maxContextTokens: (agentMaxContextTokens - maxTokens) * 0.9,
   };
 };
diff --git a/client/src/components/Messages/Content/Error.tsx b/client/src/components/Messages/Content/Error.tsx
index 8a9391ccda..77580a3737 100644
--- a/client/src/components/Messages/Content/Error.tsx
+++ b/client/src/components/Messages/Content/Error.tsx
@@ -62,6 +62,7 @@ const errorMessages = {
     const { info } = json;
     return info;
   },
+  [ErrorTypes.GOOGLE_TOOL_CONFLICT]: 'com_error_google_tool_conflict',
   [ViolationTypes.BAN]:
     'Your account has been temporarily banned due to violations of our service.',
   invalid_api_key:
diff --git a/client/src/components/SidePanel/Parameters/DynamicSwitch.tsx b/client/src/components/SidePanel/Parameters/DynamicSwitch.tsx
index a603ffe89d..eff11f3453 100644
--- a/client/src/components/SidePanel/Parameters/DynamicSwitch.tsx
+++ b/client/src/components/SidePanel/Parameters/DynamicSwitch.tsx
@@ -50,7 +50,7 @@ function DynamicSwitch({
           <div className="flex justify-between">
             <Label
               htmlFor={`${settingKey}-dynamic-switch`}
-              className="text-left text-sm font-medium"
+              className="break-words text-left text-sm font-medium"
             >
               {labelCode ? (localize(label as TranslationKeys) ?? label) : label || settingKey}{' '}
               {showDefault && (
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index 0fcfe0bb42..1e130a0f82 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -233,6 +233,7 @@
   "com_endpoint_openai_temp": "Higher values = more random, while lower values = more focused and deterministic. We recommend altering this or Top P but not both.",
   "com_endpoint_openai_topp": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We recommend altering this or temperature but not both.",
   "com_endpoint_openai_use_responses_api": "Use the Responses API instead of Chat Completions, which includes extended features from OpenAI. Required for o1-pro, o3-pro, and to enable reasoning summaries.",
+  "com_endpoint_google_use_search_grounding": "Use Google's search grounding feature to enhance responses with real-time web search results. This enables models to access current information and provide more accurate, up-to-date answers.",
   "com_endpoint_output": "Output",
   "com_endpoint_plug_image_detail": "Image Detail",
   "com_endpoint_plug_resend_files": "Resend Files",
@@ -280,6 +281,7 @@
   "com_endpoint_top_p": "Top P",
   "com_endpoint_use_active_assistant": "Use Active Assistant",
   "com_endpoint_use_responses_api": "Use Responses API",
+  "com_endpoint_use_search_grounding": "Grounding with Google Search",
   "com_error_expired_user_key": "Provided key for {{0}} expired at {{1}}. Please provide a new key and try again.",
   "com_error_files_dupe": "Duplicate file detected.",
   "com_error_files_empty": "Empty files are not allowed.",
@@ -291,6 +293,7 @@
   "com_error_heic_conversion": "Failed to convert HEIC image to JPEG. Please try converting the image manually or use a different format.",
   "com_error_input_length": "The latest message token count is too long, exceeding the token limit, or your token limit parameters are misconfigured, adversely affecting the context window. More info: {{0}}. Please shorten your message, adjust the max context size from the conversation parameters, or fork the conversation to continue.",
   "com_error_invalid_agent_provider": "The \"{{0}}\" provider is not available for use with Agents. Please go to your agent's settings and select a currently available provider.",
+  "com_error_google_tool_conflict": "Usage of built-in Google tools are not supported with external tools. Please disable either the built-in tools or the external tools.",
   "com_error_invalid_user_key": "Invalid key provided. Please provide a valid key and try again.",
   "com_error_moderation": "It appears that the content submitted has been flagged by our moderation system for not aligning with our community guidelines. We're unable to proceed with this specific topic. If you have any other questions or topics you'd like to explore, please edit your message, or create a new conversation.",
   "com_error_no_base_url": "No base URL found. Please provide one and try again.",
diff --git a/package-lock.json b/package-lock.json
index 8d04047ef4..7290a012ba 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -64,7 +64,7 @@
         "@langchain/google-genai": "^0.2.13",
         "@langchain/google-vertexai": "^0.2.13",
         "@langchain/textsplitters": "^0.1.0",
-        "@librechat/agents": "^2.4.49",
+        "@librechat/agents": "^2.4.50",
         "@librechat/api": "*",
         "@librechat/data-schemas": "*",
         "@node-saml/passport-saml": "^5.0.0",
@@ -19436,9 +19436,9 @@
       }
     },
     "node_modules/@librechat/agents": {
-      "version": "2.4.49",
-      "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-2.4.49.tgz",
-      "integrity": "sha512-Bnp/PZsg1VgnmGS80tW4ssKpcqUZ7xysKesV/8gGaUBF1VDBiYBh0gC6ugfJhltNOv93rEVSucjPlTAuHimNCg==",
+      "version": "2.4.50",
+      "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-2.4.50.tgz",
+      "integrity": "sha512-8yUndPTa5ctxGBqlzMcyBDi+c6lup37wtXXFJMyBcm2Bx4MhqrEOMdI3HRu/3CsYpRgC07wAK2AwZ593aGLWoA==",
       "license": "MIT",
       "dependencies": {
         "@langchain/anthropic": "^0.3.23",
@@ -46624,7 +46624,7 @@
         "typescript": "^5.0.4"
       },
       "peerDependencies": {
-        "@librechat/agents": "^2.4.49",
+        "@librechat/agents": "^2.4.50",
         "@librechat/data-schemas": "*",
         "@modelcontextprotocol/sdk": "^1.12.3",
         "axios": "^1.8.2",
@@ -46717,7 +46717,7 @@
     },
     "packages/data-provider": {
       "name": "librechat-data-provider",
-      "version": "0.7.89",
+      "version": "0.7.899",
       "license": "ISC",
       "dependencies": {
         "axios": "^1.8.2",
diff --git a/packages/api/package.json b/packages/api/package.json
index a4c41ec537..8275e35c9c 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -69,7 +69,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "peerDependencies": {
-    "@librechat/agents": "^2.4.49",
+    "@librechat/agents": "^2.4.50",
     "@librechat/data-schemas": "*",
     "@modelcontextprotocol/sdk": "^1.12.3",
     "axios": "^1.8.2",
diff --git a/packages/api/src/endpoints/google/llm.ts b/packages/api/src/endpoints/google/llm.ts
index c2c26e3251..e76075f44a 100644
--- a/packages/api/src/endpoints/google/llm.ts
+++ b/packages/api/src/endpoints/google/llm.ts
@@ -1,6 +1,7 @@
 import { Providers } from '@librechat/agents';
 import { googleSettings, AuthKeys } from 'librechat-data-provider';
 import type { GoogleClientOptions, VertexAIClientOptions } from '@librechat/agents';
+import type { GoogleAIToolType } from '@langchain/google-common';
 import type * as t from '~/types';
 import { isEnabled } from '~/utils';
 
@@ -105,6 +106,7 @@ export function getGoogleConfig(
   const authHeader = options.authHeader;
 
   const {
+    grounding,
     thinking = googleSettings.thinking.default,
     thinkingBudget = googleSettings.thinkingBudget.default,
     ...modelOptions
@@ -187,8 +189,16 @@ export function getGoogleConfig(
     };
   }
 
+  const tools: GoogleAIToolType[] = [];
+
+  if (grounding) {
+    tools.push({ googleSearch: {} });
+  }
+
   // Return the final shape
   return {
+    /** @type {GoogleAIToolType[]} */
+    tools,
     /** @type {Providers.GOOGLE | Providers.VERTEXAI} */
     provider,
     /** @type {GoogleClientOptions | VertexAIClientOptions} */
diff --git a/packages/data-provider/package.json b/packages/data-provider/package.json
index cb4e94eb77..90ea975001 100644
--- a/packages/data-provider/package.json
+++ b/packages/data-provider/package.json
@@ -1,6 +1,6 @@
 {
   "name": "librechat-data-provider",
-  "version": "0.7.89",
+  "version": "0.7.899",
   "description": "data services for librechat apps",
   "main": "dist/index.js",
   "module": "dist/index.es.js",
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index cf69603bf1..7f1b2c8fbe 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -1257,6 +1257,10 @@ export enum ErrorTypes {
    * Google provider returned an error
    */
   GOOGLE_ERROR = 'google_error',
+  /**
+   * Google provider does not allow custom tools with built-in tools
+   */
+  GOOGLE_TOOL_CONFLICT = 'google_tool_conflict',
   /**
    * Invalid Agent Provider (excluded by Admin)
    */
diff --git a/packages/data-provider/src/parameterSettings.ts b/packages/data-provider/src/parameterSettings.ts
index 8366987e43..1b28e9cc3c 100644
--- a/packages/data-provider/src/parameterSettings.ts
+++ b/packages/data-provider/src/parameterSettings.ts
@@ -537,6 +537,19 @@ const google: Record<string, SettingDefinition> = {
     optionType: 'conversation',
     columnSpan: 2,
   },
+  grounding: {
+    key: 'grounding',
+    label: 'com_endpoint_use_search_grounding',
+    labelCode: true,
+    description: 'com_endpoint_google_use_search_grounding',
+    descriptionCode: true,
+    type: 'boolean',
+    default: false,
+    component: 'switch',
+    optionType: 'model',
+    showDefault: false,
+    columnSpan: 2,
+  },
 };
 
 const googleConfig: SettingsConfiguration = [
@@ -550,6 +563,7 @@ const googleConfig: SettingsConfiguration = [
   librechat.resendFiles,
   google.thinking,
   google.thinkingBudget,
+  google.grounding,
 ];
 
 const googleCol1: SettingsConfiguration = [
@@ -567,6 +581,7 @@ const googleCol2: SettingsConfiguration = [
   librechat.resendFiles,
   google.thinking,
   google.thinkingBudget,
+  google.grounding,
 ];
 
 const openAI: SettingsConfiguration = [
diff --git a/packages/data-provider/src/schemas.ts b/packages/data-provider/src/schemas.ts
index 5b654d90bc..de51c35bf2 100644
--- a/packages/data-provider/src/schemas.ts
+++ b/packages/data-provider/src/schemas.ts
@@ -634,6 +634,8 @@ export const tConversationSchema = z.object({
   reasoning_summary: eReasoningSummarySchema.optional().nullable(),
   /* OpenAI: use Responses API */
   useResponsesApi: z.boolean().optional(),
+  /* Google: use Search Grounding */
+  grounding: z.boolean().optional(),
   /* assistant */
   assistant_id: z.string().optional(),
   /* agents */
@@ -736,6 +738,8 @@ export const tQueryParamsSchema = tConversationSchema
     reasoning_summary: true,
     /** @endpoints openAI, custom, azureOpenAI */
     useResponsesApi: true,
+    /** @endpoints google */
+    grounding: true,
     /** @endpoints google, anthropic, bedrock */
     topP: true,
     /** @endpoints google, anthropic */
@@ -818,6 +822,7 @@ export const googleBaseSchema = tConversationSchema.pick({
   topK: true,
   thinking: true,
   thinkingBudget: true,
+  grounding: true,
   iconURL: true,
   greeting: true,
   spec: true,
@@ -849,6 +854,7 @@ export const googleGenConfigSchema = z
         thinkingBudget: coerceNumber.optional(),
       })
       .optional(),
+    grounding: z.boolean().optional(),
   })
   .strip()
   .optional();
diff --git a/packages/data-schemas/src/types/convo.ts b/packages/data-schemas/src/types/convo.ts
index b97f179b53..1d9ba8749e 100644
--- a/packages/data-schemas/src/types/convo.ts
+++ b/packages/data-schemas/src/types/convo.ts
@@ -47,6 +47,7 @@ export interface IConversation extends Document {
   reasoning_effort?: string;
   reasoning_summary?: string;
   useResponsesApi?: boolean;
+  grounding?: boolean;
   // Additional fields
   files?: string[];
   expiredAt?: Date;