Python: Added custom args and thread object to ai_function kwargs

[dmytrostruk]

Motivation and Context

Resolves: #2622

Updated agent and tool invocation logic to include kwargs and thread object from agent.run method in ai_function.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agents.py	291	52	82%	329, 390–392, 438, 492, 510, 672, 853, 856–858, 994–997, 999, 1002–1004, 1100, 1141, 1143, 1152–1157, 1163, 1165, 1175–1176, 1183, 1185–1186, 1194–1198, 1206–1207, 1209, 1214, 1216, 1250, 1295–1296, 1298, 1300, 1311
_tools.py	685	65	90%	224, 270, 321, 323, 486, 518–519, 620, 622, 642, 660, 674, 686, 691, 693, 700, 733, 787–789, 827, 850, 852–861, 870–876, 904, 914, 1098, 1471–1475, 1575, 1644, 1745, 1751, 1794–1795, 1930, 1971–1972, 2000–2002, 2037–2038, 2103–2104, 2111–2112
TOTAL	16601	2572	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2388	130 💤	0 ❌	0 🔥	57.198s ⏱️

[Copilot]

Pull request overview

This PR enables passing custom keyword arguments and thread objects from agent.run() to AI functions via **kwargs, allowing tools to access runtime context without exposing these parameters to the AI model.

Key changes:

• AI functions can now receive runtime kwargs like user_id or thread objects
• The **kwargs parameters are automatically excluded from function schemas
• Thread objects are automatically injected into tool invocations

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
python/packages/core/agent_framework/_tools.py	Added detection logic for **kwargs in function signatures and excluded VAR_KEYWORD parameters from schema generation. Modified AIFunction.__init__ to set _forward_runtime_kwargs flag and updated _create_input_model_from_func to filter out variadic parameters.
python/packages/core/agent_framework/_agents.py	Modified run and run_stream methods to inject thread into kwargs before passing to chat client, and filter thread from kwargs when calling _notify_thread_of_new_messages to avoid duplicate arguments.
python/packages/core/tests/core/test_tools.py	Added comprehensive test test_ai_function_with_kwargs_injection to verify kwargs injection works correctly, schema excludes kwargs, and both direct invocation and invoke method handle kwargs properly.
python/packages/core/tests/core/test_agents.py	Added test test_agent_tool_receives_thread_in_kwargs to verify that thread objects are properly passed to tools through kwargs during agent execution with message stores.
python/samples/getting_started/tools/ai_function_with_kwargs.py	New sample demonstrating how to inject custom arguments like user_id into AI functions for passing runtime context without exposing it to the AI model.
python/samples/getting_started/tools/ai_function_with_thread_injection.py	New sample showing how to access the thread object inside AI functions via kwargs, enabling tools to query conversation history and thread metadata.
python/samples/getting_started/tools/README.md	Updated documentation to include references to the two new sample files demonstrating kwargs injection and thread injection patterns.

[moonbox3]

@dmytrostruk looks like we'll need to pop the thread before calling .run() as these integration tests are failing due to an unexpected thread arg. https://github.com/microsoft/agent-framework/actions/runs/20123952892/job/57749702216#step:6:2256

Should we also make sure we have unit test coverage checking for the proper args? We shouldn't need to wait until failing integration tests to see these types of errors.