adk-docs
adk-docs copied to clipboard
google
int | None union syntax fails to parse in function parameters despite documented support
Bug Description:
The Google ADK function parameter parser fails to handle modern Python union syntax (int | None) in function parameters, throwing a parsing error despite the codebase claiming to support union types. The error suggests using manual function declaration parsing as a workaround.
To Reproduce:
Create a function with int | None parameter annotation Use the function as a tool in an ADK agent Run the agent - automatic function calling fails with parsing error Expected Behavior: The int | None syntax should be parsed successfully, similar to how Optional[int] works, since both represent the same type annotation.
Actual Behavior:
Error: Failed to parse the parameter num_lines: int | None of function <function_name> for automatic function calling. Automatic function calling works best with simpler function signature schema, consider manually parsing your function declaration for function <function_name>.
Root Cause Analysis: The issue appears to be in where the parser checks get_origin(param.annotation) is Union. The modern int | None syntax may not be detected by this condition, causing it to fall through to the error case at .
Environment:
Python version: 3.12.10 ADK version: 1.4.2 OS: Windows 11 Pro Code Example:
def example_function(file_path: str, num_lines: int | None = None) -> str:
# Function implementation
pass
Workaround: Using Optional[int] instead of int | None works as expected:
from typing import Optional
def example_function(file_path: str, num_lines: Optional[int] = None) -> str:
# Function implementation
pass
Additional Context:
The codebase requires from future import annotations as shown in check-file-contents.yml:73-83 The parser has logic for handling union types with None as shown in The codebase uses Optional[type] extensively in existing tools, suggesting this should work This appears to be an inconsistency between the documented/intended support for modern Python syntax and the actual implementation in the parameter parser.
I'm running into this same issue in this a2a sample code: https://github.com/a2aproject/a2a-samples/blob/main/samples/python/agents/adk_expense_reimbursement/agent.py#L23-L25
I've submitted a documentation PR that provides workarounds and best practices for this issue:
PR: https://github.com/google/adk-docs/pull/786
The guide documents:
- Why
| Nonesyntax doesn't work currently - Working pattern:
Optional[int]instead ofint | None - Python version compatibility notes
- Migration checklist for updating existing code
While this doesn't fix the underlying parser issue, it should help developers avoid hitting this error and provide clear guidance until native | None support is added.
