Python: [BREAKING] Remove deprecated kwargs compatibility paths

[eavanvalkenburg]

Motivation and Context

PR #4581 introduced explicit runtime buckets such as additional_properties, client_kwargs, and function_invocation_kwargs, but it intentionally left deprecated kwargs-based compatibility paths in place.

This change removes those deprecated paths before more code depends on them again. It is a breaking change because callers that still rely on legacy constructor kwargs, direct runtime run(**kwargs) / get_response(**kwargs) compatibility, or tool invoke(**kwargs) runtime injection now need to move to the explicit APIs.

Workflow run(..., custom_data=...) behavior remains intentionally unchanged in this branch and is tracked separately in #4850.

Description

This PR removes the remaining deprecated kwargs compatibility shims from the Python core stack.

• Remove deprecated constructor kwargs merging from BaseAgent and BaseChatClient, leaving additional_properties as the explicit metadata bucket.
• Remove deprecated runtime kwargs fan-out from agent and chat execution paths so runtime data flows through options, client_kwargs, and function_invocation_kwargs.
• Remove legacy runtime kwargs injection into tool **kwargs; tool runtime context must now flow through FunctionInvocationContext.
• Update middleware, telemetry, MCP, and workflow-internal callers to use the explicit signatures.
• Update focused core tests to match the explicit APIs and delete the legacy kwargs propagation coverage file.

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.

[Copilot]

Pull request overview

Removes deprecated **kwargs compatibility shims across the Python core agent/chat/tool stack, enforcing explicit runtime buckets (options, client_kwargs, function_invocation_kwargs) and FunctionInvocationContext for tool runtime context.

Changes:

• Remove legacy constructor/runtime **kwargs fan-out paths in agents, chat clients, middleware, tools, and telemetry layers.
• Enforce explicit tool runtime context via FunctionInvocationContext (reject unexpected runtime kwargs in FunctionTool.invoke()).
• Update and simplify tests to reflect the explicit APIs; delete legacy kwargs propagation coverage.

Reviewed changes

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

Show a summary per file

File	Description
python/packages/core/tests/core/test_tools.py	Updates tool invocation tests to assert runtime kwargs are rejected and ctx-based flow is required.
python/packages/core/tests/core/test_middleware_with_chat.py	Updates chat middleware tests to use context.options and explicit options={...} calls.
python/packages/core/tests/core/test_middleware_with_agent.py	Updates agent/function middleware tests to use function_invocation_kwargs and options.
python/packages/core/tests/core/test_kwargs_propagation_to_ai_function.py	Removes legacy coverage for kwargs propagation into tool **kwargs.
python/packages/core/tests/core/test_function_invocation_logic.py	Updates function-invocation tests to pass tools/tool_choice via options and session via client_kwargs.
python/packages/core/tests/core/test_clients.py	Changes BaseChatClient constructor test to expect TypeError for direct legacy kwargs.
python/packages/core/tests/core/test_agents.py	Changes Agent constructor test to expect TypeError for direct legacy kwargs; updates option plumbing expectations.
python/packages/core/agent_framework/observability.py	Updates telemetry layers to accept/forward explicit client_kwargs and function_invocation_kwargs (no **kwargs).
python/packages/core/agent_framework/_workflows/_agent_executor.py	Adds typing casts for new run signatures while continuing to pass workflow run kwargs into agent execution.
python/packages/core/agent_framework/_tools.py	Removes legacy runtime kwargs injection; enforces ctx-based runtime flow; tightens invoke() kwarg handling.
python/packages/core/agent_framework/_middleware.py	Updates middleware layers/signatures for explicit runtime buckets; adds run-level tools plumbing.
python/packages/core/agent_framework/_mcp.py	Updates MCP callback to pass model settings via options dict instead of direct kwargs.
python/packages/core/agent_framework/_clients.py	Removes legacy constructor kwargs merge; updates get_response signatures to explicit runtime buckets.
python/packages/core/agent_framework/_agents.py	Removes run(**kwargs) and constructor kwargs merge; adds explicit additional_properties and middleware plumbing.

Comments suppressed due to low confidence (2)

python/packages/core/agent_framework/_workflows/_agent_executor.py:362

