A thought signature, in Google’s Gemini API, is an encrypted representation of the model’s internal thought process. The API returns it with the model’s output, and the application passes it back to the model in subsequent API calls; doing so is what lets the model maintain its chain of reasoning across a conversation. Google presents this as critical for complex, multi-step agentic workflows, where it says preserving the “why” behind a decision is just as important as the decision itself.
Usage
According to New Gemini API updates for Gemini 3, the API began enforcing the return of thought signatures starting with Gemini 3, and how strictly it validates them depends on the kind of request:
- Function calling validates signatures strictly on the current turn; a missing signature results in a 400 error.
- Text and chat generation does not strictly enforce them, but omitting them degrades the model’s reasoning and answer quality.
- Image generation and editing validates strictly for all model parts, including a
thoughtSignature; a missing signature results in a 400 error.
Applications that use the official SDKs with standard chat history do not need to handle signatures themselves, since the SDKs do so automatically.