Skip to content

Support @Schema annotation for Object parameters in FunctionTool #611

@NamanSatish

Description

@NamanSatish

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 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions