Generative AI Google Brain

gemini-thinking-intro-thought-signatures

2 min read

Intro to thought signatures

Source notebook

Repo path: gemini/thinking/intro_thought_signatures.ipynb · Open on GitHub · intermediate

Shows how Gemini thought signatures preserve reasoning context across multi-turn function calling.

Summary

This notebook teaches the Gemini API thought signatures feature using the Google Gen AI SDK on Vertex AI. It walks through a conditional thermostat workflow where Gemini first calls a weather function, then receives the tool result plus prior model content containing the thought signature, then decides whether to call a thermostat function and generate a final response.

Key code patterns

Create Vertex AI GenAI client

from google import genai
 
client = genai.Client(
    vertexai=True,
    project=PROJECT_ID,
    location="global",
)

Connects the Google Gen AI SDK to the generative AI service on Vertex AI.

Declare function tools

thermostat_tools = Tool(
    function_declarations=[
        get_weather_declaration,
        set_thermostat_declaration,
    ]
)

Gives the model two callable functions and lets it choose which tool to invoke.

Enable thinking with tools

config = GenerateContentConfig(
    tools=[thermostat_tools],
    thinking_config=ThinkingConfig(
        include_thoughts=True,
    ),
)

Requests tool use with thinking enabled so responses can include thought summaries and thought signatures.

Return tool result with history

contents.append(response_turn_1.candidates[0].content)
contents.append(Content(
    role="tool",
    parts=[Part.from_function_response(
        name=tool_call_1.name,
        response=result_1,
    )],
))

Preserves the prior model turn, including its thought signature, before sending the function response back.

Models & APIs used

  • Models: gemini-2.5-flash
  • APIs / services: Vertex AI, Gemini API
  • SDKs / libraries: google-genai

When to use this

Use this pattern for multi-turn Gemini workflows where sequential tool calls depend on earlier reasoning and tool results.

Gotchas & caveats

  • Requires Google Cloud project authentication or Vertex AI API Key Express Mode.
  • PROJECT_ID must be set directly or via GOOGLE_CLOUD_PROJECT.
  • Notebook uses LOCATION = “global”.
  • include_thoughts can only be enabled when thinking is enabled.
  • The functions are mock implementations, not real weather or thermostat APIs.

Best practices

  • Pass the model’s previous response content back into contents so the thought signature is preserved.
  • Send function execution results as role=“tool” with Part.from_function_response.
  • Group related function declarations in a Tool so the model can choose the needed function.
  • Use thought signatures for multi-turn interactions with external tools that require reasoning context.

Graph View

Backlinks