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