feat(google-genai): Support thought signatures for Gemini 3 Pro function calling

Add thought signature support required by Gemini 3 Pro when using function
calling with includeThoughts enabled. Thought signatures preserve reasoning
context during the internal tool execution loop.

Changes from original implementation:
- Attach thought signatures to functionCall parts per Google specification
  (not to text parts or separate empty parts)
- Clarify in documentation that validation applies only to the current turn's
  function calling loop, not to historical conversation messages
- Add integration tests validating function calls with signatures

Key behaviors:
- Signatures are extracted from model responses and stored in message metadata
- During internal tool execution, signatures are correctly attached to
  functionCall parts when sending back function responses
- Handles both parallel and sequential function calls correctly:
  - Parallel: only first functionCall gets the signature (per API spec)
  - Sequential: each step's first functionCall gets its signature
- Previous turn signatures in conversation history are not validated by the API

See: https://ai.google.dev/gemini-api/docs/thought-signatures

Signed-off-by: Dan Dobrin <[email protected]>
Signed-off-by: Mark Pollack <[email protected]>

Author: markpollack

auto-configurations/models/spring-ai-autoconfigure-model-google-genai/src/test/java/org/springframework/ai/model/google/genai/autoconfigure/chat/GoogleGenAiPropertiesTests.java

@@ -131,6 +131,25 @@ void extendedUsageMetadataDefaultBinding() {
 		});
 	}
 
+	@Test
+	void includeThoughtsPropertiesBinding() {
+		this.contextRunner.withPropertyValues("spring.ai.google.genai.chat.options.include-thoughts=true")
+			.run(context -> {
+				GoogleGenAiChatProperties chatProperties = context.getBean(GoogleGenAiChatProperties.class);
+				assertThat(chatProperties.getOptions().getIncludeThoughts()).isTrue();
+			});
+	}
+
+	@Test
+	void includeThoughtsDefaultBinding() {
+		// Test that defaults are applied when not specified
+		this.contextRunner.run(context -> {
+			GoogleGenAiChatProperties chatProperties = context.getBean(GoogleGenAiChatProperties.class);
+			// Should be null when not set
+			assertThat(chatProperties.getOptions().getIncludeThoughts()).isNull();
+		});
+	}
+
 	@Configuration
 	@EnableConfigurationProperties({ GoogleGenAiConnectionProperties.class, GoogleGenAiChatProperties.class,
 			GoogleGenAiEmbeddingConnectionProperties.class })

models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/GoogleGenAiChatModel.java

@@ -281,20 +281,48 @@ else if (message instanceof UserMessage userMessage) {
 		}
 		else if (message instanceof AssistantMessage assistantMessage) {
 			List<Part> parts = new ArrayList<>();
+
+			// Check if there are thought signatures to restore.
+			// Per Google's documentation, thought signatures must be attached to the
+			// first functionCall part in each step of the current turn.
+			// See: https://ai.google.dev/gemini-api/docs/thought-signatures
+			List<byte[]> thoughtSignatures = null;
+			if (assistantMessage.getMetadata() != null
+					&& assistantMessage.getMetadata().containsKey("thoughtSignatures")) {
+				Object signaturesObj = assistantMessage.getMetadata().get("thoughtSignatures");
+				if (signaturesObj instanceof List) {
+					thoughtSignatures = new ArrayList<>((List<byte[]>) signaturesObj);
+				}
+			}
+
+			// Add text part (without thought signature - signatures go on functionCall
+			// parts)
 			if (StringUtils.hasText(assistantMessage.getText())) {
-				parts.add(Part.fromText(assistantMessage.getText()));
+				parts.add(Part.builder().text(assistantMessage.getText()).build());
 			}
+
+			// Add function call parts with thought signatures attached.
+			// Per Google's docs: "The first functionCall part in each step of the
+			// current turn must include its thought_signature."
 			if (!CollectionUtils.isEmpty(assistantMessage.getToolCalls())) {
-				parts.addAll(assistantMessage.getToolCalls()
-					.stream()
-					.map(toolCall -> Part.builder()
+				List<AssistantMessage.ToolCall> toolCalls = assistantMessage.getToolCalls();
+				for (int i = 0; i < toolCalls.size(); i++) {
+					AssistantMessage.ToolCall toolCall = toolCalls.get(i);
+					Part.Builder partBuilder = Part.builder()
 						.functionCall(FunctionCall.builder()
 							.name(toolCall.name())
 							.args(parseJsonToMap(toolCall.arguments()))
-							.build())
-						.build())
-					.toList());
+							.build());
+
+					// Attach thought signature to function call part if available
+					if (thoughtSignatures != null && !thoughtSignatures.isEmpty()) {
+						partBuilder.thoughtSignature(thoughtSignatures.remove(0));
+					}
+
+					parts.add(partBuilder.build());
+				}
 			}
