google / google/adk-java

Support @Schema annotation for Object parameters in FunctionTool

Open
#611 2 comments 1 reaction 1 assignee Claimed by @hemasekhar-p View on GitHub
needs review
Dominant language
Java
Stars
1.7k
Forks
420
Avg merge
4d 12h
Merged PRs (30d)
31

Description

**Is your feature request related to a problem? Please describe.**
Currently, adk-java relies on Jackson's `@JsonProperty` for defining schema names and required fields for pojos used as FunctionTool parameters. This creates several friction points:

1. Naming Conflicts: We may want the LLM-facing parameter name (e.g., `snake_case`) to differ from the Java field name (e.g., `camelCase`) without affecting internal JSON serialization used for other purposes.
2. Missing Metadata: Standard Jackson annotations do not support a `description` field, which is critical for FunctionTool schemas.
3. Ambiguous Optionality: Controlling whether a field is "required" or "optional" in the generated schema is difficult to decouple from Jackson's strict deserialization rules.

**Describe the solution you'd like**
I would like to extend the com.google.adk.tools.Annotations.Schema annotation to act as the highest source of truth for generating the FunctionTool schema in regards to pojo parameters, and deserialization. This includes:

1. Name: `@Schema(name="...")` should control the property name in the generated schema and during deserialization of the LLM response.
2. Description: `@Schema(description="...")` should populate the schema description.
3. Optionality: `@Schema(optional=true/false)` should explicitly control whether a field is marked as required, overriding Jackson's default behavior if necessary.

**Describe alternatives you've considered**

1. Jackson Mixins: We could use Jackson Mixins to separate the LLM view from the internal view, but this adds significant boilerplate and complexity for developers.
2. Custom Annotations: I considered creating a new set of annotations, but extending the existing `@Schema` annotation seems more idiomatic for the ADK.

**Additional context**
The Object FunctionTool parameter doesn't seem to have a direct 1-1 equivalent in adk-python, other than an [issue](https://github.com/google/adk-python/issues/1066) requesting for pydantic models to be supported as FunctionTool parameters.

The precedence rules I believe align best with the rest of the library would be :

Name: `@Schema(name)` > `@JsonProperty(value)` > Field Name
Description: `@Schema(description)` > None
Required: `@Schema(optional)` > `@JsonProperty(required)` > Default (Optional)

These rules should not affect the way prior objects that have been passed without the `@Schema` annotation are treated.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.