Introduce Grouding with Google Search configuration

Author: scherervictor

dotnet/samples/Concepts/ChatCompletion/Google_GeminiChatCompletionGroudingWithGoogleSearch.cs

@@ -0,0 +1,62 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.ChatCompletion;
+using Microsoft.SemanticKernel.Connectors.Google;
+
+namespace ChatCompletion;
+
+/// <summary>
+/// These examples demonstrate different ways of using chat completion with Google AI API.
+/// <para>
+/// Currently grounding with Google Search is only supported in Google AI Gemini 2.0+ models
+/// See: https://ai.google.dev/gemini-api/docs/grounding
+/// </para>
+/// </summary>
+public sealed class Google_GeminiChatCompletionGroudingWithGoogleSearch(ITestOutputHelper output) : BaseTest(output)
+{
+    [Fact]
+    public async Task GoogleAIChatCompletionUsingThinkingBudget()
+    {
+        Console.WriteLine("============= Google AI - Gemini 2.5 Chat Completion using Grounding with Google Search =============");
+
+        Assert.NotNull(TestConfiguration.GoogleAI.ApiKey);
+        string geminiModelId = "gemini-2.5-pro-exp-03-25";
+
+        Kernel kernel = Kernel.CreateBuilder()
+            .AddGoogleAIGeminiChatCompletion(
+                modelId: geminiModelId,
+                apiKey: TestConfiguration.GoogleAI.ApiKey)
+            .Build();
+
+        var chatHistory = new ChatHistory("You are an expert in the tool shop.");
+        var chat = kernel.GetRequiredService<IChatCompletionService>();
+        var executionSettings = new GeminiPromptExecutionSettings
+        {
+            // This parameter enables grouding with google search.
+            GroundingConfig = new() { GoogleSearch = new() }
+        };
+
+        // First user message
+        chatHistory.AddUserMessage("Hi, I'm looking for new power tools, any suggestion?");
+        await MessageOutputAsync(chatHistory);
+
+        // First assistant message
+        var reply = await chat.GetChatMessageContentAsync(chatHistory, executionSettings);
+        chatHistory.Add(reply);
+        await MessageOutputAsync(chatHistory);
+    }
+
+    /// <summary>
+    /// Outputs the last message of the chat history
+    /// </summary>
+    private Task MessageOutputAsync(ChatHistory chatHistory)
+    {
+        var message = chatHistory.Last();
+
+        Console.WriteLine($"{message.Role}: {message.Content}");
+        Console.WriteLine("------------------------");
+
+        return Task.CompletedTask;
+    }
+}

dotnet/samples/Concepts/README.md

@@ -64,6 +64,7 @@ dotnet test -l "console;verbosity=detailed" --filter "FullyQualifiedName=ChatCom
 - [Google_GeminiChatCompletion](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/ChatCompletion/Google_GeminiChatCompletion.cs)
 - [Google_GeminiChatCompletionStreaming](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/ChatCompletion/Google_GeminiChatCompletionStreaming.cs)
 - [Google_GeminiChatCompletionWithThinkingBudget](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/ChatCompletion/Google_GeminiChatCompletionWithThinkingBudget.cs)
+- [Google_GeminiChatCompletionGroundingWithGoogleSearch](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/ChatCompletion/Google_GeminiChatCompletionGroudingWithGoogleSearch.cs)
 - [Google_GeminiGetModelResult](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/ChatCompletion/Google_GeminiGetModelResult.cs)
 - [Google_GeminiStructuredOutputs](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/ChatCompletion/Google_GeminiStructuredOutputs.cs)
 - [Google_GeminiVision](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/ChatCompletion/Google_GeminiVision.cs)

dotnet/src/Connectors/Connectors.Google.UnitTests/GeminiPromptExecutionSettingsTests.cs

@@ -112,6 +112,9 @@ public void ItCreatesGeminiExecutionSettingsFromJsonSnakeCase()
                           ],
                           "thinking_config": {
                             "thinking_budget": 1000
+                          },
+                          "grounding_config": {
+                            "google_search": {}
                           }
                         }
                         """;
@@ -134,6 +137,7 @@ public void ItCreatesGeminiExecutionSettingsFromJsonSnakeCase()
             settings.Threshold.Equals(threshold));
 
         Assert.Equal(1000, executionSettings.ThinkingConfig?.ThinkingBudget);
+        Assert.NotNull(executionSettings.GroundingConfig?.GoogleSearch);
     }
 
     [Fact]
@@ -160,6 +164,9 @@ public void PromptExecutionSettingsCloneWorksAsExpected()
                           ],
                           "thinking_config": {
                             "thinking_budget": 1000
+                          },
+                          "grouding_config": {
+                            "google_search": {}
                           }
                         }
                         """;
