fix: Fix RecursionError in ADK framework by adding circular reference detection to schema resolution

PiperOrigin-RevId: 905576545

Author: google-genai-bot

src/google/adk/tools/_gemini_schema_util.py

@@ -108,10 +108,20 @@ def _dereference_schema(schema: dict[str, Any]) -> dict[str, Any]:
 
   defs = schema.get("$defs", {})
 
-  def _resolve_refs(sub_schema: Any) -> Any:
+  def _resolve_refs(sub_schema: Any, path_refs: frozenset[str]) -> Any:
     if isinstance(sub_schema, dict):
       if "$ref" in sub_schema:
-        ref_key = sub_schema["$ref"].split("/")[-1]
+        ref_uri = sub_schema["$ref"]
+        ref_key = ref_uri.split("/")[-1]
+
+        if ref_uri in path_refs:
+          return {
+              "type": "object",
+              "description": f"Circular ref to {ref_key}",
+          }
+
+        new_path = path_refs | {ref_uri}
+
         if ref_key in defs:
           # Found the reference, replace it with the definition.
           resolved = defs[ref_key].copy()
@@ -120,21 +130,24 @@ def _resolve_refs(sub_schema: Any) -> Any:
           del sub_schema_copy["$ref"]
           resolved.update(sub_schema_copy)
           # Recursively resolve refs in the newly inserted part.
-          return _resolve_refs(resolved)
+          return _resolve_refs(resolved, new_path)
         else:
           # Reference not found, return as is.
           return sub_schema
       else:
         # No $ref, so traverse deeper into the dictionary.
-        return {key: _resolve_refs(value) for key, value in sub_schema.items()}
+        return {
+            key: _resolve_refs(value, path_refs)
+            for key, value in sub_schema.items()
+        }
     elif isinstance(sub_schema, list):
       # Traverse into lists.
-      return [_resolve_refs(item) for item in sub_schema]
+      return [_resolve_refs(item, path_refs) for item in sub_schema]
     else:
       # Not a dict or list, return as is.
       return sub_schema
 
-  dereferenced_schema = _resolve_refs(schema)
+  dereferenced_schema = _resolve_refs(schema, frozenset())
   # Remove the definitions block after resolving.
   if "$defs" in dereferenced_schema:
     del dereferenced_schema["$defs"]

tests/unittests/tools/test_gemini_schema_util.py

@@ -730,6 +730,115 @@ def test_to_gemini_schema_boolean_true_in_array_items_properties(self):
     model_schema = data_schema.items.properties["model"]
     assert model_schema.type == Type.OBJECT
 
+  def test_to_gemini_schema_circular_ref(self):
+    """Test that circular references in schema are handled without RecursionError."""
+    openapi_schema = {
+        "$defs": {
+            "Node": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "parent": {"$ref": "#/$defs/Node"},
+                },
+            }
+        },
+        "properties": {"tree": {"$ref": "#/$defs/Node"}},
+        "type": "object",
+    }
+    # Should not raise RecursionError
+    gemini_schema = _to_gemini_schema(openapi_schema)
+    assert gemini_schema.type == Type.OBJECT
+    assert gemini_schema.properties["tree"].type == Type.OBJECT
+    assert (
+        gemini_schema.properties["tree"].properties["name"].type == Type.STRING
+    )
+    assert (
+        gemini_schema.properties["tree"].properties["parent"].type
+        == Type.OBJECT
+    ), "The circular ref should be handled and return the fallback object"
+    assert (
+        gemini_schema.properties["tree"].properties["parent"].description
+        == "Circular ref to Node"
+    )
+
+  def test_to_gemini_schema_multi_step_circular_ref(self):
+    """Test that multi-step circular references (Value -> Struct -> Value) are handled."""
+    openapi_schema = {
+        "$defs": {
+            "Value": {
+                "anyOf": [
+                    {"type": "string"},
+                    {"$ref": "#/$defs/Struct"},
+                ]
+            },
+            "Struct": {
+                "type": "object",
+                "properties": {
+                    "fields": {
+                        "type": "object",
+                        "properties": {
+                            "my_val": {
+                                "type": "array",
+                                "items": {"$ref": "#/$defs/Value"},
+                            }
+                        },
+                    }
+                },
+            },
+        },
+        "properties": {"root": {"$ref": "#/$defs/Value"}},
+        "type": "object",
+    }
+
+    gemini_schema = _to_gemini_schema(openapi_schema)
+    # Individual assertions are used here instead of comparing the whole Schema
+    # object or its properties dictionary because Schema objects with deep
+    # nesting can have subtle differences in default fields that are hard to
+    # debug due to pytest truncation limits.
+    assert gemini_schema.type == Type.OBJECT
+    # root is Value, which resolved to anyOf
+    assert len(gemini_schema.properties["root"].any_of) == 2
+    assert gemini_schema.properties["root"].any_of[0].type == Type.STRING
+    # any_of[1] is Struct
+    struct_schema = gemini_schema.properties["root"].any_of[1]
+    assert struct_schema.type == Type.OBJECT
+    assert struct_schema.properties["fields"].type == Type.OBJECT
+    # properties["fields"].properties["my_val"] is an array
+    my_val_schema = struct_schema.properties["fields"].properties["my_val"]
+    assert my_val_schema.type == Type.ARRAY
+    assert (
+        my_val_schema.items.type == Type.OBJECT
+    ), "Array items referencing a circular $ref should resolve to Type.OBJECT"
+
+  def test_to_gemini_schema_reused_non_circular_ref(self):
+    """Test that reused non-circular references are handled correctly."""
+    openapi_schema = {
+        "$defs": {
+            "CommonType": {"type": "string"},
+            "ObjectA": {
+                "type": "object",
+                "properties": {"prop_a": {"$ref": "#/$defs/CommonType"}},
+            },
+            "ObjectB": {
+                "type": "object",
+                "properties": {"prop_b": {"$ref": "#/$defs/CommonType"}},
+            },
+        },
+        "properties": {
+            "a": {"$ref": "#/$defs/ObjectA"},
+            "b": {"$ref": "#/$defs/ObjectB"},
+        },
+        "type": "object",
+    }
+    gemini_schema = _to_gemini_schema(openapi_schema)
+    assert gemini_schema.type == Type.OBJECT
+    assert (
+        gemini_schema.properties["a"].properties["prop_a"].type == Type.STRING
+    )
+    assert (
+        gemini_schema.properties["b"].properties["prop_b"].type == Type.STRING
+    )
+
 
 class TestToSnakeCase: