[legacy path] Nested pydantic model tool parameter fails under VERTEX_AI when the function also has a fallback-parsed parameter — only with JSON_SCHEMA_FOR_FUNC_DECL disabled

[MarcHuang168]

Update (2026-09-03): Scope corrected — this only affects the legacy declaration path, i.e. when JSON_SCHEMA_FOR_FUNC_DECL is disabled. Default FunctionTool usage is not affected. See my comment below for the end-to-end reproduction.

🔴 Required Information

Describe the Bug:
When a tool function has a parameter that the strict parser in _function_parameter_parse_util does not handle (e.g. datetime.datetime), from_function_with_options falls back to building each parameter's schema from pydantic's JSON schema. In that fallback, the GEMINI_API variant runs _sanitize_schema_formats_for_gemini (which, among other things, turns $ref/$defs into ref/defs), but the VERTEX_AI variant validates the raw JSON schema directly with types.Schema.model_validate. Any nested pydantic model parameter therefore fails on Vertex with $ref / $defs extra_forbidden errors, and the surfaced ValueError blames that (valid) model parameter rather than the parameter that triggered the fallback.

Net effect: the same tool works on the Gemini Developer API but cannot be registered on Vertex AI.

Steps to Reproduce:

1. pip install google-adk
2. Run the snippet under Minimal Reproduction Code

Expected Behavior:
Both variants produce a declaration; on Vertex, p is described as an object with nested addr (the GEMINI_API variant already emits defs/ref for it).

Observed Behavior:

GEMINI_API: True
...
pydantic_core._pydantic_core.ValidationError: 2 validation errors for Schema
properties.addr.$ref
  Extra inputs are not permitted [type=extra_forbidden, input_value='#/$defs/Addr', input_type=str]
$defs
  Extra inputs are not permitted [type=extra_forbidden, ...]
...
ValueError: Failed to parse the parameter p: __main__.Person of function schedule for automatic function calling. ...

Environment Details:

• ADK Library Version (pip show google-adk): 2.8.0 (also reproduces on main)
• Desktop OS: macOS (arm64)
• Python Version (python -V): 3.14.7

Model Information:

• Are you using LiteLLM: No
• Which model is being used: N/A (reproduces at declaration-build time; variant selected explicitly via from_function_with_options(func, GoogleLLMVariant.VERTEX_AI))

---

🟡 Optional Information

Regression:
Unknown.

Logs:
See Observed Behavior above.

Screenshots / Video:
N/A

Additional Context:

• The nested model alone (no fallback-triggering parameter) works on both variants, because the strict parser handles BaseModel recursively; the failure needs the function to enter the pydantic fallback path.
• fix(tools): sanitize anyOf schemas for Vertex AI function declarations #6381 added Vertex-specific anyOf flattening in _function_tool_declarations.py, but the fallback path in _automatic_function_calling_util.from_function_with_options has no $ref/$defs handling for VERTEX_AI.
• I'm not planning a PR for this one; happy for anyone to pick it up. Reported with AI assistance; reproduced and reviewed by me.

Minimal Reproduction Code:

import datetime
import pydantic
from google.adk.tools._automatic_function_calling_util import from_function_with_options
from google.adk.utils.variant_utils import GoogleLLMVariant


class Addr(pydantic.BaseModel):
    city: str


class Person(pydantic.BaseModel):
    name: str
    addr: Addr


def schedule(p: Person, when: datetime.datetime) -> str:
    """Schedule a visit.

    Args:
        p: the person
        when: visit time
    """
    return "ok"


print("GEMINI_API:", from_function_with_options(schedule, GoogleLLMVariant.GEMINI_API).parameters is not None)
print("VERTEX_AI :", from_function_with_options(schedule, GoogleLLMVariant.VERTEX_AI).parameters is not None)

How often has this issue occurred?:

• Always (100%)

[seanxuu]

I’d like to work on this issue. I plan to trace the fallback schema path in from_function_with_options, align the Vertex AI path with the existing schema normalization behavior, and add focused tests for nested Pydantic models combined with fallback-parsed parameters. I’ll keep the change scoped to function declaration building and verify that existing Gemini and simple-model behavior remains unchanged. Please let me know if this direction fits the project.

[agooll]

Hi maintainers! I’d be interested in helping with this issue if it is still available.