@@ -177,6 +184,7 @@ public void PromptExecutionSettingsCloneWorksAsExpected()
         Assert.Equivalent(executionSettings.SafetySettings, clone.SafetySettings);
         Assert.Equal(executionSettings.AudioTimestamp, clone.AudioTimestamp);
         Assert.Equivalent(executionSettings.ThinkingConfig, clone.ThinkingConfig);
+        Assert.Equivalent(executionSettings.GroundingConfig, clone.GroundingConfig);
     }
 
     [Fact]
@@ -220,5 +228,6 @@ public void PromptExecutionSettingsFreezeWorksAsExpected()
         Assert.Throws<NotSupportedException>(() => executionSettings.StopSequences!.Add("baz"));
         Assert.Throws<NotSupportedException>(() => executionSettings.SafetySettings!.Add(new GeminiSafetySetting(GeminiSafetyCategory.Toxicity, GeminiSafetyThreshold.Unspecified)));
         Assert.Throws<InvalidOperationException>(() => executionSettings.ThinkingConfig = new GeminiThinkingConfig { ThinkingBudget = 1 });
+        Assert.Throws<InvalidOperationException>(() => executionSettings.GroundingConfig = new GeminiGroundingConfig { GoogleSearch = new object() });
     }
 }

dotnet/src/Connectors/Connectors.Google.UnitTests/Services/GoogleAIGeminiChatCompletionServiceTests.cs

@@ -144,6 +144,41 @@ public async Task RequestBodyIncludesThinkingConfigWhenSetAsync(int? thinkingBud
         }
     }
 
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public async Task RequestBodyIncludesGoogleSearchToolWhenSetAsync(bool shouldContain)
+    {
+        // Arrange
+        string model = "gemini-2.5-pro";
+        var sut = new GoogleAIGeminiChatCompletionService(model, "key", httpClient: this._httpClient);
+
+        var executionSettings = new GeminiPromptExecutionSettings
+        {
+            GroundingConfig = shouldContain
+                ? new GeminiGroundingConfig() { GoogleSearch = new() }
+                : null
+        };
+
+        // Act
+        var result = await sut.GetChatMessageContentAsync("my prompt", executionSettings);
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(this._messageHandlerStub.RequestContent);
+
+        var requestBody = UTF8Encoding.UTF8.GetString(this._messageHandlerStub.RequestContent);
+
+        if (shouldContain)
+        {
+            Assert.Contains("googleSearch", requestBody);
+        }
+        else
+        {
+            Assert.DoesNotContain("googleSearch", requestBody);
+        }
+    }
+
     public void Dispose()
     {
         this._httpClient.Dispose();

dotnet/src/Connectors/Connectors.Google.UnitTests/Services/VertexAIGeminiChatCompletionServiceTests.cs

@@ -156,6 +156,41 @@ public async Task RequestBodyIncludesThinkingConfigWhenSetAsync(int? thinkingBud
         }
     }
 
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public async Task RequestBodyIncludesGoogleSearchToolWhenSetAsync(bool shouldContain)
+    {
+        // Arrange
+        string model = "gemini-2.5-pro";
+        var sut = new VertexAIGeminiChatCompletionService(model, () => new ValueTask<string>("key"), "location", "project", httpClient: this._httpClient);
+
+        var executionSettings = new GeminiPromptExecutionSettings
+        {
+            GroundingConfig = shouldContain
+                ? new GeminiGroundingConfig() { GoogleSearch = new() }
+                : null
+        };
+
+        // Act
+        var result = await sut.GetChatMessageContentAsync("my prompt", executionSettings);
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(this._messageHandlerStub.RequestContent);
+
+        var requestBody = UTF8Encoding.UTF8.GetString(this._messageHandlerStub.RequestContent);
+
+        if (shouldContain)
+        {
+            Assert.Contains("googleSearch", requestBody);
+        }
+        else
+        {
+            Assert.DoesNotContain("googleSearch", requestBody);
+        }
+    }
+
     public void Dispose()
     {
         this._httpClient.Dispose();

dotnet/src/Connectors/Connectors.Google/Core/Gemini/Clients/GeminiChatCompletionClient.cs

@@ -691,6 +691,7 @@ private static GeminiMetadata GetResponseMetadata(
             PromptFeedbackBlockReason = geminiResponse.PromptFeedback?.BlockReason,
             PromptFeedbackSafetyRatings = geminiResponse.PromptFeedback?.SafetyRatings.ToList(),
             ResponseSafetyRatings = candidate.SafetyRatings?.ToList(),
+            GroundingMetadata = candidate.GroundingMetadata
         };
 
     private sealed class ChatCompletionState

dotnet/src/Connectors/Connectors.Google/Core/Gemini/Models/GeminiRequest.cs

@@ -461,6 +461,16 @@ private static void AddAdditionalBodyFields(GeminiPromptExecutionSettings execut
             request.Configuration ??= new ConfigurationElement();
             request.Configuration.ThinkingConfig = new GeminiRequestThinkingConfig { ThinkingBudget = executionSettings.ThinkingConfig.ThinkingBudget };
         }
+
+        if (executionSettings.GroundingConfig?.GoogleSearch is not null)
+        {
+            request.Tools ??= [];
+            if (request.Tools.Count == 0)
+            {
+                request.Tools.Add(new GeminiTool());
+            }
+            request.Tools[0].GoogleSearch = new GeminiTool.GoogleSearchProperties();
+        }
     }
 
     internal sealed class ConfigurationElement

