Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: RecursionError in _to_gemini_schema() when processing circular $ref in $defs #3870
• Related: RecursionError in _to_gemini_schema() when processing circular $ref in $defs #3870

Problem:
The _dereference_schema() function in google.adk.tools._gemini_schema_util triggers a RecursionError when processing JSON schemas with circular $ref references. This occurs because the function recursively resolves references without detecting circular dependencies, causing infinite recursion when a schema references itself (e.g., a tree structure where a node can contain child nodes of the same type).

Additionally, the original implementation only handled $defs-style references (#/$defs/TypeName) but not JSON Pointer references (#/properties/path/to/field), which are commonly used in OpenAPI and other schema formats.

Solution:
Enhanced _dereference_schema() with the following improvements:

1. Circular reference detection: Track references currently being resolved using a resolving set. When a circular reference is detected, return a placeholder schema ({"type": "object", "description": "Circular reference to <ref>"}) instead of recursing infinitely.

2. JSON Pointer support: Added _resolve_json_pointer() helper function to resolve references that use JSON Pointer syntax (#/properties/...), in addition to existing $defs support.

This allows for a graceful degradation, where rather than raising an error, circular references are replaced with valid placeholder schemas, allowing tools with recursive data structures to function correctly.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.
  • 3408 passed
  • 2504 warnings
  • Took 71.89s

Manual End-to-End (E2E) Tests:

1. Schema with circular $defs reference

   from google.adk.tools._gemini_schema_util import _to_gemini_schema
   
   schema = {
       "type": "object",
       "properties": {
           "attendees": {
               "type": "array",
               "items": {"$ref": "#/$defs/Attendee"}
           }
       },
       "$defs": {
           "Attendee": {
               "type": "object",
               "properties": {
                   "name": {"type": "string"},
                   "alternateAttendee": {"$ref": "#/$defs/Attendee"} # Circular
               }
           }
       }
   }
   
   gemini_schema = _to_gemini_schema(schema)
   

   • Before fix: RecursionError
   • After fix: Success

2. Schema with JSON Pointer circular reference

   from google.adk.tools._gemini_schema_util import _to_gemini_schema
   
   schema = {
       "type": "object",
       "properties": {
           "body": {
               "type": "object",
               "properties": {
                   "attendees": {
                       "type": "array",
                       "items": {
                           "type": "object",
                           "properties": {
                               "start": {
                                   "$ref": "#/properties/body/properties/end" # JSON Pointer
                               }
                           }
                       }
                   },
                   "end": {"type": "object", "properties": {"dateTime": {"type": "string"}}}
               }
           }
       }
   }
   
   gemini_schema = _to_gemini_schema(schema)
   

   • Before fix: RecursionError
   • After fix: Success

3. Schema with 2 circular $defs reference

   from google.adk.tools._gemini_schema_util import _to_gemini_schema
   
   schema = {
       "type": "object",
       "properties": {
           "attendees": {
               "type": "array",
               "items": {"$ref": "#/$defs/Attendee"}
           },
           "organizer": {"$ref": "#/$defs/Person"}
       },
       "$defs": {
           "Attendee": {
               "type": "object",
               "properties": {
                   "name": {"type": "string"},
                   "alternateAttendee": {"$ref": "#/$defs/Attendee"}  # Circular 1
               }
           },
           "Person": {
               "type": "object",
               "properties": {
                   "name": {"type": "string"},
                   "manager": {"$ref": "#/$defs/Person"}  # Circular 2
               }
           }
       }
   }
   
   gemini_schema = _to_gemini_schema(schema)
   

   • Before fix: RecursionError
   • After fix: Success

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

Note on google-genai dependency:
While this fix resolves the issue for ADK's schema conversion pipeline, the google-genai library's Schema.from_json_schema() method has a similar issue in its convert_json_schema() function. However, since ADK calls _dereference_schema() before passing schemas to google-genai, this fix protects ADK users from the RecursionError. Direct users of google-genai would need a similar fix in that library's auto-generated types.py file.

Applicability:
This fix enables building MCP server tools that wrap complex APIs which often contain recursive schema definitions for representing hierarchical data structures.