If you call Gemini 3 Pro 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.

How thought_signature works in Gemini 3 Pro

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 can cause 400 errors and weaker tool reasoning.

What is a thought signature in Gemini 3 Pro?

In Gemini 3 Pro, 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 Gemini and Vertex AI APIs, 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.

A simplified 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 3 Pro use thought signatures?

Gemini 3 Pro is a thinking model 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?

For Gemini 3 Pro you must preserve thought signatures any time you are building the conversation history yourself, especially when tools or function calls are involved.

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.
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.

If you drop the field or change it, Gemini 3 Pro can return a 400 Bad Request error that complains about a missing or invalid thought_signature, and tool performance or reasoning quality can degrade.

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.

What common errors can you see with thought signatures?

The most common issues show up when you modify or drop thought signatures while replaying history:

Missing thought_signature on a function call: The follow up request can fail with a 400 error that mentions a missing thought_signature for a function call part.
Edited or regenerated signatures: If you change the value, the signature no longer matches the internal state, so the server can reject the request or the model can lose its chain of reasoning.
Custom history without signatures: If you construct your own message history and only store text, later turns cannot reuse the saved reasoning state and Gemini has to reason again from scratch for that context.

Frequently Asked Questions

Can you decode a thought signature from Gemini 3 Pro?

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.

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