Fix: Default Values Breaking Google AI Function Tool Declarations

by SLV Team 66 views
Default Values are Not Supported in Function Declaration Schema for Google AI

Hey everyone, let's dive into a frustrating hiccup some of us are facing when working with Google AI and its function tools. Specifically, we're talking about an issue where default parameter values in function tool declarations are causing errors. This is a real pain, especially since the documentation seems to suggest everything should be peachy.

The Bug: Default Parameters and Google AI

So, here's the deal: when you try to use function tools with default parameter values in Google AI (Gemini API), you'll likely run into a wall. The error message? "Default value is not supported in function declaration schema for Google AI." But here's the kicker – the same code works perfectly fine with Vertex AI. Talk about a head-scratcher!

This discrepancy flies in the face of the ADK (Agent Development Kit) documentation. The documentation at https://google.github.io/adk-docs/tools/function-tools/ explicitly states that optional parameters, which are defined by providing a default value, should be supported. This means the ADK should correctly interpret these and not list them as required in the tool schema sent to the LLM (Large Language Model). The current behavior, however, suggests there's some variant-specific logic under the hood that's not playing nice with the Gemini API.

Reproducing the Problem

To see this firsthand, let's walk through the steps to reproduce the issue:

  1. Install ADK: First things first, get the ADK installed: pip install google-adk.
  2. Create a Function Tool: Next, create a function tool with some default parameters. Here's a basic example:
from google.adk.tools import FunctionTool

async def find_something(
    tool_context: ToolContext,
    query: str = "",
    category: str = "",
    important_only: bool = False,
    limit: int = 10,
) -> dict:
    """Find something ..."""
    # implementation
    pass

some_tools = {
    "find_something": FunctionTool(func=find_something),
}
  1. Configure Your Agent: Now, configure your agent to use Google AI (Gemini API). Something like this will do the trick:
llm_config:
  provider: google
  model: gemini-2.5-flash
  api_key_secret_name: GOOGLE_API_KEY
  1. Run and Attempt to Use the Tool: Fire up your agent and try to use the tool you created. If you're unlucky, you'll encounter the dreaded warning, and the tool calls will likely fail.

Expected vs. Actual Behavior

Based on the ADK documentation, you should be able to use optional parameters with default values without a hitch, regardless of whether you're using Vertex AI or Gemini API. The ADK should recognize the default values and not mark those parameters as required in the tool schema.

However, the actual behavior tells a different story. The Gemini API implementation seems to reject default values, causing the agent to stumble. This leads to confusion and frustration, especially when the documentation suggests everything should work seamlessly.

Digging Deeper: The Root Cause

Looking under the hood, the issue seems to stem from the _function_parameter_parse_util.py file within the ADK. This file appears to contain variant-specific logic that handles default values differently depending on the AI platform being used. It's likely that this logic rejects default values for the Gemini API while accepting them for Vertex AI. Setting the environment variable GOOGLE_GENAI_USE_VERTEXAI=true might temporarily solve the problem. However, this isn't a viable long-term solution, particularly for those of us who need to leverage the Gemini API.

The Impact of This Bug

This bug significantly impacts the usability of function tools for developers relying on the Gemini API. The ability to use default parameters is crucial for building flexible and user-friendly tools. When this functionality is broken, it forces developers to work around the limitation, which can lead to more complex code and a less-than-ideal user experience.

Possible Solutions

To address this issue and make the ADK more reliable, there are two primary options:

  1. Update the Documentation: The documentation should be updated to clearly state that default parameters are not supported with the Gemini API, at least until the underlying implementation is fixed. This transparency would set the correct expectations for developers and help them avoid wasting time on code that won't work.
  2. Fix the Implementation: The ideal solution is to fix the implementation in the _function_parameter_parse_util.py file to correctly handle default parameters for both Vertex AI and Gemini API. This would align with the existing documentation and provide a consistent experience for all users.

System Information

For reference, here's some system information:

  • OS: macOS
  • Python version: 3.11
  • ADK version: 1.16.0
  • Model: gemini-2.5-flash (also fails with gemini-2.5-pro)

Conclusion: A Call for Action

In conclusion, the issue with default parameter values in Google AI function tools needs attention. Whether it's through clearer documentation or a fix to the implementation, Google needs to address this issue. Until then, developers will have to navigate this pitfall to ensure that their tools function as intended, especially when leveraging the power of Gemini API. Let's hope for a quick resolution so we can get back to building amazing things! This will ensure developers using Gemini API can create function tools that are both flexible and user-friendly.

Understanding the Problem: Default Parameters in Function Tools

