google-adk 1.1.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

google/adk/telemetry.py

@@ -21,6 +21,8 @@
 #    Agent Development Kit should be focused on the higher-level
 #    constructs of the framework that are not observable by the SDK.
 
+from __future__ import annotations
+
 import json
 from typing import Any
 
@@ -31,51 +33,113 @@ from .agents.invocation_context import InvocationContext
 from .events.event import Event
 from .models.llm_request import LlmRequest
 from .models.llm_response import LlmResponse
+from .tools.base_tool import BaseTool
 
 tracer = trace.get_tracer('gcp.vertex.agent')
 
 
+def _safe_json_serialize(obj) -> str:
+  """Convert any Python object to a JSON-serializable type or string.
+
+  Args:
+    obj: The object to serialize.
+
+  Returns:
+    The JSON-serialized object string or <non-serializable> if the object cannot be serialized.
+  """
+
+  try:
+    # Try direct JSON serialization first
+    return json.dumps(
+        obj, ensure_ascii=False, default=lambda o: '<not serializable>'
+    )
+  except (TypeError, OverflowError):
+    return '<not serializable>'
+
+
 def trace_tool_call(
+    tool: BaseTool,
     args: dict[str, Any],
+    function_response_event: Event,
 ):
   """Traces tool call.
 
   Args:
+    tool: The tool that was called.
     args: The arguments to the tool call.
+    function_response_event: The event with the function response details.
   """
   span = trace.get_current_span()
   span.set_attribute('gen_ai.system', 'gcp.vertex.agent')
-  span.set_attribute('gcp.vertex.agent.tool_call_args', json.dumps(args))
+  span.set_attribute('gen_ai.operation.name', 'execute_tool')
+  span.set_attribute('gen_ai.tool.name', tool.name)
+  span.set_attribute('gen_ai.tool.description', tool.description)
+  tool_call_id = '<not specified>'
+  tool_response = '<not specified>'
+  if function_response_event.content.parts:
+    function_response = function_response_event.content.parts[
+        0
+    ].function_response
+    if function_response is not None:
+      tool_call_id = function_response.id
+      tool_response = function_response.response
 
+  span.set_attribute('gen_ai.tool.call.id', tool_call_id)
 