dotnet/src/Connectors/Connectors.Google/Core/Gemini/Models/GeminiResponseCandidate.cs

@@ -45,4 +45,13 @@ internal sealed class GeminiResponseCandidate
     /// </summary>
     [JsonPropertyName("tokenCount")]
     public int TokenCount { get; set; }
+
+    /// <summary>
+    /// Optional. GroundingMetadata of response candidate.
+    /// </summary>
+    /// <remarks>
+    /// Returned when Grounding with Google Search is enabled.
+    /// </remarks>
+    [JsonPropertyName("groundingMetadata")]
+    public GeminiGroundingMetadata? GroundingMetadata { get; set; }
 }

dotnet/src/Connectors/Connectors.Google/Core/Gemini/Models/GeminiTool.cs

@@ -25,6 +25,17 @@ internal sealed class GeminiTool
     [JsonPropertyName("functionDeclarations")]
     public IList<FunctionDeclaration> Functions { get; set; } = [];
 
+    /// <summary>
+    /// Optional. Google Search configuration that allows the model to use Google Search as a tool to improve response quality.
+    /// When this property is set (even with empty object), the model can decide to use Google Search autonomously.
+    /// </summary>
+    /// <remarks>
+    /// The Search-as-a-tool functionality also enables multi-turn searches. Combining Search with function calling is not yet supported.
+    /// </remarks>
+    [JsonPropertyName("googleSearch")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public GoogleSearchProperties? GoogleSearch { get; set; }
+
     /// <summary>
     /// Structured representation of a function declaration as defined by the OpenAPI 3.03 specification.
     /// Included in this declaration are the function name and parameters.
@@ -56,4 +67,12 @@ internal sealed class FunctionDeclaration
         [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
         public JsonElement? Parameters { get; set; }
     }
+
+    /// <summary>
+    /// Configuration properties for Google Search integration.
+    /// </summary>
+    /// <remarks>
+    /// An empty object is sufficient to enable Search as a tool.
+    /// </remarks>
+    internal sealed class GoogleSearchProperties;
 }

dotnet/src/Connectors/Connectors.Google/GeminiGroundingConfig.cs

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace Microsoft.SemanticKernel.Connectors.Google;
+
+/// <summary>
+/// GeminiGroundingConfig class
+/// </summary>
+public class GeminiGroundingConfig
+{
+    /// <summary>The Grounding with Google Search feature in the Gemini API can be used to improve the accuracy and recency of responses from the model.</summary>
+    /// <remarks>
+    /// The model can decide when to use Google Search.
+    /// This parameter is valid from Gemini 2.0+.
+    /// Combining Search with function calling is not yet supported. Functions will be ignored when this parameter is set.
+    /// </remarks>
+    [JsonPropertyName("google_search")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? GoogleSearch { get; set; }
+
+    /// <summary>
+    /// Clones this instance.
+    /// </summary>
+    /// <returns></returns>
+    public GeminiGroundingConfig Clone()
+    {
+        return (GeminiGroundingConfig)this.MemberwiseClone();
+    }
+}