Merge branch 'main' into feat/eager-table-preparation

Author: ferponse

.github/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.27.1"
+  ".": "1.27.2"
 }

CHANGELOG.md

@@ -1,7 +1,11 @@
 # Changelog
 
+## [1.27.2](https://github.com/google/adk-python/compare/v1.27.1...v1.27.2) (2026-03-17)
+### Bug Fixes
+  * Use valid dataplex OAuth scope for BigQueryToolset ([4010716](https://github.com/google/adk-python/commit/4010716470fc83918dc367c5971342ff551401c8))
+  * Store and retrieve usage_metadata in Vertex AI custom_metadata ([b318eee](https://github.com/google/adk-python/commit/b318eee979b1625d3d23ad98825c88f54016a12f))
 
-## [1.27.1](https://github.com/google/adk-python/compare/v1.26.0...v1.27.0) (2026-03-13)
+## [1.27.1](https://github.com/google/adk-python/compare/v1.27.0...v1.27.1) (2026-03-13)
 ### Bug Fixes
   * Rolling back change to fix issue affecting LlmAgent creation due to missing version field ([0e18f81](https://github.com/google/adk-python/commit/0e18f81a5cd0d0392ded653b1a63a236449a2685))
 

contributing/samples/adk_triaging_agent/agent.py

@@ -26,15 +26,14 @@
 import requests
 
 LABEL_TO_OWNER = {
-    "a2a": "seanzhou1023",
     "agent engine": "yeesian",
-    "auth": "seanzhou1023",
+    "auth": "xuanyang15",
     "bq": "shobsi",
     "core": "Jacksunwei",
     "documentation": "joefernandez",
     "eval": "ankursharmas",
-    "live": "seanzhou1023",
-    "mcp": "seanzhou1023",
+    "live": "wuliang229",
+    "mcp": "wukath",
     "models": "xuanyang15",
     "services": "DeanChensj",
     "tools": "xuanyang15",

contributing/samples/spanner_admin/README.md

@@ -0,0 +1,116 @@
+# Spanner Admin Tools Sample
+
+## Introduction
+
+This sample agent demonstrates the Spanner first-party tools in ADK,
+distributed via the `google.adk.tools.spanner` module. These tools include:
+
+1. `list_instances`
+
+  Fetches Spanner instance names present in a project.
+
+1. `get_instance`
+
+  Fetches details of a given Spanner instance.
+
+1. `create_database`
+
+  Creates a Spanner database within a given instance and project.
+
+1. `list_databases`
+
+  Fetches Spanner database names present in an instance.
+
+1. `create_instance`
+
+  Creates a Spanner instance within a GCP project.
+
+1. `list_instance_configs`
+
+  Fetches Spanner instance configurations available for a project.
+
+1. `get_instance_config`
+
+  Fetches details of a Spanner instance configuration.
+
+## How to use
+
+Set up environment variables in your `.env` file for using
+[Google AI Studio](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-ai-studio)
+or
+[Google Cloud Vertex AI](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai)
+for the LLM service for your agent. For example, for using Google AI Studio you
+would set:
+
+* GOOGLE_GENAI_USE_VERTEXAI=FALSE
+* GOOGLE_API_KEY={your api key}
+
+### With Application Default Credentials
+
+This mode is useful for quick development when the agent builder is the only
+user interacting with the agent. The tools are run with these credentials.
+
+1. Create application default credentials on the machine where the agent would
+be running by following https://cloud.google.com/docs/authentication/provide-credentials-adc.
+
+1. Set `CREDENTIALS_TYPE=None` in `agent.py`
+
+1. Run the agent
+
+### With Service Account Keys
+
+This mode is useful for quick development when the agent builder wants to run
+the agent with service account credentials. The tools are run with these
+credentials.
+
+1. Create service account key by following https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys.
+
+1. Set `CREDENTIALS_TYPE=AuthCredentialTypes.SERVICE_ACCOUNT` in `agent.py`
+
+1. Download the key file and replace `"service_account_key.json"` with the path
+
+1. Run the agent
+
+### With Interactive OAuth
+
+1. Follow
+https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name.
+to get your client id and client secret. Be sure to choose "web" as your client
+type.
+
+1.  Follow https://developers.google.com/workspace/guides/configure-oauth-consent
+    to add scope "https://www.googleapis.com/auth/spanner.data" and
+    "https://www.googleapis.com/auth/spanner.admin" as declaration, this is used
+    for review purpose.
+
+1.  Follow
+    https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred
+    to add http://localhost/dev-ui/ to "Authorized redirect URIs".
+
+    Note: localhost here is just a hostname that you use to access the dev ui,
+    replace it with the actual hostname you use to access the dev ui.
+
+1.  For 1st run, allow popup for localhost in Chrome.
+
+1.  Configure your `.env` file to add two more variables before running the
+    agent:
+
+    *   OAUTH_CLIENT_ID={your client id}
+    *   OAUTH_CLIENT_SECRET={your client secret}
+
+    Note: don't create a separate .env, instead put it to the same .env file that
+    stores your Vertex AI or Dev ML credentials
+
+1.  Set `CREDENTIALS_TYPE=AuthCredentialTypes.OAUTH2` in `agent.py` and run the
+    agent
+
+## Sample prompts
+
+* Show me all Spanner instances in my project.
+* Give me details about the 'my-instance' Spanner instance.
+* List all databases in instance 'my-instance'.
+* Create a new Spanner database named 'my-db' in instance 'my-instance'.
+* List all instance configurations available for my project.
+* Get details about 'regional-us-central1' configuration.
+* Create a Spanner instance 'new-instance' with 'regional-us-central1' config and name 'new-instance'.
+

contributing/samples/spanner_admin/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import agent

contributing/samples/spanner_admin/agent.py

@@ -0,0 +1,77 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+
+from google.adk.agents.llm_agent import LlmAgent
+from google.adk.auth.auth_credential import AuthCredentialTypes
+from google.adk.tools.spanner.admin_toolset import SpannerAdminToolset
+from google.adk.tools.spanner.spanner_credentials import SpannerCredentialsConfig
+import google.auth
+
+# Define an appropriate credential type
+# Set to None to use the application default credentials (ADC) for a quick
+# development.
+CREDENTIALS_TYPE = None
+
+if CREDENTIALS_TYPE == AuthCredentialTypes.OAUTH2:
+  # Initialize the tools to do interactive OAuth
+  # The environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET
+  # must be set
+  credentials_config = SpannerCredentialsConfig(
+      client_id=os.getenv("OAUTH_CLIENT_ID"),
+      client_secret=os.getenv("OAUTH_CLIENT_SECRET"),
+      scopes=[
+          "https://www.googleapis.com/auth/spanner.admin",
+          "https://www.googleapis.com/auth/spanner.data",
+      ],
+  )
+elif CREDENTIALS_TYPE == AuthCredentialTypes.SERVICE_ACCOUNT:
+  # Initialize the tools to use the credentials in the service account key.
+  # If this flow is enabled, make sure to replace the file path with your own
+  # service account key file
+  # https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys
+  creds, _ = google.auth.load_credentials_from_file("service_account_key.json")
+  credentials_config = SpannerCredentialsConfig(credentials=creds)
+else:
+  # Initialize the tools to use the application default credentials.
+  # https://cloud.google.com/docs/authentication/provide-credentials-adc
+  application_default_credentials, _ = google.auth.default()
+  credentials_config = SpannerCredentialsConfig(
+      credentials=application_default_credentials
+  )
+
+spanner_admin_toolset = SpannerAdminToolset(
+    credentials_config=credentials_config,
+)
+
+# The variable name `root_agent` determines what your root agent is for the
+# debug CLI
+root_agent = LlmAgent(
+    model="gemini-2.5-flash",
+    name="spanner_admin_agent",
+    description=(
+        "Agent to perform Spanner admin tasks and answer questions about"
+        " Spanner databases."
+    ),
+    instruction="""\
+        You are a Spanner admin agent with access to several Spanner admin tools.
+        Make use of those tools to answer user's questions and perform admin
+        tasks like listing instances or databases.
+    """,
+    tools=[
+        # Use tools from Spanner admin toolset.
+        spanner_admin_toolset,
+    ],
+)

src/google/adk/features/_feature_registry.py

@@ -45,6 +45,7 @@ class FeatureName(str, Enum):
   PUBSUB_TOOLSET = "PUBSUB_TOOLSET"
   SKILL_TOOLSET = "SKILL_TOOLSET"
   SPANNER_TOOLSET = "SPANNER_TOOLSET"
+  SPANNER_ADMIN_TOOLSET = "SPANNER_ADMIN_TOOLSET"
   SPANNER_TOOL_SETTINGS = "SPANNER_TOOL_SETTINGS"
   SPANNER_VECTOR_STORE = "SPANNER_VECTOR_STORE"
   TOOL_CONFIG = "TOOL_CONFIG"
@@ -136,6 +137,9 @@ class FeatureConfig:
     FeatureName.SKILL_TOOLSET: FeatureConfig(
         FeatureStage.EXPERIMENTAL, default_on=True
     ),
+    FeatureName.SPANNER_ADMIN_TOOLSET: FeatureConfig(
+        FeatureStage.EXPERIMENTAL, default_on=True
+    ),
     FeatureName.SPANNER_TOOLSET: FeatureConfig(
         FeatureStage.EXPERIMENTAL, default_on=True
     ),

src/google/adk/models/lite_llm.py

@@ -384,8 +384,42 @@ def _iter_reasoning_texts(reasoning_value: Any) -> Iterable[str]:
     yield str(reasoning_value)
 
 
+def _is_thinking_blocks_format(reasoning_value: Any) -> bool:
+  """Returns True if reasoning_value is Anthropic thinking_blocks format.
+
+  Anthropic thinking_blocks is a list of dicts, each with 'type', 'thinking',
+  and 'signature' keys.
+  """
+  if not isinstance(reasoning_value, list) or not reasoning_value:
+    return False
+  first = reasoning_value[0]
+  return isinstance(first, dict) and "signature" in first
+
+
 def _convert_reasoning_value_to_parts(reasoning_value: Any) -> List[types.Part]:
-  """Converts provider reasoning payloads into Gemini thought parts."""
+  """Converts provider reasoning payloads into Gemini thought parts.
+
+  Handles Anthropic thinking_blocks (list of dicts with type/thinking/signature)
+  by preserving the signature on each part's thought_signature field. This is
+  required for Anthropic to maintain thinking across tool call boundaries.
+  """
+  if _is_thinking_blocks_format(reasoning_value):
+    parts: List[types.Part] = []
+    for block in reasoning_value:
+      if not isinstance(block, dict):
+        continue
+      block_type = block.get("type", "")
+      if block_type == "redacted":
+        continue
+      thinking_text = block.get("thinking", "")
+      signature = block.get("signature", "")
+      if not thinking_text:
+        continue
+      part = types.Part(text=thinking_text, thought=True)
+      if signature:
+        part.thought_signature = signature.encode("utf-8")
+      parts.append(part)
+    return parts
   return [
       types.Part(text=text, thought=True)
       for text in _iter_reasoning_texts(reasoning_value)
@@ -396,12 +430,19 @@ def _convert_reasoning_value_to_parts(reasoning_value: Any) -> List[types.Part]:
 def _extract_reasoning_value(message: Message | Delta | None) -> Any:
   """Fetches the reasoning payload from a LiteLLM message.
 
-  Checks for both 'reasoning_content' (LiteLLM standard, used by Azure/Foundry,
-  Ollama via LiteLLM) and 'reasoning' (used by LM Studio, vLLM).
-  Prioritizes 'reasoning_content' when both are present.
+  Checks for 'thinking_blocks' (Anthropic structured format with signatures),
+  'reasoning_content' (LiteLLM standard, used by Azure/Foundry, Ollama via
+  LiteLLM) and 'reasoning' (used by LM Studio, vLLM).
+  Prioritizes 'thinking_blocks' when present (Anthropic models), then
+  'reasoning_content', then 'reasoning'.
   """
   if message is None:
     return None
+  # Anthropic models return thinking_blocks with type/thinking/signature fields.
+  # This must be preserved to maintain thinking across tool call boundaries.
+  thinking_blocks = message.get("thinking_blocks")
+  if thinking_blocks is not None:
+    return thinking_blocks
   reasoning_content = message.get("reasoning_content")
   if reasoning_content is not None:
     return reasoning_content
@@ -835,6 +876,30 @@ async def _content_to_message_param(
           else final_content
       )
 
+    # For Anthropic models, rebuild thinking_blocks with signatures so that
+    # thinking is preserved across tool call boundaries. Without this,
+    # Anthropic silently drops thinking after the first turn.
+    if model and _is_anthropic_model(model) and reasoning_parts:
+      thinking_blocks = []
+      for part in reasoning_parts:
+        if part.text and part.thought_signature:
+          sig = part.thought_signature
+          if isinstance(sig, bytes):
+            sig = sig.decode("utf-8")
+          thinking_blocks.append({
+              "type": "thinking",
+              "thinking": part.text,
+              "signature": sig,
+          })
+      if thinking_blocks:
+        msg = ChatCompletionAssistantMessage(
+            role=role,
+            content=final_content,
+            tool_calls=tool_calls or None,
+        )
+        msg["thinking_blocks"] = thinking_blocks  # type: ignore[typeddict-unknown-key]
+        return msg
+
     reasoning_texts = []
     for part in reasoning_parts:
       if part.text:
@@ -1943,6 +2008,31 @@ def _build_request_log(req: LlmRequest) -> str:
 """
 
 
+def _is_anthropic_model(model_string: str) -> bool:
+  """Check if the model is an Anthropic Claude model accessed via LiteLLM.
+
+  Detects models using the anthropic/ provider prefix, bedrock/ models that
+  contain 'anthropic' or 'claude', and vertex_ai/ models that contain 'claude'.
+
+  Args:
+    model_string: A LiteLLM model string (e.g., "anthropic/claude-4-sonnet",
+      "bedrock/anthropic.claude-3-5-sonnet", "vertex_ai/claude-4-sonnet")
+
+  Returns:
+    True if it's an Anthropic Claude model, False otherwise.
+  """
+  lower = model_string.lower()
+  if lower.startswith("anthropic/"):
+    return True
+  if lower.startswith("bedrock/"):
+    model_part = lower.split("/", 1)[1]
+    return "anthropic" in model_part or "claude" in model_part
+  if lower.startswith("vertex_ai/"):
+    model_part = lower.split("/", 1)[1]
+    return "claude" in model_part
+  return False
+
+
 def _is_litellm_vertex_model(model_string: str) -> bool:
   """Check if the model is a Vertex AI model accessed via LiteLLM.