+
 			return parts;
 		}
 		else if (message instanceof ToolResponseMessage toolResponseMessage) {
@@ -601,8 +629,22 @@ protected List<Generation> responseCandidateToGeneration(Candidate candidate) {
 		int candidateIndex = candidate.index().orElse(0);
 		FinishReason candidateFinishReason = candidate.finishReason().orElse(new FinishReason(FinishReason.Known.STOP));
 
-		Map<String, Object> messageMetadata = Map.of("candidateIndex", candidateIndex, "finishReason",
-				candidateFinishReason);
+		Map<String, Object> messageMetadata = new HashMap<>();
+		messageMetadata.put("candidateIndex", candidateIndex);
+		messageMetadata.put("finishReason", candidateFinishReason);
+
+		// Extract thought signatures from response parts if present
+		if (candidate.content().isPresent() && candidate.content().get().parts().isPresent()) {
+			List<Part> parts = candidate.content().get().parts().get();
+			List<byte[]> thoughtSignatures = parts.stream()
+				.filter(part -> part.thoughtSignature().isPresent())
+				.map(part -> part.thoughtSignature().get())
+				.toList();
+
+			if (!thoughtSignatures.isEmpty()) {
+				messageMetadata.put("thoughtSignatures", thoughtSignatures);
+			}
+		}
 
 		ChatGenerationMetadata chatGenerationMetadata = ChatGenerationMetadata.builder()
 			.finishReason(candidateFinishReason.toString())
@@ -716,10 +758,19 @@ GeminiRequest createGeminiRequest(Prompt prompt) {
 		if (requestOptions.getPresencePenalty() != null) {
 			configBuilder.presencePenalty(requestOptions.getPresencePenalty().floatValue());
 		}
-		if (requestOptions.getThinkingBudget() != null) {
-			configBuilder
-				.thinkingConfig(ThinkingConfig.builder().thinkingBudget(requestOptions.getThinkingBudget()).build());
+
+		// Build thinking config if either thinkingBudget or includeThoughts is set
+		if (requestOptions.getThinkingBudget() != null || requestOptions.getIncludeThoughts() != null) {
+			ThinkingConfig.Builder thinkingBuilder = ThinkingConfig.builder();
+			if (requestOptions.getThinkingBudget() != null) {
+				thinkingBuilder.thinkingBudget(requestOptions.getThinkingBudget());
+			}
+			if (requestOptions.getIncludeThoughts() != null) {
+				thinkingBuilder.includeThoughts(requestOptions.getIncludeThoughts());
+			}
+			configBuilder.thinkingConfig(thinkingBuilder.build());
 		}
+
 		if (requestOptions.getLabels() != null && !requestOptions.getLabels().isEmpty()) {
 			configBuilder.labels(requestOptions.getLabels());
 		}
@@ -1068,7 +1119,9 @@ public enum ChatModel implements ChatModelDescription {
 		 * See: <a href=
 		 * "https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash-lite">gemini-2.5-flash-lite</a>
 		 */
-		GEMINI_2_5_FLASH_LIGHT("gemini-2.5-flash-lite");
+		GEMINI_2_5_FLASH_LIGHT("gemini-2.5-flash-lite"),
+
+		GEMINI_3_PRO_PREVIEW("gemini-3-pro-preview");
 
 		public final String value;
 

models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/GoogleGenAiChatOptions.java

@@ -119,6 +119,19 @@ public class GoogleGenAiChatOptions implements ToolCallingChatOptions, Structure
 	 */
 	private @JsonProperty("thinkingBudget") Integer thinkingBudget;
 
+	/**
+	 * Optional. Whether to include thoughts in the response.
+	 * When true, thoughts are returned if the model supports them and thoughts are available.
+	 *
+	 * <p><strong>IMPORTANT:</strong> For Gemini 3 Pro with function calling,
+	 * this MUST be set to true to avoid validation errors. Thought signatures
+	 * are automatically propagated in multi-turn conversations to maintain context.
+	 *
+	 * <p>Note: Enabling thoughts increases token usage and API costs.
+	 * This is part of the thinkingConfig in GenerationConfig.
+	 */
+	private @JsonProperty("includeThoughts") Boolean includeThoughts;
+
 	/**
 	 * Optional. Whether to include extended usage metadata in responses.
 	 * When true, includes thinking tokens, cached content, tool-use tokens, and modality details.
@@ -212,6 +225,7 @@ public static GoogleGenAiChatOptions fromOptions(GoogleGenAiChatOptions fromOpti
 		options.setInternalToolExecutionEnabled(fromOptions.getInternalToolExecutionEnabled());
 		options.setToolContext(fromOptions.getToolContext());
 		options.setThinkingBudget(fromOptions.getThinkingBudget());
+		options.setIncludeThoughts(fromOptions.getIncludeThoughts());
 		options.setLabels(fromOptions.getLabels());
 		options.setIncludeExtendedUsageMetadata(fromOptions.getIncludeExtendedUsageMetadata());
 		options.setCachedContentName(fromOptions.getCachedContentName());
@@ -371,6 +385,14 @@ public void setThinkingBudget(Integer thinkingBudget) {
 		this.thinkingBudget = thinkingBudget;
 	}
 
+	public Boolean getIncludeThoughts() {
+		return this.includeThoughts;
+	}
+
+	public void setIncludeThoughts(Boolean includeThoughts) {
+		this.includeThoughts = includeThoughts;
+	}
+
 	public Boolean getIncludeExtendedUsageMetadata() {
 		return this.includeExtendedUsageMetadata;
 	}
@@ -474,6 +496,7 @@ public boolean equals(Object o) {
 				&& Objects.equals(this.frequencyPenalty, that.frequencyPenalty)
 				&& Objects.equals(this.presencePenalty, that.presencePenalty)
 				&& Objects.equals(this.thinkingBudget, that.thinkingBudget)
+				&& Objects.equals(this.includeThoughts, that.includeThoughts)
 				&& Objects.equals(this.maxOutputTokens, that.maxOutputTokens) && Objects.equals(this.model, that.model)
 				&& Objects.equals(this.responseMimeType, that.responseMimeType)
 				&& Objects.equals(this.responseSchema, that.responseSchema)
@@ -487,22 +510,22 @@ public boolean equals(Object o) {
 	@Override
 	public int hashCode() {
 		return Objects.hash(this.stopSequences, this.temperature, this.topP, this.topK, this.candidateCount,
-				this.frequencyPenalty, this.presencePenalty, this.thinkingBudget, this.maxOutputTokens, this.model,
-				this.responseMimeType, this.responseSchema, this.toolCallbacks, this.toolNames,
-				this.googleSearchRetrieval, this.safetySettings, this.internalToolExecutionEnabled, this.toolContext,
-				this.labels);
+				this.frequencyPenalty, this.presencePenalty, this.thinkingBudget, this.includeThoughts,
+				this.maxOutputTokens, this.model, this.responseMimeType, this.responseSchema, this.toolCallbacks,
+				this.toolNames, this.googleSearchRetrieval, this.safetySettings, this.internalToolExecutionEnabled,
+				this.toolContext, this.labels);
 	}
 
 	@Override
 	public String toString() {
 		return "GoogleGenAiChatOptions{" + "stopSequences=" + this.stopSequences + ", temperature=" + this.temperature
 				+ ", topP=" + this.topP + ", topK=" + this.topK + ", frequencyPenalty=" + this.frequencyPenalty
 				+ ", presencePenalty=" + this.presencePenalty + ", thinkingBudget=" + this.thinkingBudget
-				+ ", candidateCount=" + this.candidateCount + ", maxOutputTokens=" + this.maxOutputTokens + ", model='"
-				+ this.model + '\'' + ", responseMimeType='" + this.responseMimeType + '\'' + ", toolCallbacks="
-				+ this.toolCallbacks + ", toolNames=" + this.toolNames + ", googleSearchRetrieval="
-				+ this.googleSearchRetrieval + ", safetySettings=" + this.safetySettings + ", labels=" + this.labels
-				+ '}';
+				+ ", includeThoughts=" + this.includeThoughts + ", candidateCount=" + this.candidateCount
+				+ ", maxOutputTokens=" + this.maxOutputTokens + ", model='" + this.model + '\'' + ", responseMimeType='"
+				+ this.responseMimeType + '\'' + ", toolCallbacks=" + this.toolCallbacks + ", toolNames="
+				+ this.toolNames + ", googleSearchRetrieval=" + this.googleSearchRetrieval + ", safetySettings="
+				+ this.safetySettings + ", labels=" + this.labels + '}';
 	}
 
 	@Override
@@ -640,6 +663,11 @@ public Builder thinkingBudget(Integer thinkingBudget) {
 			return this;
 		}
 
+		public Builder includeThoughts(Boolean includeThoughts) {
+			this.options.setIncludeThoughts(includeThoughts);
+			return this;
+		}
+
 		public Builder includeExtendedUsageMetadata(Boolean includeExtendedUsageMetadata) {
 			this.options.setIncludeExtendedUsageMetadata(includeExtendedUsageMetadata);
 			return this;

models/spring-ai-google-genai/src/test/java/org/springframework/ai/google/genai/GoogleGenAiChatModelIT.java

@@ -105,7 +105,7 @@ void googleSearchToolPro() {
 				GoogleGenAiChatOptions.builder().model(ChatModel.GEMINI_2_5_PRO).googleSearchRetrieval(true).build());
 		ChatResponse response = this.chatModel.call(prompt);
 		assertThat(response.getResult().getOutput().getText()).containsAnyOf("Blackbeard", "Bartholomew", "Calico Jack",
-				"Anne Bonny");
+				"Bob", "Anne Bonny");
 	}
 
 	@Test

models/spring-ai-google-genai/src/test/java/org/springframework/ai/google/genai/GoogleGenAiChatModelObservationApiKeyIT.java

@@ -64,7 +64,7 @@ void beforeEach() {
 	void observationForChatOperation() {
 
 		var options = GoogleGenAiChatOptions.builder()
-			.model(GoogleGenAiChatModel.ChatModel.GEMINI_2_0_FLASH.getValue())
+			.model(GoogleGenAiChatModel.ChatModel.GEMINI_3_PRO_PREVIEW.getValue())
 			.temperature(0.7)
 			.stopSequences(List.of("this-is-the-end"))
 			.maxOutputTokens(2048)
@@ -86,7 +86,7 @@ void observationForChatOperation() {
 	void observationForStreamingOperation() {
 
 		var options = GoogleGenAiChatOptions.builder()
-			.model(GoogleGenAiChatModel.ChatModel.GEMINI_2_0_FLASH.getValue())
+			.model(GoogleGenAiChatModel.ChatModel.GEMINI_3_PRO_PREVIEW.getValue())
 			.temperature(0.7)
 			.stopSequences(List.of("this-is-the-end"))
 			.maxOutputTokens(2048)
@@ -126,7 +126,7 @@ private void validate(ChatResponseMetadata responseMetadata) {
 					AiProvider.GOOGLE_GENAI_AI.value())
 			.hasLowCardinalityKeyValue(
 					ChatModelObservationDocumentation.LowCardinalityKeyNames.REQUEST_MODEL.asString(),
-					GoogleGenAiChatModel.ChatModel.GEMINI_2_0_FLASH.getValue())
+					GoogleGenAiChatModel.ChatModel.GEMINI_3_PRO_PREVIEW.getValue())
 			.hasHighCardinalityKeyValue(
 					ChatModelObservationDocumentation.HighCardinalityKeyNames.REQUEST_MAX_TOKENS.asString(), "2048")
 			.hasHighCardinalityKeyValue(
@@ -174,8 +174,9 @@ public GoogleGenAiChatModel vertexAiEmbedding(Client genAiClient, TestObservatio
 			return GoogleGenAiChatModel.builder()
 				.genAiClient(genAiClient)
 				.observationRegistry(observationRegistry)
-				.defaultOptions(
-						GoogleGenAiChatOptions.builder().model(GoogleGenAiChatModel.ChatModel.GEMINI_2_0_FLASH).build())
+				.defaultOptions(GoogleGenAiChatOptions.builder()
+					.model(GoogleGenAiChatModel.ChatModel.GEMINI_3_PRO_PREVIEW)
+					.build())
 				.build();
 		}
 

models/spring-ai-google-genai/src/test/java/org/springframework/ai/google/genai/GoogleGenAiRetryTests.java

@@ -61,7 +61,7 @@ public void setUp() {
 				GoogleGenAiChatOptions.builder()
 					.temperature(0.7)
 					.topP(1.0)
-					.model(GoogleGenAiChatModel.ChatModel.GEMINI_2_0_FLASH.getValue())
+					.model(GoogleGenAiChatModel.ChatModel.GEMINI_3_PRO_PREVIEW.getValue())
 					.build(),
 				this.retryTemplate);