Python: preserve explicit null arguments in auto function calling

[he-yufeng]

Description

Fixes #5934.

FunctionTool.invoke dumped the validated arguments with model_dump(exclude_none=True), which strips any argument whose value is null. When the model deliberately sets a required nullable parameter to null — e.g. unit: Literal["C", "F"] | None with a description telling the model to set it to null when the user gave no unit — that argument was dropped, and the function then failed to invoke on the missing required argument.

The fix uses exclude_unset=True instead: keep the arguments the model actually provided (an explicit null included) and omit only the ones it left out, so the function's own defaults still apply. Because the tool's input model is generated from the function signature, its field defaults match the signature defaults, so omitted optionals behave exactly as before — only explicitly-provided nulls are now preserved.

Changed both the mapping path (the auto-function-calling path from the model) and the BaseModel path for consistency.

Behavior

For a required nullable parameter the model sets to null:

before (exclude_none):  unit dropped -> TypeError: missing required argument 'unit'
after  (exclude_unset): unit=None passed through -> function runs

An omitted optional argument still falls back to the function's own default (unchanged).

Tests

Adds test_invoke_preserves_explicit_null_argument (the #5934 repro, fails against the old behavior) and test_invoke_omitted_optional_uses_function_default (guards that omitted optionals still use the function default).

[Copilot]

Pull request overview

Fixes a Python tool-invocation edge case where explicitly-provided null arguments were being dropped during argument validation, which can break invocation of required-but-nullable parameters in auto function calling.

Changes:

• Switch FunctionTool.invoke() argument dumping from exclude_none=True to exclude_unset=True to preserve explicit null values while still omitting truly-omitted fields.
• Add regression tests to confirm explicit None is preserved for required nullable parameters and omitted optionals still use function defaults.

Reviewed changes

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

File	Description
python/packages/core/agent_framework/_tools.py	Updates FunctionTool.invoke() argument dumping behavior to preserve explicit nulls.
python/packages/core/tests/core/test_tools.py	Adds regression tests for explicit-null preservation and omitted-optional default behavior.

[he-yufeng]

Good catch, and you're right that this was the path that mattered. I've pushed a follow-up that switches _auto_invoke_function to exclude_unset=True as well, so an explicit null in a model-emitted function_call now reaches the tool instead of being dropped by exclude_none. The three sites (invoke's mapping and BaseModel branches plus the auto-calling path) are consistent now.

[he-yufeng]

Added in the follow-up: test_auto_invoke_preserves_explicit_null_argument drives _auto_invoke_function directly with {"unit": null} and asserts the tool sees None. It fails on the old exclude_none (the required argument goes missing and parsing errors) and passes with the fix, so it guards the auto-calling path specifically.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_tools.py	1162	83	92%	227–228, 405, 407, 420, 445–447, 455, 473, 487, 494, 501, 524, 526, 533, 541, 676, 710–712, 715–717, 719, 725, 776–778, 803, 829, 833, 871–873, 877, 899, 1050, 1062, 1069–1072, 1093, 1101, 1115–1117, 1467, 1562, 1590, 1612, 1620, 1678, 1725, 1732–1733, 1792, 1796, 1849, 1910–1911, 1922, 1994, 2008, 2011, 2024, 2027, 2050, 2057, 2067, 2071, 2148, 2201, 2223, 2279, 2358, 2555, 2621–2622, 2788–2789, 2880
TOTAL	44597	5215	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9052	33 💤	0 ❌	0 🔥	2m 20s ⏱️