[BREAKING] Python: clean up kwargs across agents, chat clients, tools, and sessions

[eavanvalkenburg]

Motivation and Context

Resolves #3642 — the Python codebase relied heavily on blanket **kwargs across public APIs (agents, chat clients, tools, sessions), making it difficult to discover available parameters, catch mistakes at type-check time, and reason about what data flows where.

Description

Audit and refactor public **kwargs usage across core agents, chat clients, tools, sessions, and provider packages. The migration strategy is codified in CODING_STANDARD.md.

Explicit runtime buckets replace blanket **kwargs forwarding:

• RawAgent.run(..., function_invocation_kwargs=..., client_kwargs=...)
• Chat client get_response() layers use the same split; below FunctionInvocationLayer only compatibility **kwargs remain (client_kwargs flattened, function_invocation_kwargs ignored).

FunctionTool context injection — tools now prefer an explicit ctx: FunctionInvocationContext parameter. Legacy **kwargs tools still work via _forward_runtime_kwargs.

Agent.as_tool() refactor — direct JSON schema (no generated Pydantic model), always-streaming wrapper, approval_mode parameter, and UserInputRequiredException propagation (integrates #4568 behavior).

Session decoupled from function context — FunctionInvocationContext no longer has a session attribute. Tools that need a session must receive it explicitly via function_invocation_kwargs.

Layered docstrings — public APIs compose docstrings from the nearest Raw... implementation via a new _docstrings.py helper.

Provider constructors cleaned up to use explicit additional_properties. Deprecation warnings on all legacy direct kwargs paths.

Updated samples, tests, and typing across all 23 packages.

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

Refactors Python public APIs to reduce ambiguous **kwargs usage by introducing explicit runtime buckets (function_invocation_kwargs, client_kwargs) and a first-class FunctionInvocationContext injection mechanism for tools, while updating provider/client constructors to use additional_properties and aligning docstrings/tests/samples to the new calling patterns.

Changes:

• Replaces broad **kwargs forwarding with explicit function_invocation_kwargs and client_kwargs across agent and chat-client layers, adding compatibility deprecation warnings.
• Updates @tool runtime injection to prefer an explicit/typed FunctionInvocationContext parameter (with legacy **kwargs support retained for now).
• Refactors Agent.as_tool() to use an explicit JSON schema, always-streaming execution, approval-mode support, and correct propagation of user_input_request via UserInputRequiredException.

Reviewed changes

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

Show a summary per file

File	Description
python/samples/02-agents/tools/function_tool_with_session_injection.py	Updates sample to pass sessions via function_invocation_kwargs and consume via FunctionInvocationContext.
python/samples/02-agents/tools/function_tool_with_kwargs.py	Updates sample to demonstrate context-based runtime injection instead of **kwargs.
python/samples/02-agents/tools/agent_as_tool_with_session_propagation.py	Updates sample to explicitly pass session via function_invocation_kwargs and show propagation semantics.
python/packages/redis/agent_framework_redis/_history_provider.py	Adds explicit state= keyword-only parameter to history provider interface methods.
python/packages/ollama/agent_framework_ollama/_embedding_client.py	Replaces constructor **kwargs passthrough with explicit additional_properties.
python/packages/ollama/agent_framework_ollama/_chat_client.py	Replaces constructor **kwargs passthrough with explicit additional_properties.
python/packages/github_copilot/agent_framework_github_copilot/_agent.py	Removes unused **kwargs from agent run surface and internal helpers.
python/packages/foundry_local/agent_framework_foundry_local/_foundry_local_client.py	Replaces wrapper **kwargs passthrough with explicit additional_properties.
python/packages/durabletask/tests/test_shim.py	Removes tests that validated kwargs-forwarding behavior for session creation.
python/packages/durabletask/tests/test_orchestration_context.py	Removes tests relying on session creation with extra parameters.
python/packages/durabletask/tests/test_client.py	Removes tests relying on session creation with extra parameters.
python/packages/durabletask/tests/test_agent_session_id.py	Updates durable session construction/serialization tests to match new init/from_dict behavior.
python/packages/durabletask/agent_framework_durabletask/_shim.py	Adjusts durable shim session APIs and behavior to align with narrowed session interfaces.
python/packages/durabletask/agent_framework_durabletask/_models.py	Refactors DurableAgentSession initialization/serialization and durable session id handling.
python/packages/durabletask/agent_framework_durabletask/_executors.py	Makes durable executor session creation explicit (session_id, service_session_id).
python/packages/devui/agent_framework_devui/models/_discovery_models.py	Import ordering cleanup.
python/packages/declarative/agent_framework_declarative/_workflows/_executors_tools.py	Import ordering cleanup.
python/packages/core/tests/core/test_tools.py	Adds coverage for typed/untyped FunctionInvocationContext injection and validation constraints.
python/packages/core/tests/core/test_sessions.py	Updates test history provider to accept explicit state= kw-only arg.
python/packages/core/tests/core/test_kwargs_propagation_to_ai_function.py	Adds/adjusts tests to validate separation of runtime buckets and legacy kwargs compatibility.
python/packages/core/tests/core/test_function_invocation_logic.py	Adds test ensuring user_input_request propagates through as_tool() execution.
python/packages/core/tests/core/test_embedding_client.py	Adds test ensuring embedding clients reject unknown kwargs (tightening constructor surfaces).
python/packages/core/tests/core/test_clients.py	Adds tests for docstrings layering and explicit additional_properties/client_kwargs behaviors.
python/packages/core/tests/core/test_as_tool_kwargs_propagation.py	Updates tests to use FunctionInvocationContext and validate function_invocation_kwargs propagation semantics.
python/packages/core/tests/core/test_agents.py	Updates as_tool() expectations (schema, streaming finalization) and session/tool-kwargs semantics; adds docstring tests.
python/packages/core/agent_framework/openai/_chat_client.py	Adds overloads + layered docstring application for OpenAI clients while preserving runtime signature semantics.
python/packages/core/agent_framework/observability.py	Updates telemetry layers to flatten client_kwargs and ignore already-processed function_invocation_kwargs.
python/packages/core/agent_framework/exceptions.py	Introduces UserInputRequiredException for propagating user-input requests through tool/agent layers.
python/packages/core/agent_framework/azure/_chat_client.py	Replaces constructor **kwargs passthrough with explicit additional_properties.
python/packages/core/agent_framework/_types.py	Adjusts ResponseStream hook typing to allow `Awaitable[UpdateT
python/packages/core/agent_framework/_tools.py	Adds context injection discovery, explicit context= param for invoke, legacy kwargs deprecation warnings, and user-input propagation handling.
python/packages/core/agent_framework/_skills.py	Minor formatting simplification.
python/packages/core/agent_framework/_sessions.py	Makes state= explicit in history provider abstract methods for known data flow.
python/packages/core/agent_framework/_middleware.py	Splits legacy runtime kwargs from client_kwargs and function_invocation_kwargs in contexts; updates chat/agent middleware plumbing accordingly.
python/packages/core/agent_framework/_docstrings.py	New helper to layer/extend docstrings from raw implementations.
python/packages/core/agent_framework/_clients.py	Introduces docstring layering; updates BaseChatClient.get_response compatibility flattening and as_agent(additional_properties=...).
python/packages/core/agent_framework/_agents.py	Adds runtime bucket parameters; refactors as_tool() schema + always-streaming wrapper; adds docstring layering; deprecates direct run kwargs.
python/packages/core/agent_framework/init.py	Exports UserInputRequiredException.
python/packages/copilotstudio/agent_framework_copilotstudio/_agent.py	Removes unused **kwargs from run surface and internal helpers.
python/packages/claude/agent_framework_claude/_agent.py	Aligns run signature with explicit options + bucket params (ignored for this provider).
python/packages/bedrock/agent_framework_bedrock/_embedding_client.py	Replaces constructor **kwargs passthrough with explicit additional_properties.
python/packages/bedrock/agent_framework_bedrock/_chat_client.py	Replaces constructor **kwargs passthrough with explicit additional_properties.
python/packages/azure-cosmos/agent_framework_azure_cosmos/_history_provider.py	Adds explicit state= kw-only arg to match updated history provider interface.
python/packages/azure-ai/agent_framework_azure_ai/_embedding_client.py	Replaces constructor **kwargs passthrough with explicit additional_properties.
python/packages/azure-ai/agent_framework_azure_ai/_client.py	Replaces constructor **kwargs passthrough with explicit additional_properties.
python/packages/azure-ai/agent_framework_azure_ai/_chat_client.py	Replaces constructor **kwargs passthrough with explicit additional_properties.
python/packages/azure-ai-search/tests/test_aisearch_context_provider.py	Adds fixture to clear env vars for test isolation.
python/packages/anthropic/agent_framework_anthropic/_chat_client.py	Replaces constructor **kwargs passthrough with explicit additional_properties.
python/packages/ag-ui/tests/ag_ui/test_agent_wrapper_comprehensive.py	Updates AG-UI wrapper test to capture session at call-time rather than via client kwargs.
python/packages/ag-ui/tests/ag_ui/conftest.py	Updates stub client to read session from client_kwargs compatibility path.
python/packages/ag-ui/agent_framework_ag_ui/_client.py	Removes unused **kwargs passthrough from client constructor.
python/packages/a2a/agent_framework_a2a/_agent.py	Aligns run signature with explicit bucket params (ignored for this provider).
python/CODING_STANDARD.md	Codifies the **kwargs migration strategy and preferred explicit “buckets”.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/a2a/agent_framework_a2a
_agent.py	179	13	92%	375, 396, 417, 437, 451, 465, 477–478, 519–520, 549–551
packages/ag-ui/agent_framework_ag_ui
_client.py	147	13	91%	85–86, 90–94, 98–102, 262
packages/anthropic/agent_framework_anthropic
_chat_client.py	416	34	91%	430, 433, 514, 601, 603, 746–747, 825, 855–856, 901, 917–918, 925–927, 931–933, 937–940, 1054, 1064, 1116, 1237, 1264–1265, 1282, 1295, 1308, 1333–1334
packages/azure-ai/agent_framework_azure_ai
_chat_client.py	482	76	84%	415–416, 418, 602, 607–608, 610–611, 614, 617, 619, 624, 885–886, 888, 891, 894, 897–902, 905, 907, 915, 927–929, 933, 936–937, 945–948, 958, 966–969, 971–972, 974–975, 982, 990–991, 999–1012, 1017, 1020, 1028, 1034, 1042–1044, 1047, 1067–1068, 1201, 1228, 1243, 1359
_client.py	405	49	87%	214, 392, 394, 442, 452–456, 458–464, 477, 538, 553–558, 600, 616–617, 643–644, 662, 697, 699, 720–721, 724, 769, 772, 774, 865, 896, 938, 1147, 1150, 1153–1154, 1156–1159
_embedding_client.py	113	12	89%	152, 167–170, 174, 178, 228, 238, 249, 258, 284
packages/copilotstudio/agent_framework_copilotstudio
_agent.py	84	2	97%	174, 182
packages/core/agent_framework
_agents.py	360	44	87%	467, 471, 530, 561, 924, 960, 976, 1065–1069, 1119, 1141, 1266, 1282, 1284, 1297, 1303, 1339, 1341, 1350–1355, 1360, 1362, 1368–1369, 1376, 1378–1379, 1387–1388, 1391–1393, 1401–1402, 1404, 1409, 1411
_clients.py	105	2	98%	316, 544
_docstrings.py	46	5	89%	33, 41–42, 56, 69
_middleware.py	340	18	94%	60, 63, 68, 776, 792, 794, 796, 919, 922, 949, 951, 976, 1068, 1072, 1224, 1228, 1300, 1374
_sessions.py	171	16	90%	67–69, 71–74, 91–92, 94–98, 589, 602
_tools.py	865	77	91%	170–171, 346, 348, 361, 390–392, 400, 418, 432, 439, 446, 463, 465, 472, 480, 514, 562, 566, 606–608, 655–657, 679, 735, 757, 824–830, 866, 878, 880, 882, 885–888, 909, 913, 917, 931–933, 1272, 1292, 1377–1383, 1509, 1513, 1526, 1558, 1676, 1706, 1726, 1728, 1784, 1847, 2062–2063, 2114, 2183–2184, 2244, 2249, 2256
_types.py	1017	86	91%	58, 67–68, 122, 127, 146, 148, 152, 156, 158, 160, 162, 180, 184, 210, 232, 237, 242, 246, 276, 652–653, 1161, 1232, 1267, 1285, 1295, 1339, 1471–1473, 1661, 1752–1757, 1782, 1950, 1962, 2211, 2232, 2327, 2556, 2759, 2828, 2839, 2841–2845, 2847, 2850–2858, 2868, 3073–3075, 3078–3080, 3084, 3089, 3093, 3177–3179, 3208, 3262, 3281–3282, 3285–3289, 3295
exceptions.py	66	0	100%
observability.py	676	51	92%	369–370, 397, 399–401, 404–406, 411–412, 418–419, 425–426, 716, 720–722, 724, 1067–1071, 1273–1274, 1368–1373, 1380–1383, 1387–1395, 1402, 1508, 1688, 2072, 2074
packages/core/agent_framework/azure
_chat_client.py	89	5	94%	305, 307, 320–321, 332
packages/core/agent_framework/openai
_chat_client.py	321	27	91%	212, 293–294, 298, 423, 430, 506–513, 515–518, 528, 606, 608, 625, 663, 676, 700, 716, 756
packages/redis/agent_framework_redis
_history_provider.py	59	1	98%	191
TOTAL	22874	2603	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4965	20 💤	0 ❌	0 🔥	1m 22s ⏱️

[TaoChenOSU]

Question: what does it mean here by "sub-agent"? Is it when an agent is used as a tool and this agent (the parent) is given the tool?

[eavanvalkenburg]

Yes that is indeed meant for Agent as tool being added to another agent, not orchestrations, I can clarify