Generative AI Google Brain

gemini-thinking-intro-thought-signatures-rest

3 min read

Intro to thought signatures with REST API

Source notebook

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

Shows how to pass Gemini thought signatures through REST function-calling turns.

Summary

This notebook teaches how to use thought signatures with the Gemini API over cURL and the Vertex AI REST endpoint. It demonstrates a multi-turn thermostat workflow where Gemini calls a weather tool, receives a tool response, preserves thought signatures in model parts, calls a thermostat tool, and then returns a final user-friendly response.

Key code patterns

Vertex REST endpoint

MODEL_ID = "gemini-2.5-flash"
api_host = "aiplatform.googleapis.com"
if LOCATION != "global":
    api_host = f"{LOCATION}-aiplatform.googleapis.com"
API_ENDPOINT = f"{api_host}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}"

Builds the regional or global Vertex AI publisher model endpoint used by cURL generateContent calls.

Enable thinking

"generationConfig": {
  "thinking_config": {
    "include_thoughts": true
  }
}

Requests thought summaries and makes responses include thought_signature fields on function-call parts.

Declare tools

"tools": [{
  "function_declarations": [
    {"name": "get_current_temperature", "parameters": {...}},
    {"name": "set_thermostat_temperature", "parameters": {...}}
  ]
}]

Lets Gemini choose between weather lookup and thermostat-setting function calls.

Preserve signature

{
  "role": "model",
  "parts": [{
    "function_call": {"name": "get_current_temperature", "args": {"location": "London"}},
    "thought_signature": "${THOUGHT_SIGNATURE_1}"
  }]
}

Sends the thought signature back inside its original model Part so reasoning context is preserved.

Models & APIs used

When to use this

Use this pattern when building REST-based Gemini function-calling flows that need coherent multi-turn reasoning across tool calls.

Gotchas & caveats

  • Requires a Google Cloud project with the Vertex AI API enabled.
  • Colab authentication is only run when google.colab is present.
  • LOCATION defaults to global but changes the API host when set to a regional value.
  • The notebook installs jq and shells out to gcloud auth print-access-token for REST calls.
  • When manually editing history, send each thought_signature back inside its original Part.
  • Do not merge signed Parts with unsigned Parts or combine two signed Parts.

Best practices

  • Set GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_REGION before constructing the endpoint.
  • Use function_declarations with explicit parameters and required fields.
  • Include thought signatures when sending function execution results back to the model.
  • Keep the full conversation history when requesting the final response.
  • Clean up generated response*.json files after the tutorial.

Graph View

Backlinks