I noticed that @seanxuu has already expressed interest, so I don’t want to duplicate any ongoing work. If implementation has already started, I’d also be happy to collaborate or take on a focused part such as regression testing.

My proposed approach would be to:

• reproduce the issue against the current main branch;
• trace the fallback schema-building path in from_function_with_options;
• align the Vertex AI path with the appropriate schema normalization behavior while preserving the existing Gemini API behavior;
• add focused regression tests covering nested Pydantic models combined with fallback-parsed parameters such as datetime;
• verify that simple models and existing function-tool schema generation remain unaffected.

Before I start, could a maintainer confirm whether this issue is still available and whether this implementation direction is appropriate? If so, I’d be glad to take it on.

[llalitkumarrr]

Hello @seanxuu,

We tried to reproduce the issue using Vertex AI and the Google ADK v2.8.0 with the approach shared below but we did not encounter any errors.

Could you please take a look and let us know if this helps? If we have misunderstood your issue kindly let us know what we need to adjust. Additionally sharing an end to end code sample to reproduce the issue would be very helpful.

import asyncio
import datetime
import pydantic
from dotenv import load_dotenv
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai.types import Content, Part
from google.adk.agents import Agent
from google.adk.tools import FunctionTool

class Address(pydantic.BaseModel):
    city: str

class UserProfile(pydantic.BaseModel):
    name: str
    address: Address

def schedule_appointment(profile: UserProfile, when: datetime.datetime) -> str:
    """Schedules an appointment for the user."""
    return f"Scheduled for {profile.name} in {profile.address.city} at {when}."

async def main():
    load_dotenv(override=True)

    APP_NAME = "BugReproApp"
    USER_ID = "test_user"
    SESSION_ID = "test_session1"


    myag = Agent(
        model="gemini-2.5-pro", 
        name="scheduler_agent",
        description="I schedule appointments.",
        instruction="You are a helpful assistant.",
        tools=[FunctionTool(schedule_appointment)] 
    )

    session_service = InMemorySessionService()
    await session_service.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID)
    

    runner = Runner(agent=myag, session_service=session_service, app_name=APP_NAME)
    
    initial_prompt = "Schedule an appointment for John in Seattle for tomorrow at 3 PM."
    next_message = Content(parts=[Part(text=initial_prompt)], role="user")
    
    print("Starting runner...")
    try:
        async for event in runner.run_async(
            user_id=USER_ID,
            session_id=SESSION_ID,
            new_message=next_message,
        ):
            print(event)
    except Exception as e:
        print("\n--- CRASH DETECTED ---")
        print(f"Error Type: {type(e)}")
        print(f"Error Message: {e}")

if __name__ == "__main__":
    asyncio.run(main())

[MarcHuang168]

@llalitkumarrr Thanks for checking — you're right, and I should correct the scope of this report.

Your script goes through FunctionTool, which by default takes the pydantic JSON-schema path (JSON_SCHEMA_FOR_FUNC_DECL is default_on=True), and that path handles nested models on Vertex fine. My reproduction called from_function_with_options directly, i.e. the legacy path, which FunctionTool only uses when that feature is disabled.

The crash is real but confined to the legacy path. It reproduces end-to-end with FunctionTool only when the feature is turned off:

import os, datetime, pydantic
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "true"
from google.adk.features import override_feature_enabled, FeatureName
override_feature_enabled(FeatureName.JSON_SCHEMA_FOR_FUNC_DECL, False)
from google.adk.tools import FunctionTool

class Address(pydantic.BaseModel):
    city: str

class UserProfile(pydantic.BaseModel):
    name: str
    address: Address

def schedule_appointment(profile: UserProfile, when: datetime.datetime) -> str:
    """Schedules an appointment.

    Args:
        profile: the user
        when: the time
    """
    return "ok"

FunctionTool(schedule_appointment)._get_declaration()
# ValueError: Failed to parse the parameter profile ... ($ref / $defs extra_forbidden)

So this is low-impact: only users who opt out of the JSON-schema declarations hit it. Happy to retitle/rescope the issue accordingly, or close it if the legacy path is slated for removal — your call. Apologies for the noise, and cc @seanxuu @agooll so you don't spend effort on a non-default path without knowing.

[agooll]

Thanks for the clarification. I’ll hold off on implementation until the maintainers decide whether the legacy path should be fixed or retired. I’d be happy to help with regression testing if a fix is pursued.