{ "cells": [ { "cell_type": "code", "execution_count": null, "metadata": { "cellView": "form", "id": "sqi5B7V_Rjim" }, "outputs": [], "source": [ "# @title Copyright 2025 Google LLC\n", "#\n", "# Licensed under the Apache License, Version 2.0 (the \"License\");\n", "# you may not use this file except in compliance with the License.\n", "# You may obtain a copy of the License at\n", "#\n", "# https://www.apache.org/licenses/LICENSE-2.0\n", "#\n", "# Unless required by applicable law or agreed to in writing, software\n", "# distributed under the License is distributed on an \"AS IS\" BASIS,\n", "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", "# See the License for the specific language governing permissions and\n", "# limitations under the License." ] }, { "cell_type": "markdown", "metadata": { "id": "VyPmicX9RlZX" }, "source": [ "# Intro to thought signatures with REST API\n", "\n", "\n", " \n", " \n", " \n", " \n", "
\n", " \n", " \"Google
Open in Colab\n", " \n", " 		\n", " \n", " \"Google
Open in Colab Enterprise\n", " \n", " 		\n", " \n", " \"Vertex
Open in Vertex AI Workbench\n", " \n", " 		\n", " \n", " \"GitHub
View on GitHub\n", " \n", "
\n", "\n", "

\n", "Share to:\n", "\n", "\n", " \"LinkedIn\n", "\n", "\n", "\n", " \"Bluesky\n", "\n", "\n", "\n", " \"X\n", "\n", "\n", "\n", " \"Reddit\n", "\n", "\n", "\n", " \"Facebook\n", "\n", "

" ] }, { "cell_type": "markdown", "metadata": { "id": "8MqT58L6Rm_q" }, "source": [ "| Authors |\n", "| --- |\n", "| [Eric Dong](https://github.com/gericdong) |" ] }, { "cell_type": "markdown", "metadata": { "id": "nVxnv1D5RoZw" }, "source": [ "## Overview\n", "\n", "A thought signature is an encrypted representation of the model's internal reasoning process for a given turn in a conversation. By passing this signature back to the model in subsequent requests, you provide it with the context of its previous thoughts, allowing it to build upon its reasoning and maintain a coherent line of inquiry.\n", "\n", "This tutorial explores how to use the thought signatures feature of the Gemini API with cURL and the REST API." ] }, { "cell_type": "markdown", "metadata": { "id": "gPiTOAHURvTM" }, "source": [ "## Getting Started" ] }, { "cell_type": "markdown", "metadata": { "id": "5f7c203ffaa1" }, "source": [ "### Install required libraries" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "4e66b2f6d36f" }, "outputs": [], "source": [ "%%capture\n", "\n", "!sudo apt install -q jq" ] }, { "cell_type": "markdown", "metadata": { "id": "dmWOrTJ3gx13" }, "source": [ "### Authenticate your notebook environment (Colab only)\n", "\n", "If you are running this notebook on Google Colab, run the following cell to authenticate your environment." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "NyKGtVQjgx13" }, "outputs": [], "source": [ "import sys\n", "\n", "if \"google.colab\" in sys.modules:\n", " from google.colab import auth\n", "\n", " auth.authenticate_user()" ] }, { "cell_type": "markdown", "metadata": { "id": "O6ZGaZlxP9L0" }, "source": [ "### Set Google Cloud project\n", "\n", "To get started using Vertex AI, you must have an existing Google Cloud project and [enable the Vertex AI API](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com).\n", "\n", "Learn more about [setting up a project and a development environment](https://cloud.google.com/vertex-ai/docs/start/cloud-environment)." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "u8IivOG5SqY6" }, "outputs": [], "source": [ "import os\n", "\n", "# fmt: off\n", "PROJECT_ID = \"[your-project-id]\" # @param {type: \"string\", placeholder: \"[your-project-id]\", isTemplate: true}\n", "# fmt: on\n", "if not PROJECT_ID or PROJECT_ID == \"[your-project-id]\":\n", " PROJECT_ID = str(os.environ.get(\"GOOGLE_CLOUD_PROJECT\"))\n", "\n", "LOCATION = os.environ.get(\"GOOGLE_CLOUD_REGION\", \"global\")\n", "\n", "os.environ[\"GOOGLE_CLOUD_PROJECT\"] = PROJECT_ID\n", "os.environ[\"GOOGLE_CLOUD_REGION\"] = LOCATION" ] }, { "cell_type": "markdown", "metadata": { "id": "854fbf388e2b" }, "source": [ "## Use the Gemini 2.5 Flash model" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "7eeb063ac6d4" }, "outputs": [], "source": [ "MODEL_ID = \"gemini-2.5-flash\"\n", "\n", "api_host = \"aiplatform.googleapis.com\"\n", "if LOCATION != \"global\":\n", " api_host = f\"{LOCATION}-aiplatform.googleapis.com\"\n", "\n", "os.environ[\"API_ENDPOINT\"] = (\n", " f\"{api_host}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}\"\n", ")\n", "API_ENDPOINT = os.environ[\"API_ENDPOINT\"]" ] }, { "cell_type": "markdown", "metadata": { "id": "37CH91ddY9kG" }, "source": [ "## Use Thought Signatures\n", "\n", "When thinking is enabled, the API response includes a `thought_signature` field containing an encrypted representation of the model's reasoning. When a function's execution result is sent back to the server, including the `thought_signature` allows the model to restore its previous thinking context, which will likely improve function calling performance.\n", "\n", "Optionally, to enable thought summaries, include the `\"thinking_config\": { \"include_thoughts\": true }` object in your request body. " ] }, { "cell_type": "markdown", "metadata": { "id": "hlVCCsncIlYJ" }, "source": [ "## Example: Conditional Thermostat Control\n", "\n", "In this scenario, a user wants to set a thermostat based on the current weather. The request is: \"If it's too hot or too cold in London, set the thermostat to a comfortable temperature.\"\n", "\n", "This requires the model to:\n", "\n", "- Call a tool to get the weather in London.\n", "- Use the returned weather information to decide if another tool needs to be called.\n", "- Call the tool to set the thermostat if the condition is met." ] }, { "cell_type": "markdown", "metadata": { "id": "vTWbrR1RJP_K" }, "source": [ "### **Step 1**: First Turn - Get the Weather\n", "\n", "We send the initial prompt to the model, along with the definitions of the tools it can use and the configuration to enable thinking. We expect it to call the `get_current_temperature` function and return a thought signature to maintain the context of the user's conditional request." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "id": "p8-eTvw5oDE8" }, "outputs": [], "source": [ "%%bash\n", "\n", "curl -X POST \\\n", "-H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n", "-H \"Content-Type: application/json\" \\\n", "https://${API_ENDPOINT}:generateContent \\\n", "-d @- \\\n", "> response1.json 2>/dev/null < response2.json 2>/dev/null < response3.json 2>/dev/null <