What is thought_signature in Gemini and how do you use it?

If you call a Gemini thinking model such as Gemini 4 or Gemini 3 through the API, you will quickly notice a field named thought_signature on some parts of the response. This guide explains what that field actually is, why Google added it, and what you are expected to do with it in real applications.

Note: Google shut down gemini-3-pro-preview on March 9, 2026 and recommends gemini-3.1-pro-preview. Thought signatures still apply to current Gemini 4 and Gemini 3 models; the examples below use the generateContent API.

How thought_signature works in Gemini

It is an encrypted snapshot of the model's reasoning for one response part.
You cannot decode it; your job is to store it and send it back unchanged.
Dropping it from a function call can cause 400 errors; dropping it elsewhere can weaken reasoning.

What is a thought signature in Gemini?

In Gemini, a thought signature is an opaque token that encodes the model's internal reasoning state for a specific content part. Google describes it as an encrypted representation of the model's internal thought process, used so Gemini can preserve its reasoning state across multi step and multi turn interactions.

You cannot inspect, decode, or use the value directly. It is only meaningful to the model and the serving stack that verifies it.

What does thought_signature look like in the API?

In the generateContent API on Gemini and Vertex AI, thought signatures appear as fields such as thought_signature or thoughtSignature on individual parts of a response. For example, a function call part or the final text part can carry a thought signature. The newer Interactions API places signatures differently: on thought steps and built-in tool steps, not on standard function calls or model output.

A simplified generateContent JSON example looks like this:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "getWeather",
              "args": { "city": "London" }
            },
            "thought_signature": "AgQKA..."
          }
        ]
      }
    }
  ]
}

The exact value and structure of the token are unspecified and can change at any time. You should treat it as opaque data.

Why does Gemini use thought signatures?

Gemini 4 and Gemini 3 are thinking models that can run extended reasoning steps before it returns text or a tool call. When it calls an external tool, that reasoning has to pause while your code runs. The thought signature acts like a signed save state so the model can resume the same line of thought on the next request instead of starting again from the plain chat text.

This helps Gemini keep its chain of reasoning consistent across multi step and multi turn interactions and can reduce the amount of redundant reasoning work the model has to do.

When do you need to pass thought_signature back?

When you build the generateContent conversation history yourself, preserving thought signatures is required for function calls and recommended for text.

Tool calls and function calling: When the model returns a functionCall, that part usually includes a thought_signature. When you send the tool result back in the next request, you must include the original function call part in the history with the exact same thought_signature value.
Parallel function calls: When one response contains several function calls, only the first functionCall part carries the signature. Send all the calls back first, then all the results: "FC1 + signature, FC2, FR1, FR2".
Multi step function calls: Each step's function call has its own signature. Until the user sends a new text message, pass every signature from that turn back.
Plain text conversations: Even when you do not use tools, Gemini may attach a thought signature to the final text part. Google recommends sending it back on later turns to keep the reasoning context strong, although it is not always strictly required.

Gemini 2.5 behaves differently: it puts the signature on the first part of a function call response, and returning it is optional.

If you drop or change the signature on a function call part, the API can return a 400 Bad Request error that complains about a missing or invalid thought_signature. For text parts Google recommends returning signatures rather than requiring them, but dropping them can degrade reasoning quality.

Do SDKs and tools handle thought signatures for you?

If you use the official Google SDKs for the Gemini API or Vertex AI, or tools such as Firebase AI Logic, they usually handle thought signatures automatically. As long as you pass the full message history object back without editing individual parts, the SDK will carry the thought_signature fields through for you.

You only have to manage them manually when you build custom clients, rewrite the history, or transform responses yourself, for example when streaming through queues or storing messages in your own database schema.

How do you fix missing, invalid or corrupted thought_signature errors?

All three are 400 errors that mean the signature Gemini sent you did not come back exactly as it left, so find the message you got below and fix how your code stores or replays that turn.

Function call is missing a thought_signature in functionCall parts.
Unable to submit request because thought signature is not valid.
Corrupted thought signature.

Vertex AI words the first one as "Function call <name> in the <index> content block is missing a thought_signature".

Error	Usual cause	Fix
Missing thought_signature	History rebuilt from the function name and args only	Store the original function call part and resend it unchanged
Missing thought_signature	Parallel calls and results interleaved	Reorder them as shown under "Parallel function calls" above
Missing thought_signature	Function calls that Gemini did not generate, such as history from another model	Set one of Google's placeholder signatures, listed below the table
Not valid or corrupted	A signature that was edited, or replayed from an older session, such as a resumed task or messages pasted back after compacting history	Store signatures byte for byte and don't replay old ones into a new session; start a fresh turn or use the placeholder for history you must keep

Google's placeholder values are context_engineering_is_the_way_to_go and skip_thought_signature_validator; they skip validation, and Google discourages them unless there is no other way.

The not valid and corrupted messages are not explained in Google's docs; the causes above come from public bug reports and fixes in Gemini CLI, Roo Code and the Google AI forum.

How do you fix thought_signature errors in LangChain, LiteLLM, OpenRouter or n8n?

Update the tool first, then append the model's full reply to your history instead of rebuilding it.

LangChain: Upgrade to langchain-google-genai 3.1.0 or later and pass the original AIMessage back; a new AIMessage you build yourself loses the signatures.
LiteLLM: Append the assistant message as you received it, including provider_specific_fields; LiteLLM stores the signature there or in the tool call id.
OpenRouter: Pass the reasoning_details from the previous response back unchanged and in the same order.
n8n: The AI Agent node supports Gemini signatures from n8n 2.7.0, so upgrade if you are on an older version.

Which thought_signature problems don't show an error?

Three mistakes return no error but can make Gemini's answers worse:

History from a Flash or Pro model sent to Flash-Lite: Flash-Lite drops thoughts that a non-Flash-Lite model generated. Gemini 3.5 Flash and newer models keep thoughts from previous turns by default, so send either the full history (thoughts, function calls and responses) or none of it; partial history can degrade answers.
No signature found while streaming: Without a function call, the signature can arrive in a part with empty text. Read the stream until finish_reason before saving the turn.
Text-only history: If you store only the text of each turn, Gemini cannot reuse its saved reasoning and has to reason again from scratch.

Frequently Asked Questions

Can you decode a Gemini thought signature?

No. A thought signature is a signed and encrypted representation of the model's internal reasoning state. It is intentionally opaque and is only meant to be passed back to the API unchanged.

Is a thought signature the same as chain of thought?

Not exactly. Conceptually it is a breadcrumb of the model's chain of thought, but you never see the raw reasoning. You only see the encrypted token that lets Gemini resume that reasoning later.

Do you always have to set thought_signature manually?

If you use the official Google SDKs or managed integrations and you pass the full message history back unchanged, they usually handle thought signatures for you. You only need to manage them yourself when you construct requests or transform history manually.