• AgentExecutor still forwards **run_kwargs into agent.run(). After this PR removes run(**kwargs) compatibility, any workflow-level kwargs stored under WORKFLOW_RUN_KWARGS_KEY (e.g., custom_data / arbitrary values intended for tool context) will now raise TypeError at runtime. Since _prepare_agent_run_args already merges these values into options["additional_function_arguments"], run_kwargs should be filtered down to only explicit agent.run parameters (or cleared) before spreading into run().

        run_kwargs, options = self._prepare_agent_run_args(ctx.get_state(WORKFLOW_RUN_KWARGS_KEY, {}))

        run_agent = cast(Callable[..., Awaitable[AgentResponse[Any]]], self._agent.run)
        response = await run_agent(
            self._cache,
            stream=False,
            session=self._session,
            options=options,
            **run_kwargs,
        )

python/packages/core/agent_framework/_workflows/_agent_executor.py:394

• Same issue in the streaming path: spreading **run_kwargs into agent.run(stream=True, ...) will now fail for workflow-provided arbitrary kwargs after removal of run(**kwargs) compatibility. Filter/clear run_kwargs (keeping only explicit agent.run parameters) and rely on options["additional_function_arguments"] / function_invocation_kwargs for propagating workflow runtime data.

        run_agent_stream = cast(Callable[..., ResponseStream[AgentResponseUpdate, AgentResponse[Any]]], self._agent.run)
        stream = run_agent_stream(
            self._cache,
            stream=True,
            session=self._session,
            options=options,
            **run_kwargs,
        )

[eavanvalkenburg]

Automated Code Review

Reviewers: 4 | Confidence: 83%

✗ Correctness

This PR removes deprecated **kwargs patterns across the agent framework, replacing them with explicit function_invocation_kwargs and client_kwargs parameters. The changes are internally consistent and tests are properly updated. One concrete bug: in ChatMiddlewareLayer.get_response(), context_kwargs is copied from effective_client_kwargs before middleware is popped, so a middleware key in client_kwargs would leak into context.kwargs and eventually downstream client_kwargs / _inner_get_response(). The old code popped middleware before constructing context kwargs. Additionally, removing the VAR_KEYWORD continue in _discover_injected_parameters introduces a theoretical edge case where **ctx without annotation on a tool with explicit input_model could be misidentified as a context parameter.

✓ Security Reliability

This PR removes deprecated **kwargs pass-through patterns across the agent/client/tool APIs, replacing them with explicit named parameters (function_invocation_kwargs, client_kwargs, tool_call_id). This is a positive security change: it eliminates an injection vector where arbitrary keyword arguments could leak into tool invocations, client calls, or middleware contexts. The main concerns are: (1) the _mcp.py sampling callback uses chat_client: Any cast to bypass type checking, which silently hides signature mismatches and could cause runtime errors; (2) exception messages in _tools.py include user-controlled parameter names which is a minor info-leak concern but acceptable for developer-facing errors; (3) the _agent_executor.py introduces cast(Callable[...], self._agent.run) which bypasses type safety unnecessarily. No blocking security issues found.

✓ Test Coverage

This PR removes deprecated **kwargs patterns, replacing them with explicit parameters (function_invocation_kwargs, client_kwargs, tool_call_id). Test updates are mostly consistent with the code changes—deprecation-warning tests are replaced with TypeError-rejection tests, and middleware tests are updated to use the new explicit parameter style. However, the complete deletion of test_kwargs_propagation_to_ai_function.py removes the only end-to-end integration test verifying clean separation of function_invocation_kwargs vs client_kwargs through the full Agent → Client → Tool pipeline. Additionally, the MCP sampling_callback calling-convention change (positional kwargs to options dict) has no test verifying the new argument format, and the new AgentContext.tools attribute has no middleware-level test coverage.

✗ Design Approach

The PR cleanly removes the deprecated **kwargs forwarding paths throughout the agent/client/tool stack and replaces them with explicit function_invocation_kwargs / client_kwargs / options parameters. The intent and scope are correct. There is one concrete regression introduced by the refactoring: in ChatMiddlewareLayer.get_response, context_kwargs is now constructed from effective_client_kwargs before middleware is popped from that dict. In the old code the ChatContext.kwargs dict was built after the pop ({**effective_client_kwargs, **kwargs} where effective_client_kwargs already had middleware removed). In the new code any middleware key present in client_kwargs survives into context_kwargs, then gets forwarded by _middleware_handler as part of client_kwargs to the next layer, where downstream code pops and re-applies it — resulting in double middleware application. A secondary concern is the _mcp.py fix using chat_client: Any = self.client / response: Any = ... to silence a type-checker complaint; cast(SupportsChatGetResponse[Any], self.client) would constrain the escape to the minimum necessary. Finally, AgentContext.kwargs is kept as a public field but is now always {} because kwargs=kwargs is no longer passed at construction; existing middleware that reads context.kwargs to observe runtime parameters will silently see an empty dict with no deprecation warning.

