feat(tools): Support tuple tool parameters

Merge #6076

## Summary

- Support homogeneous tuple annotations such as `tuple[float, float]` and `tuple[str, ...]` in automatic function declarations.
- Parse supported tuples as array schemas instead of falling back to Pydantic JSON schema fields that `google.genai.types.Schema` rejects.
- Add regression coverage for tuple tool parameters and optional tuple parameters.

Fixes #3575

## Verification

- `uv run pytest tests/unittests/tools/test_from_function_with_options.py -q`
- `uv run pytest tests/unittests/tools -q`
- `uv run pre-commit run --files src/google/adk/tools/_function_parameter_parse_util.py tests/unittests/tools/test_from_function_with_options.py`

Co-authored-by: Haran Rajkumar <haranrk@google.com>
COPYBARA_INTEGRATE_REVIEW=#6076 from RaghunandanKumar:fix/issue-3575 a53780a
PiperOrigin-RevId: 934745222

Author: 2 people

src/google/adk/tools/_function_parameter_parse_util.py

@@ -182,7 +182,7 @@ def _is_default_value_compatible(
       or isinstance(annotation, typing_types.GenericAlias)
       or isinstance(annotation, typing_types.UnionType)
   ):
-    origin = get_origin(annotation)
+    origin: Any = get_origin(annotation)
     if origin in (Union, typing_types.UnionType):
       return any(
           _is_default_value_compatible(default_value, arg)
@@ -208,6 +208,22 @@ def _is_default_value_compatible(
           for item in default_value
       )
 
+    if origin is tuple:
+      if not isinstance(default_value, tuple):
+        return False
+      args = get_args(annotation)
+      if len(args) == 2 and args[-1] is Ellipsis:
+        return all(
+            _is_default_value_compatible(item, args[0])
+            for item in default_value
+        )
+      if len(args) != len(default_value):
+        return False
+      return all(
+          _is_default_value_compatible(item, arg)
+          for item, arg in zip(default_value, args)
+      )
+
     if origin is Literal:
       return default_value in get_args(annotation)
 
@@ -299,7 +315,7 @@ def _parse_schema_from_parameter(
       or isinstance(param.annotation, typing_types.GenericAlias)
       or isinstance(param.annotation, typing_types.UnionType)
   ):
-    origin = get_origin(param.annotation)
+    origin: Any = get_origin(param.annotation)
     args = get_args(param.annotation)
     if origin is dict:
       schema.type = types.Type.OBJECT
@@ -339,6 +355,43 @@ def _parse_schema_from_parameter(
         schema.default = param.default
       _raise_if_schema_unsupported(variant, schema)
       return schema
+    if origin is tuple:
+      # A genai array schema only carries a single `items` type, so only
+      # homogeneous tuples can be represented. `tuple[T, ...]` maps to an
+      # unbounded array, while a fixed-length homogeneous tuple
+      # (e.g. `tuple[T, T]`) additionally pins min_items/max_items to the
+      # arity. Heterogeneous tuples (e.g. `tuple[str, int]`) cannot be
+      # represented and intentionally raise so that from_function_with_options
+      # routes them through the standard unsupported-parameter handling.
+      fixed_length = None
+      if len(args) == 2 and args[-1] is Ellipsis:
+        item_annotation = args[0]
+      elif args and all(arg == args[0] for arg in args):
+        item_annotation = args[0]
+        fixed_length = len(args)
+      else:
+        raise ValueError(
+            f'Tuple type {param.annotation} must use one repeated item type.'
+        )
+      schema.type = types.Type.ARRAY
+      schema.items = _parse_schema_from_parameter(
+          variant,
+          inspect.Parameter(
+              'item',
+              inspect.Parameter.POSITIONAL_OR_KEYWORD,
+              annotation=item_annotation,
+          ),
+          func_name,
+      )
+      if fixed_length is not None:
+        schema.min_items = fixed_length
+        schema.max_items = fixed_length
+      if param.default is not inspect.Parameter.empty:
+        if not _is_default_value_compatible(param.default, param.annotation):
+          raise ValueError(default_value_error_msg)
+        schema.default = param.default
+      _raise_if_schema_unsupported(variant, schema)
+      return schema
     if origin in (Union, typing_types.UnionType):
       schema.any_of = []
       schema.type = types.Type.OBJECT

tests/unittests/tools/test_from_function_with_options.py

@@ -22,6 +22,7 @@
 from google.adk.utils.variant_utils import GoogleLLMVariant
 from google.genai import types
 import pydantic
+import pytest
 
 
 def test_from_function_with_options_no_return_annotation_gemini():
@@ -229,6 +230,72 @@ def test_function(
   assert declaration.response.type == types.Type.STRING
 
 
+def test_from_function_with_tuple_type_parameter():
+  """Test from_function_with_options with fixed-size homogeneous tuple."""
+
+  def test_function(
+      coordinate: tuple[float, float],
+  ) -> str:
+    """Formats a coordinate pair."""
+    return f'{coordinate[0]}, {coordinate[1]}'
+
+  declaration = _automatic_function_calling_util.from_function_with_options(
+      test_function, GoogleLLMVariant.VERTEX_AI
+  )
+
+  assert declaration.name == 'test_function'
+  assert declaration.parameters.type == types.Type.OBJECT
+  coordinate_schema = declaration.parameters.properties['coordinate']
+  assert coordinate_schema.type == types.Type.ARRAY
+  assert coordinate_schema.items.type == types.Type.NUMBER
+  # Fixed-size tuples pin the array length so the model emits exactly the
+  # expected number of items.
+  assert coordinate_schema.min_items == 2
+  assert coordinate_schema.max_items == 2
+  assert declaration.response.type == types.Type.STRING
+
+
+def test_from_function_with_variadic_tuple_type_parameter():
+  """Test from_function_with_options with variable-length homogeneous tuple."""
+
+  def test_function(
+      tags: tuple[str, ...],
+  ) -> str:
+    """Joins tags."""
+    return ', '.join(tags)
+
+  declaration = _automatic_function_calling_util.from_function_with_options(
+      test_function, GoogleLLMVariant.VERTEX_AI
+  )
+
+  tags_schema = declaration.parameters.properties['tags']
+  assert tags_schema.type == types.Type.ARRAY
+  assert tags_schema.items.type == types.Type.STRING
+  # Variadic tuples are unbounded, so no size constraints are set.
+  assert tags_schema.min_items is None
+  assert tags_schema.max_items is None
+
+
+def test_from_function_with_heterogeneous_tuple_raises():
+  """Heterogeneous tuples can't map to a single-`items` array schema.
+
+  `google.genai.types.Schema` arrays carry a single `items` type (no
+  positional `prefixItems`), so a tuple like `tuple[str, int]` cannot be
+  represented. It must surface a clear error rather than be silently coerced
+  into an incorrect homogeneous array.
+  """
+
+  def test_function(
+      pair: tuple[str, int],
+  ) -> str:
+    return f'{pair[0]}: {pair[1]}'
+
+  with pytest.raises(ValueError):
+    _automatic_function_calling_util.from_function_with_options(
+        test_function, GoogleLLMVariant.VERTEX_AI
+    )
+
+
 def test_from_function_with_collections_return_type():
   """Test from_function_with_options with collections return type."""
 
@@ -322,14 +389,8 @@ async def test_function(param: str) -> AsyncGenerator[Dict[str, str], None]:
   assert declaration.response.type == types.Type.OBJECT
 
 
-def test_required_fields_set_in_json_schema_fallback():
-  """Test that required fields are populated when the json_schema fallback path is used.
-
-  When a parameter has a complex type (e.g. tuple[str, ...] | None) that
-  _parse_schema_from_parameter can't handle, from_function_with_options falls
-  back to the parameters_json_schema branch. This test verifies that the
-  required fields are correctly populated in that fallback branch.
-  """
+def test_required_fields_set_with_optional_tuple_parameter():
+  """Test that required fields are populated with optional tuple parameters."""
 
   def complex_tool(
       query: str,
@@ -351,19 +412,43 @@ def complex_tool(
           'query': types.Schema(type=types.Type.STRING),
           'mode': types.Schema(type=types.Type.STRING, default='default'),
           'tags': types.Schema(
-              any_of=[
-                  types.Schema(
-                      items=types.Schema(type=types.Type.STRING),
-                      type=types.Type.ARRAY,
-                  ),
-                  types.Schema(type=types.Type.NULL),
-              ],
+              items=types.Schema(type=types.Type.STRING),
               nullable=True,
+              type=types.Type.ARRAY,
           ),
       },
   )
 
 
+def test_required_fields_set_in_json_schema_fallback():
+  """Required fields are populated when the json_schema fallback path is used.
+
+  A parameter whose type `_parse_schema_from_parameter` cannot handle (here
+  `Sequence[str]`) forces from_function_with_options onto the pydantic
+  json_schema fallback branch. This verifies that branch still derives required
+  fields correctly: parameters without defaults are required, parameters with
+  defaults are not.
+  """
+
+  def complex_tool(
+      query: str,
+      items: Sequence[str],
+      mode: str = 'default',
+  ) -> str:
+    return query
+
+  declaration = _automatic_function_calling_util.from_function_with_options(
+      complex_tool, GoogleLLMVariant.VERTEX_AI
+  )
+
+  assert declaration.name == 'complex_tool'
+  assert declaration.parameters.type == types.Type.OBJECT
+  # query and items have no defaults -> required; mode has a default -> not.
+  assert set(declaration.parameters.required) == {'query', 'items'}
+  assert declaration.parameters.properties['items'].type == types.Type.ARRAY
+  assert declaration.parameters.properties['mode'].default == 'default'
+
+
 def test_schema_sanitization_for_complex_union_type():
   """Test schema is sanitized for complex union type."""
 
@@ -390,8 +475,9 @@ def test_format_preservation_for_vertex_fallback():
   class ComplexModel(pydantic.BaseModel):
     # Field with format that would be stripped by Gemini sanitization
     email: str = pydantic.Field(json_schema_extra={'format': 'email'})
-    # Complex field to trigger fallback (tuple is not handled by _parse_schema_from_parameter)
-    complex_field: tuple[str, ...]
+    # Complex field to trigger fallback (Sequence is not handled by
+    # _parse_schema_from_parameter)
+    complex_field: Sequence[str]
 
   def my_tool(param: ComplexModel) -> str:
     return f'ok {param}'