fix(tool): allow null for optional nested object fields

[JGoP-L]

AgentScope-Java Version

1.0.12-SNAPSHOT

Description

Fixes #1163

Background

When a tool parameter contains a nested object, AgentScope-Java currently treats these two cases differently for optional fields:

1. The optional field is omitted
2. The optional field is explicitly set to null

Case 1 passes validation, but case 2 fails during JSON Schema validation with an error like:

null found, string expected

This makes tool calling brittle in practice, because LLMs often emit null for optional fields instead of omitting them entirely.

Purpose

Make optional nested object fields behave consistently:

• missing optional field: valid
• optional field explicitly set to null: also valid

Required field validation should continue to work as before.

Changes made

1. Fix tool input validation for explicit null optional fields

Updated ToolValidator.validateInput(...) to normalize tool input before JSON Schema validation.

It now recursively removes null-valued object properties before validating the payload. This means:

• optional fields with null are treated the same as omitted fields
• required fields with null still fail validation, because the field is removed and then checked by required

Modified file:

• agentscope-core/src/main/java/io/agentscope/core/tool/ToolValidator.java

2. Add regression tests for generated nested bean schema

Added tests to verify:

• missing optional nested bean field is accepted
• explicit null optional nested bean field is accepted

Modified file:

• agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java

3. Add protection tests for object parameter conversion

Added tests to confirm that nested bean parameter conversion itself already works correctly for:

• missing optional field
• explicit null optional field

This verifies the bug is in validation behavior rather than conversion behavior.

Modified file:

• agentscope-core/src/test/java/io/agentscope/core/tool/ToolMethodInvokerTest.java

How to test

Run:

mvn -pl agentscope-core -Dtest=ToolValidatorTest,ToolMethodInvokerTest test

[Copilot]

Pull request overview

This PR fixes tool input validation so that optional object fields explicitly set to null are treated the same as omitted fields, preventing brittle failures during JSON Schema validation (Fixes #1163).

Changes:

• Normalize tool-call JSON inputs by pruning null object properties before running JSON Schema validation.
• Add regression tests covering generated nested bean schemas accepting missing vs explicit-null optional fields.
• Add protection tests confirming nested bean parameter conversion already handles missing vs explicit-null optional fields.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
agentscope-core/src/main/java/io/agentscope/core/tool/ToolValidator.java	Adds pre-validation normalization that prunes null-valued object properties before schema validation.
agentscope-core/src/test/java/io/agentscope/core/tool/ToolValidatorTest.java	Adds regression tests for generated bean schemas around missing vs explicit null optional nested fields.
agentscope-core/src/test/java/io/agentscope/core/tool/ToolMethodInvokerTest.java	Adds conversion tests showing bean parameter conversion behaves correctly for missing vs explicit null optional fields.

[codecov]

Codecov Report

❌ Patch coverage is 80.32787% with 12 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...in/java/io/agentscope/core/tool/ToolValidator.java	80.32%	4 Missing and 8 partials ⚠️

📢 Thoughts on this report? Let us know!