-def trace_tool_response(
-    invocation_context: InvocationContext,
-    event_id: str,
+  if not isinstance(tool_response, dict):
+    tool_response = {'result': tool_response}
+  span.set_attribute(
+      'gcp.vertex.agent.tool_call_args',
+      _safe_json_serialize(args),
+  )
+  span.set_attribute('gcp.vertex.agent.event_id', function_response_event.id)
+  span.set_attribute(
+      'gcp.vertex.agent.tool_response',
+      _safe_json_serialize(tool_response),
+  )
+  # Setting empty llm request and response (as UI expect these) while not
+  # applicable for tool_response.
+  span.set_attribute('gcp.vertex.agent.llm_request', '{}')
+  span.set_attribute(
+      'gcp.vertex.agent.llm_response',
+      '{}',
+  )
+
+
+def trace_merged_tool_calls(
+    response_event_id: str,
     function_response_event: Event,
 ):
-  """Traces tool response event.
+  """Traces merged tool call events.
 
-  This function records details about the tool response event as attributes on
-  the current OpenTelemetry span.
+  Calling this function is not needed for telemetry purposes. This is provided
+  for preventing /debug/trace requests (typically sent by web UI).
 
   Args:
-    invocation_context: The invocation context for the current agent run.
-    event_id: The ID of the event.
-    function_response_event: The function response event which can be either
-      merged function response for parallel function calls or individual
-      function response for sequential function calls.
+    response_event_id: The ID of the response event.
+    function_response_event: The merged response event.
   """
+
   span = trace.get_current_span()
   span.set_attribute('gen_ai.system', 'gcp.vertex.agent')
-  span.set_attribute(
-      'gcp.vertex.agent.invocation_id', invocation_context.invocation_id
-  )
-  span.set_attribute('gcp.vertex.agent.event_id', event_id)
+  span.set_attribute('gen_ai.operation.name', 'execute_tool')
+  span.set_attribute('gen_ai.tool.name', '(merged tools)')
+  span.set_attribute('gen_ai.tool.description', '(merged tools)')
+  span.set_attribute('gen_ai.tool.call.id', response_event_id)
+
+  span.set_attribute('gcp.vertex.agent.tool_call_args', 'N/A')
+  span.set_attribute('gcp.vertex.agent.event_id', response_event_id)
+  try:
+    function_response_event_json = function_response_event.model_dumps_json(
+        exclude_none=True
+    )
+  except Exception:  # pylint: disable=broad-exception-caught
+    function_response_event_json = '<not serializable>'
+
   span.set_attribute(
       'gcp.vertex.agent.tool_response',
-      function_response_event.model_dump_json(exclude_none=True),
+      function_response_event_json,
   )
-
   # Setting empty llm request and response (as UI expect these) while not
   # applicable for tool_response.
   span.set_attribute('gcp.vertex.agent.llm_request', '{}')
@@ -117,15 +181,18 @@ def trace_call_llm(
   # Consider removing once GenAI SDK provides a way to record this info.
   span.set_attribute(
       'gcp.vertex.agent.llm_request',
-      json.dumps(
-          _build_llm_request_for_trace(llm_request),
-          default=lambda o: '<not serializable>',
-      ),
+      _safe_json_serialize(_build_llm_request_for_trace(llm_request)),
   )
   # Consider removing once GenAI SDK provides a way to record this info.
+
+  try:
+    llm_response_json = llm_response.model_dump_json(exclude_none=True)
+  except Exception:  # pylint: disable=broad-exception-caught
+    llm_response_json = '<not serializable>'
+
   span.set_attribute(
       'gcp.vertex.agent.llm_response',
-      llm_response.model_dump_json(exclude_none=True),
+      llm_response_json,
   )
 
 
@@ -153,7 +220,7 @@ def trace_send_data(
   # information still needs to be recorded by the Agent Development Kit.
   span.set_attribute(
       'gcp.vertex.agent.data',
-      json.dumps([
+      _safe_json_serialize([
           types.Content(role=content.role, parts=content.parts).model_dump(
               exclude_none=True
           )

google/adk/tools/_automatic_function_calling_util.py

@@ -12,10 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Forked from google3/third_party/py/google/genai/_automatic_function_calling_util.py temporarily."""
+from __future__ import annotations
 
 import inspect
 from types import FunctionType
+import typing
 from typing import Any
 from typing import Callable
 from typing import Dict
@@ -29,7 +30,8 @@ from pydantic import BaseModel
 from pydantic import create_model
 from pydantic import fields as pydantic_fields
 
-from . import function_parameter_parse_util
+from . import _function_parameter_parse_util
+from ..utils.variant_utils import GoogleLLMVariant
 
 _py_type_2_schema_type = {
     'str': types.Type.STRING,
@@ -193,7 +195,7 @@ def _get_return_type(func: Callable) -> Any:
 def build_function_declaration(
     func: Union[Callable, BaseModel],
     ignore_params: Optional[list[str]] = None,
-    variant: Literal['GOOGLE_AI', 'VERTEX_AI', 'DEFAULT'] = 'GOOGLE_AI',
+    variant: GoogleLLMVariant = GoogleLLMVariant.GEMINI_API,
 ) -> types.FunctionDeclaration:
   signature = inspect.signature(func)
   should_update_signature = False
@@ -227,6 +229,7 @@ def build_function_declaration(
           func.__closure__,
       )
       new_func.__signature__ = new_sig
+      new_func.__doc__ = func.__doc__
 
   return (
       from_function_with_options(func, variant)
@@ -289,16 +292,9 @@ def build_function_declaration_util(
 
 def from_function_with_options(
     func: Callable,
-    variant: Literal['GOOGLE_AI', 'VERTEX_AI', 'DEFAULT'] = 'GOOGLE_AI',
+    variant: GoogleLLMVariant = GoogleLLMVariant.GEMINI_API,
 ) -> 'types.FunctionDeclaration':
 
-  supported_variants = ['GOOGLE_AI', 'VERTEX_AI', 'DEFAULT']
-  if variant not in supported_variants:
-    raise ValueError(
-        f'Unsupported variant: {variant}. Supported variants are:'
-        f' {", ".join(supported_variants)}'
-    )
-
   parameters_properties = {}
   for name, param in inspect.signature(func).parameters.items():
     if param.kind in (
@@ -306,7 +302,11 @@ def from_function_with_options(
         inspect.Parameter.KEYWORD_ONLY,
         inspect.Parameter.POSITIONAL_ONLY,
     ):
-      schema = function_parameter_parse_util._parse_schema_from_parameter(
+      # This snippet catches the case when type hints are stored as strings
+      if isinstance(param.annotation, str):
+        param = param.replace(annotation=typing.get_type_hints(func)[name])
+
+      schema = _function_parameter_parse_util._parse_schema_from_parameter(
           variant, param, func.__name__
       )
       parameters_properties[name] = schema
@@ -319,27 +319,33 @@ def from_function_with_options(
         type='OBJECT',
         properties=parameters_properties,
     )
-    if variant == 'VERTEX_AI':
-      declaration.parameters.required = (
-          function_parameter_parse_util._get_required_fields(
-              declaration.parameters
-          )
-      )
-  if not variant == 'VERTEX_AI':
+    declaration.parameters.required = (
+        _function_parameter_parse_util._get_required_fields(
+            declaration.parameters
+        )
+    )
+  if variant == GoogleLLMVariant.GEMINI_API:
     return declaration
 
   return_annotation = inspect.signature(func).return_annotation
   if return_annotation is inspect._empty:
     return declaration
 
+  return_value = inspect.Parameter(
+      'return_value',
+      inspect.Parameter.POSITIONAL_OR_KEYWORD,
+      annotation=return_annotation,
+  )
+  # This snippet catches the case when type hints are stored as strings
+  if isinstance(return_value.annotation, str):
+    return_value = return_value.replace(
+        annotation=typing.get_type_hints(func)['return']
+    )
+
   declaration.response = (
-      function_parameter_parse_util._parse_schema_from_parameter(
+      _function_parameter_parse_util._parse_schema_from_parameter(
           variant,
-          inspect.Parameter(
-              'return_value',
-              inspect.Parameter.POSITIONAL_OR_KEYWORD,
-              annotation=return_annotation,
-          ),
+          return_value,
           func.__name__,
       )
   )

google/adk/tools/{function_parameter_parse_util.py → _function_parameter_parse_util.py}

@@ -13,6 +13,8 @@
 # limitations under the License.
 #
 
+from __future__ import annotations
+
 import inspect
 import logging
 import types as typing_types
@@ -26,6 +28,8 @@ from typing import Union
 from google.genai import types
 import pydantic
 
+from ..utils.variant_utils import GoogleLLMVariant
+
 _py_builtin_type_to_schema_type = {
     str: types.Type.STRING,
     int: types.Type.INTEGER,
@@ -61,8 +65,10 @@ def _update_for_default_if_mldev(schema: types.Schema):
     )
 
 
-def _raise_if_schema_unsupported(variant: str, schema: types.Schema):
-  if not variant == 'VERTEX_AI':
+def _raise_if_schema_unsupported(
+    variant: GoogleLLMVariant, schema: types.Schema
+):
+  if variant == GoogleLLMVariant.GEMINI_API:
     _raise_for_any_of_if_mldev(schema)
     _update_for_default_if_mldev(schema)
 
@@ -114,7 +120,7 @@ def _is_default_value_compatible(
 
 
 def _parse_schema_from_parameter(
-    variant: str, param: inspect.Parameter, func_name: str
+    variant: GoogleLLMVariant, param: inspect.Parameter, func_name: str
 ) -> types.Schema:
   """parse schema from parameter.
 

google/adk/tools/_gemini_schema_util.py

@@ -0,0 +1,158 @@
+# Copyright 2025 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 __future__ import annotations
+
+import re
+from typing import Any
+from typing import Optional
+
+from google.genai.types import JSONSchema
+from google.genai.types import Schema
+from pydantic import Field
+
+from ..utils.variant_utils import get_google_llm_variant
+
+
+class _ExtendedJSONSchema(JSONSchema):
+  property_ordering: Optional[list[str]] = Field(
+      default=None,
+      description="""Optional. The order of the properties. Not a standard field in open api spec. Only used to support the order of the properties.""",
+  )
+
+
+def _to_snake_case(text: str) -> str:
+  """Converts a string into snake_case.
+
+  Handles lowerCamelCase, UpperCamelCase, or space-separated case, acronyms
+  (e.g., "REST API") and consecutive uppercase letters correctly.  Also handles
+  mixed cases with and without spaces.
+
+  Examples:
+  ```
+  to_snake_case('camelCase') -> 'camel_case'
+  to_snake_case('UpperCamelCase') -> 'upper_camel_case'
+  to_snake_case('space separated') -> 'space_separated'
+  ```
+
+  Args:
+      text: The input string.
+
+  Returns:
+      The snake_case version of the string.
+  """
+
+  # Handle spaces and non-alphanumeric characters (replace with underscores)
+  text = re.sub(r"[^a-zA-Z0-9]+", "_", text)
+
+  # Insert underscores before uppercase letters (handling both CamelCases)
+  text = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", text)  # lowerCamelCase
+  text = re.sub(
+      r"([A-Z]+)([A-Z][a-z])", r"\1_\2", text
+  )  # UpperCamelCase and acronyms
+
+  # Convert to lowercase
+  text = text.lower()
+
+  # Remove consecutive underscores (clean up extra underscores)
+  text = re.sub(r"_+", "_", text)
+
+  # Remove leading and trailing underscores
+  text = text.strip("_")
+
+  return text
+
+
+def _sanitize_schema_type(schema: dict[str, Any]) -> dict[str, Any]:
+  if ("type" not in schema or not schema["type"]) and schema.keys().isdisjoint(
+      schema
+  ):
+    schema["type"] = "object"
+  if isinstance(schema.get("type"), list):
+    nullable = False
+    non_null_type = None
+    for t in schema["type"]:
+      if t == "null":
+        nullable = True
+      elif not non_null_type:
+        non_null_type = t
+    if not non_null_type:
+      non_null_type = "object"
+    if nullable:
+      schema["type"] = [non_null_type, "null"]
+    else:
+      schema["type"] = non_null_type
+  elif schema.get("type") == "null":
+    schema["type"] = ["object", "null"]
+
+  return schema
+
+
+def _sanitize_schema_formats_for_gemini(
+    schema: dict[str, Any],
+) -> dict[str, Any]:
+  """Filters the schema to only include fields that are supported by JSONSchema."""
+  supported_fields: set[str] = set(_ExtendedJSONSchema.model_fields.keys())
+  schema_field_names: set[str] = {"items"}  # 'additional_properties' to come
+  list_schema_field_names: set[str] = {
+      "any_of",  # 'one_of', 'all_of', 'not' to come
+  }
+  snake_case_schema = {}
+  dict_schema_field_names: tuple[str] = ("properties",)  # 'defs' to come
+  for field_name, field_value in schema.items():
+    field_name = _to_snake_case(field_name)
+    if field_name in schema_field_names:
+      snake_case_schema[field_name] = _sanitize_schema_formats_for_gemini(
+          field_value
+      )
+    elif field_name in list_schema_field_names:
+      snake_case_schema[field_name] = [
+          _sanitize_schema_formats_for_gemini(value) for value in field_value
+      ]
+    elif field_name in dict_schema_field_names:
+      snake_case_schema[field_name] = {
+          key: _sanitize_schema_formats_for_gemini(value)
+          for key, value in field_value.items()
+      }
+    # special handle of format field
+    elif field_name == "format" and field_value:
+      current_type = schema.get("type")
+      if (
+          # only "int32" and "int64" are supported for integer or number type
+          (current_type == "integer" or current_type == "number")
+          and field_value in ("int32", "int64")
+          or
+          # only 'enum' and 'date-time' are supported for STRING type"
+          (current_type == "string" and field_value in ("date-time", "enum"))
+      ):
+        snake_case_schema[field_name] = field_value
+    elif field_name in supported_fields and field_value is not None:
+      snake_case_schema[field_name] = field_value
+
+  return _sanitize_schema_type(snake_case_schema)
+
+
+def _to_gemini_schema(openapi_schema: dict[str, Any]) -> Schema:
+  """Converts an OpenAPI schema dictionary to a Gemini Schema object."""
+  if openapi_schema is None:
+    return None
+
+  if not isinstance(openapi_schema, dict):
+    raise TypeError("openapi_schema must be a dictionary")
+
+  openapi_schema = _sanitize_schema_formats_for_gemini(openapi_schema)
+  return Schema.from_json_schema(
+      json_schema=_ExtendedJSONSchema.model_validate(openapi_schema),
+      api_option=get_google_llm_variant(),
+  )

google/adk/tools/apihub_tool/apihub_toolset.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
 
 from typing import List
 from typing import Optional
@@ -23,9 +24,9 @@ import yaml
 from ...agents.readonly_context import ReadonlyContext
 from ...auth.auth_credential import AuthCredential
 from ...auth.auth_schemes import AuthScheme
+from .._gemini_schema_util import _to_snake_case
 from ..base_toolset import BaseToolset
 from ..base_toolset import ToolPredicate
-from ..openapi_tool.common.common import to_snake_case
 from ..openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
 from ..openapi_tool.openapi_spec_parser.rest_api_tool import RestApiTool
 from .clients.apihub_client import APIHubClient
@@ -171,7 +172,7 @@ class APIHubToolset(BaseToolset):
     if not spec_dict:
       return
 
-    self.name = self.name or to_snake_case(
+    self.name = self.name or _to_snake_case(
         spec_dict.get('info', {}).get('title', 'unnamed')
     )
     self.description = self.description or spec_dict.get('info', {}).get(

google/adk/tools/application_integration_tool/clients/connections_client.py

@@ -252,6 +252,12 @@ class ConnectionsClient:
                         "Timeout in seconds for execution of custom query"
                     ),
                 },
+                "sortByColumns": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "default": [],
+                    "description": "Column to sort the results by",
+                },
                 "connectorOutputPayload": {"type": "object"},
                 "nextPageToken": {"type": "string"},
                 "execute-connector_Response": {
@@ -665,6 +671,7 @@ class ConnectionsClient:
             "serviceName": {"$ref": "#/components/schemas/serviceName"},
             "host": {"$ref": "#/components/schemas/host"},
             "entity": {"$ref": "#/components/schemas/entity"},
+            "sortByColumns": {"$ref": "#/components/schemas/sortByColumns"},
             "dynamicAuthConfig": {
                 "$ref": "#/components/schemas/dynamicAuthConfig"
             },

google/adk/tools/application_integration_tool/integration_connector_tool.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import logging
 from typing import Any
 from typing import Dict
@@ -24,8 +26,8 @@ from typing_extensions import override
 from .. import BaseTool
 from ...auth.auth_credential import AuthCredential
 from ...auth.auth_schemes import AuthScheme
+from .._gemini_schema_util import _to_gemini_schema
 from ..openapi_tool.openapi_spec_parser.rest_api_tool import RestApiTool
-from ..openapi_tool.openapi_spec_parser.rest_api_tool import to_gemini_schema
 from ..openapi_tool.openapi_spec_parser.tool_auth_handler import ToolAuthHandler
 from ..tool_context import ToolContext
 
@@ -62,11 +64,7 @@ class IntegrationConnectorTool(BaseTool):
       'dynamic_auth_config',
   ]
 
-  OPTIONAL_FIELDS = [
-      'page_size',
-      'page_token',
-      'filter',
-  ]
+  OPTIONAL_FIELDS = ['page_size', 'page_token', 'filter', 'sortByColumns']
 
   def __init__(
       self,
@@ -128,7 +126,7 @@ class IntegrationConnectorTool(BaseTool):
       if field in schema_dict['required']:
         schema_dict['required'].remove(field)
 
-    parameters = to_gemini_schema(schema_dict)
+    parameters = _to_gemini_schema(schema_dict)
     function_decl = FunctionDeclaration(
         name=self.name, description=self.description, parameters=parameters
     )

google/adk/tools/base_tool.py

@@ -15,14 +15,14 @@
 from __future__ import annotations
 
 from abc import ABC
-import os
 from typing import Any
 from typing import Optional
 from typing import TYPE_CHECKING
 
-from deprecated import deprecated
 from google.genai import types
 
+from ..utils.variant_utils import get_google_llm_variant
+from ..utils.variant_utils import GoogleLLMVariant
 from .tool_context import ToolContext
 
 if TYPE_CHECKING:
@@ -119,12 +119,8 @@ class BaseTool(ABC):
       )
 
   @property
-  def _api_variant(self) -> str:
-    use_vertexai = os.environ.get('GOOGLE_GENAI_USE_VERTEXAI', '0').lower() in [
-        'true',
-        '1',
-    ]
-    return 'VERTEX_AI' if use_vertexai else 'GOOGLE_AI'
+  def _api_variant(self) -> GoogleLLMVariant:
+    return get_google_llm_variant()
 
 
 def _find_tool_with_function_declarations(

google/adk/tools/bigquery/bigquery_credentials.py

@@ -34,6 +34,7 @@ from ...auth import OAuth2Auth
 from ..tool_context import ToolContext
 
 BIGQUERY_TOKEN_CACHE_KEY = "bigquery_token_cache"
+BIGQUERY_DEFAULT_SCOPE = ["https://www.googleapis.com/auth/bigquery"]
 
 
 class BigQueryCredentialsConfig(BaseModel):
@@ -66,15 +67,14 @@ class BigQueryCredentialsConfig(BaseModel):
   client_secret: Optional[str] = None
   """the oauth client secret to use."""
   scopes: Optional[List[str]] = None
-  """the scopes to use.
-  """
+  """the scopes to use."""
 
   @model_validator(mode="after")
   def __post_init__(self) -> BigQueryCredentialsConfig:
     """Validate that either credentials or client ID/secret are provided."""
     if not self.credentials and (not self.client_id or not self.client_secret):
       raise ValueError(
-          "Must provide either credentials or client_id abd client_secret pair."
+          "Must provide either credentials or client_id and client_secret pair."
       )
     if self.credentials and (
         self.client_id or self.client_secret or self.scopes
@@ -88,6 +88,10 @@ class BigQueryCredentialsConfig(BaseModel):
       self.client_id = self.credentials.client_id
       self.client_secret = self.credentials.client_secret
       self.scopes = self.credentials.scopes
+
+    if not self.scopes:
+      self.scopes = BIGQUERY_DEFAULT_SCOPE
+
     return self
 
 

google/adk/tools/function_tool.py

@@ -46,14 +46,14 @@ class FunctionTool(BaseTool):
 
     # Get documentation (prioritize direct __doc__ if available)
     if hasattr(func, '__doc__') and func.__doc__:
-      doc = func.__doc__
+      doc = inspect.cleandoc(func.__doc__)
     elif (
         hasattr(func, '__call__')
         and hasattr(func.__call__, '__doc__')
         and func.__call__.__doc__
     ):
       # For callable objects, try to get docstring from __call__ method
-      doc = func.__call__.__doc__
+      doc = inspect.cleandoc(func.__call__.__doc__)
 
     super().__init__(name=name, description=doc)
     self.func = func
@@ -107,9 +107,9 @@ You could retry calling this tool, but it is IMPORTANT for you to provide all th
         or hasattr(self.func, '__call__')
         and inspect.iscoroutinefunction(self.func.__call__)
     ):
-      return await self.func(**args_to_call) or {}
+      return await self.func(**args_to_call)
     else:
-      return self.func(**args_to_call) or {}
+      return self.func(**args_to_call)
 
   # TODO(hangfei): fix call live for function stream.
   async def _call_live(