LangChain4j Gemini 工具调用报 missing thought_signature

Gemini 3 对每个 functionCall part 返回一个强制的 thoughtSignature。下一轮请求必须原样回传，还要放在相同的 content-part 位置。langchain4j-vertex-ai-gemini 适配层没有提取、也没回传这个字段。于是第一轮工具调用成功，追加工具结果后第二轮立刻 400 INVALID_ARGUMENT: missing thought_signature。问题在适配层，不在你的 @Tool 定义。

Issue & Env（案发现场与环境）

业务场景：用 LangChain4j 的 Vertex AI Gemini 集成做多轮工具调用。第一轮正常，回传工具结果后第二轮 400。
环境：langchain4j-vertex-ai-gemini 模块，模型为 Gemini 3 系列，例如 gemini-3.1-pro-preview。报错出自 langchain4j issue #5134。

StackTrace（堆栈日志）

报错原文很干净：

400 INVALID_ARGUMENT: missing thought_signature

报错里同时出现的模型名示例：gemini-3.1-pro-preview。

Reproduce（复现代码）

一个两轮的工具调用流程就能复现。第一轮让模型选工具：

String first = chatModel.chat(
    UserMessage.from("北京现在天气怎么样？")
);
// 模型返回 functionCall，正常

拿到 functionCall 后执行工具，把结果追加进消息再请求第二轮：

String second = chatModel.chat(
    userMessage,
    aiMessage,          // 含 functionCall 的那条
    ToolExecutionResultMessage.from(...)
);
// 第二轮直接抛 400 INVALID_ARGUMENT: missing thought_signature

第一轮成功最容易让人误判成工具定义写错。其实不是。

Root Cause（根因分析）

Gemini 3 强制回传签名

Gemini 3 对每个 functionCall part 返回一个强制的 thoughtSignature。下一轮请求必须把该签名原样回传，并且要在相同的 content-part 位置。否则 API 立即返回 400 INVALID_ARGUMENT。

Vertex 适配层缺字段

langchain4j-vertex-ai-gemini 适配层没有提取、也没有回传这个字段。于是出现典型症状：第一轮工具调用成功，追加工具结果后第二轮立刻 400。

兄弟模块行为不同

langchain4j-google-ai-gemini 暴露了 sendThinking(true) 与 returnThinking(true)，按文档能处理这个签名。Vertex 集成没有等价开关。这是两边行为差异的根源，也是 issue 的结论。

与 #4097 同源

issue 指出这与已关闭的 #4097 是同一个根问题。但 #4097 落地的修复（PR #4200）只覆盖 OpenAI / DeepSeek 的 reasoning_content 路径，没覆盖 Vertex AI Gemini。

The Fix（解决方案）

1. 首选：换到 google-ai-gemini

改用 langchain4j-google-ai-gemini 模块，并按文档开启 thinking 相关开关：

GoogleAiGeminiChatModel model = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .sendThinking(true)
    .returnThinking(true)
    .build();

同时注意模型选择，避开 Gemini 3 的签名强制场景。接口细节见 Google AI Gemini 官方文档。

2. 次选：等 Vertex 补齐

等 langchain4j-vertex-ai-gemini 把 thoughtSignature 的往返补齐。在此期间，别在该模块上做多轮工具调用。

3. 绕行

改用不支持、或不强制 thought signature 的模型版本。或者把多轮工具调用拆成不带工具的单轮。流式场景下可对照 Response streaming 文档。

4. 排查口诀

Gemini 上「第一轮工具调用正常、第二轮必 400」，且消息里出现 INVALID_ARGUMENT、thought_signature，基本就是这个适配问题。不用去查你的 @Tool 定义。

版本与修复状态：截至撰写时，Vertex 模块尚未补齐该字段往返，属未修复；以 issue #5134 的最新状态为准。

小结

missing thought_signature 是 Vertex 适配层没回传签名字段。第一轮成功不代表工具定义有问题。首选换到 google-ai-gemini 并开启 thinking 开关，次选等 Vertex 修复，或改成单轮工具调用。

References（参考来源）

VertexAiGeminiStreamingChatModel — Gemini 3 tool calls fail with INVALID_ARGUMENT: missing thought_signature — langchain4j issue #5134github-issue
Google Vertex AI Gemini — LangChain4j 官方文档langchain4j-docs
Google AI Gemini — LangChain4j 官方文档langchain4j-docs
Response streaming — LangChain4j 官方文档langchain4j-docs