Let's break down the core concepts. Function tools are a critical component of modern AI agents, allowing them to interact with the external world and perform specific tasks. Think of them as the agent's toolbox, containing various tools the agent can use to accomplish a goal. These tools are typically defined as functions with specific parameters.

The Role of Default Parameters

Default parameters in these function tools are incredibly useful. They provide flexibility, allowing users to optionally provide values for certain parameters. If a user doesn't specify a value for a parameter with a default, the function uses the default value instead. This simplifies the user experience and makes the tools more versatile.

How ADK Handles Function Tools

The Agent Development Kit (ADK) is the framework that manages the creation and deployment of these AI agents. When you define a function tool with default parameters, the ADK is supposed to interpret those defaults correctly. It should tell the Large Language Model (LLM) that these parameters are optional, streamlining the process.

The Gemini API Challenge

The issue arises when the Gemini API is involved. It appears the Gemini API, or at least the ADK's handling of it, is struggling to interpret these default values correctly. The LLM might be incorrectly interpreting parameters with defaults as required, leading to tool failures. This inconsistency is the core problem.

Workarounds and Mitigations

While we wait for a fix, there are a few workarounds you can try to mitigate the impact of this bug:

  1. Avoid Default Parameters: The simplest, though not ideal, workaround is to avoid using default parameters altogether. Instead, make all parameters explicitly required in your function definitions. While this increases the complexity of your tool definitions, it ensures they'll be compatible with the Gemini API.
  2. Conditional Logic: Implement conditional logic within your function to handle cases where a parameter might have had a default value. For example, if a query parameter was supposed to have a default value of an empty string, you could check if the query is empty within the function's logic and assign a default value accordingly. This approach allows you to achieve the same functionality as default parameters but may require more code.
  3. Use Vertex AI (If Possible): If your project allows it, consider switching to Vertex AI. Because the ADK doesn't have the same problem with default parameters in Vertex AI, this offers a temporary solution. Keep in mind that there might be cost or compatibility implications involved.

The Technical Deep Dive: Why It's Happening

To understand the issue, it's worth taking a look at the technical underpinnings. The problem seems to lie within the _function_parameter_parse_util.py file, which is part of the ADK code. This file is responsible for parsing function definitions and creating the schema that the LLM uses to understand the tools. The way this file interprets default values appears to vary between Vertex AI and Gemini API. It suggests a difference in the code's approach to how it handles default parameter values during the parsing process. In the case of Gemini API, the parsing logic is likely not correctly recognizing or correctly conveying the existence of the default values. As a result, the LLM is receiving an incorrect tool schema.

Code Snippets to Illustrate the Problem

While I can't provide the entire code from the _function_parameter_parse_util.py file (as that would involve reverse-engineering the compiled code), we can examine how the function declarations are likely being handled. Consider this example:

async def search_items(
    query: str = "default search",
    limit: int = 5,
    sort_by: str = None
):
    #Function implementation
    pass

In the correct processing, the ADK would see: query with a default of "default search," limit with a default of 5, and sort_by defaulting to None. It should indicate this in the JSON structure sent to the LLM (Large Language Model) to inform it that these are optional, meaning their values can be inferred, and are not strictly required.

The Root Cause: API Differences

The reason for the incompatibility comes down to how each API – Vertex AI and Gemini API – handles the schema for describing the tools. The differing implementation inside _function_parameter_parse_util.py means that the schema generated for Gemini is either: incorrect in describing default values, misinterpreting the values, or is outright ignoring them. This leads to the LLM either failing to identify that defaults are available or incorrectly treating all parameters as mandatory.

Further Steps: Reporting and Support

If you encounter this bug, consider taking these steps:

  1. Report the Issue: File a bug report or support ticket with Google. Be sure to provide detailed information about your setup, the steps to reproduce the issue, and the error messages you're seeing. The more details you provide, the better. This helps Google's developers understand the problem and find a fix.
  2. Check for Updates: Keep an eye out for updates to the ADK. The issue might be addressed in a future version. You can check the ADK's release notes or documentation for updates.
  3. Engage with the Community: Join discussions or forums related to Google AI and the ADK. Other developers may have found workarounds or insights. Sharing your experiences and seeking help from the community can be incredibly valuable.

Conclusion: Navigating the Challenges

This bug regarding default parameters in function tools for Google AI, especially when using the Gemini API, is a hurdle for developers. While the ADK documentation suggests that default parameters should be supported, the current implementation reveals an incompatibility. The implications of this are that developers must consider alternative approaches, such as avoiding defaults, using conditional logic, or utilizing Vertex AI, until a fix is implemented. By recognizing the issue, reporting it, and following the suggested steps, we can work together to help Google's AI tools evolve and offer a better developer experience. It highlights the importance of staying informed about these issues and staying proactive in providing feedback to the tool creators.