---

Automated review by eavanvalkenburg's agents

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azure-ai/agent_framework_azure_ai
_agent_provider.py	118	1	99%	279
_client.py	402	48	88%	221, 401, 403, 451, 461–465, 467–473, 486, 547, 562–567, 620–621, 647–648, 666, 697, 699, 720–721, 724, 769, 772, 774, 865, 896, 938, 1147, 1150, 1153–1154, 1156–1159
_project_provider.py	125	5	96%	159, 215, 314, 354, 387
packages/claude/agent_framework_claude
_agent.py	279	28	89%	328–329, 333, 345, 353–355, 357–358, 388–390, 409, 413, 415, 419, 428, 474, 477, 498, 503–504, 571, 658, 684–687
packages/core/agent_framework
_agents.py	357	47	86%	456, 460, 515, 915, 951, 967, 1063–1067, 1121, 1149, 1274, 1290, 1292, 1305, 1311, 1356, 1358, 1367–1372, 1377, 1379, 1385–1386, 1393, 1395–1396, 1404–1405, 1408–1410, 1420–1425, 1429, 1434, 1436
_clients.py	138	7	94%	325, 377, 533–536, 645
_mcp.py	559	29	94%	269, 329–330, 459, 521, 534, 536–539, 558–559, 572–575, 577–578, 582, 644–646, 968, 1081, 1133–1134, 1137, 1155, 1560
_middleware.py	366	16	95%	61, 64, 69, 798, 814, 816, 818, 951, 954, 981, 983, 1114, 1118, 1300, 1304, 1372
_tools.py	934	85	90%	190–191, 364, 366, 379, 404–406, 414, 432, 446, 453, 460, 483, 485, 492, 500, 539, 583, 587, 619–621, 623, 629, 674–676, 678, 701, 727, 769–771, 775, 797, 909–915, 951, 963, 965, 967, 970–973, 994, 998, 1002, 1016–1018, 1359, 1381, 1468–1474, 1603, 1607, 1653, 1802, 1822, 1824, 1880, 1943, 2115–2116, 2136, 2192–2193, 2248, 2321–2322, 2384, 2389, 2396
observability.py	745	84	88%	377, 379–380, 383, 386, 389–390, 395–396, 402–403, 409–410, 417, 419–421, 424–426, 431–432, 438–439, 445–446, 453, 610–611, 739, 743–745, 747, 751–752, 756, 794, 796, 807–809, 811–813, 817, 825, 949–950, 1112, 1351–1352, 1450–1455, 1462–1465, 1469–1477, 1484, 1588, 1622–1626, 1683–1684, 1815, 2013, 2231, 2233
packages/core/agent_framework/_workflows
_agent_executor.py	206	19	90%	109, 133, 174, 200–201, 256–257, 259–260, 296–298, 300, 310–311, 412–413, 478, 497
packages/foundry_local/agent_framework_foundry_local
_foundry_local_client.py	48	5	89%	202, 206–209
packages/openai/agent_framework_openai
_chat_client.py	885	133	84%	357, 359–360, 417–418, 420, 452, 514–517, 521–522, 527–528, 538–539, 546, 561–567, 588, 596, 619, 716, 815, 874, 876, 878, 880, 946, 960, 1040, 1050, 1055, 1098, 1176, 1193, 1206, 1263, 1356, 1361, 1365–1367, 1371–1372, 1438, 1467, 1473, 1483, 1489, 1494, 1500, 1505–1506, 1567, 1589–1590, 1605–1606, 1624–1625, 1666–1669, 1831, 1886, 1888, 1968–1976, 2098, 2153, 2168, 2188–2198, 2211, 2222–2226, 2240, 2254–2265, 2274, 2306–2309, 2317–2318, 2320–2322, 2336–2338, 2348–2349, 2355, 2370
_chat_completion_client.py	391	34	91%	254, 256–257, 304, 308, 340, 393, 489–490, 494, 631, 714–721, 723–726, 736, 814, 816, 833, 854, 882, 895, 919, 939, 979, 1058
TOTAL	27943	3417	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5415	20 💤	0 ❌	0 🔥	1m 26s ⏱️