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

* Python: clean up kwargs across agents, chat clients, tools, and sessions (#3642)

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

Key changes:
- Add explicit runtime buckets: function_invocation_kwargs and client_kwargs
  on RawAgent.run() and chat client get_response() layers.
- Refactor FunctionTool to prefer explicit ctx: FunctionInvocationContext
  injection; legacy **kwargs tools still work via _forward_runtime_kwargs.
- Refactor Agent.as_tool() to use direct JSON schema, always-streaming
  wrapper, approval_mode parameter, and UserInputRequiredException
  propagation (integrates PR #4568 behavior).
- Remove implicit session bleeding into FunctionInvocationContext; tools
  that need a session must receive it via function_invocation_kwargs.
- Lower chat-client layers after FunctionInvocationLayer accept only
  compatibility **kwargs (client_kwargs flattened, function_invocation_kwargs
  ignored).
- Add layered docstring composition from Raw... implementations via
  _docstrings.py helper.
- Clean up provider constructors to use explicit additional_properties.
- Deprecation warnings on legacy direct kwargs paths.
- Update samples, tests, and typing across all 23 packages.

Resolves #3642

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* clarified docstring

* feedback fixes

* Add unit tests for _docstrings.py build/apply helpers

Tests cover: no docstring source, no extra kwargs, appending to existing
Keyword Args section, inserting after Args, inserting in plain docstrings,
multiline descriptions, ordering, and apply_layered_docstring.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add test for propagate_session TypeError on non-AgentSession values

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add tests for multi-content and empty UserInputRequiredException propagation

Cover the branching logic in _try_execute_function_calls for:
- Multiple user_input_request items in a single exception (extra_user_input_contents path)
- Empty contents list (fallback function_result path)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add tests for DurableAIAgent.get_session forwarding service_session_id

Verifies get_session correctly forwards service_session_id and session_id
to the executor's get_new_session, replacing the removed kwargs test.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Simplify ag-ui test stub to read session from client_kwargs only

Remove dual-mode detection (client_kwargs vs raw kwargs fallback) from
the test mock. Session is now read exclusively from client_kwargs,
matching the settled public calling convention.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* updated create and get sessions in durable

* fixed docstrings

* fix test

* updated session handling

* updated from main

* updated tests

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/packages/durabletask/tests/test_agent_session_id.py

@@ -2,6 +2,8 @@
 
 """Unit tests for AgentSessionId and DurableAgentSession."""
 
+from typing import Any
+
 import pytest
 from agent_framework import AgentSession
 
@@ -153,7 +155,7 @@ class TestDurableAgentSession:
     def test_from_session_id(self) -> None:
         """Test creating DurableAgentSession from session ID."""
         session_id = AgentSessionId(name="TestAgent", key="test-key")
-        session = DurableAgentSession.from_session_id(session_id)
+        session = DurableAgentSession(durable_session_id=session_id)
 
         assert isinstance(session, DurableAgentSession)
         assert session.durable_session_id is not None
@@ -161,10 +163,10 @@ class TestDurableAgentSession:
         assert session.durable_session_id.name == "TestAgent"
         assert session.durable_session_id.key == "test-key"
 
-    def test_from_session_id_with_service_session_id(self) -> None:
-        """Test creating DurableAgentSession with service session ID."""
+    def test_init_with_service_session_id(self) -> None:
+        """Test creating DurableAgentSession with explicit service session ID."""
         session_id = AgentSessionId(name="TestAgent", key="test-key")
-        session = DurableAgentSession.from_session_id(session_id, service_session_id="service-123")
+        session = DurableAgentSession(durable_session_id=session_id, service_session_id="service-123")
 
         assert session.durable_session_id is not None
         assert session.durable_session_id == session_id
@@ -192,7 +194,7 @@ class TestDurableAgentSession:
 
     def test_from_dict_with_durable_session_id(self) -> None:
         """Test deserialization restores durable session ID."""
-        serialized = {
+        serialized: dict[str, Any] = {
             "type": "session",
             "session_id": "session-123",
             "service_session_id": "service-123",
@@ -210,7 +212,7 @@ class TestDurableAgentSession:
 
     def test_from_dict_without_durable_session_id(self) -> None:
         """Test deserialization without durable session ID."""
-        serialized = {
+        serialized: dict[str, Any] = {
             "type": "session",
             "session_id": "session-456",
             "service_session_id": "service-456",

python/packages/durabletask/tests/test_client.py

@@ -88,15 +88,6 @@ class TestDurableAIAgentClientIntegration:
 
         assert isinstance(session, DurableAgentSession)
 
-    def test_client_agent_session_with_parameters(self, agent_client: DurableAIAgentClient) -> None:
-        """Verify agent can create sessions with custom parameters."""
-        agent = agent_client.get_agent("assistant")
-
-        session = agent.create_session(service_session_id="client-session-123")
-
-        assert isinstance(session, DurableAgentSession)
-        assert session.service_session_id == "client-session-123"
-
 
 class TestDurableAIAgentClientPollingConfiguration:
     """Test polling configuration parameters for DurableAIAgentClient."""

python/packages/durabletask/tests/test_orchestration_context.py

@@ -82,17 +82,6 @@ class TestDurableAIAgentOrchestrationContextIntegration:
 
         assert isinstance(session, DurableAgentSession)
 
-    def test_orchestration_agent_session_with_parameters(
-        self, agent_context: DurableAIAgentOrchestrationContext
-    ) -> None:
-        """Verify agent can create sessions with custom parameters."""
-        agent = agent_context.get_agent("assistant")
-
-        session = agent.create_session(service_session_id="orch-session-456")
-
-        assert isinstance(session, DurableAgentSession)
-        assert session.service_session_id == "orch-session-456"
-
 
 if __name__ == "__main__":
     pytest.main([__file__, "-v", "--tb=short"])

python/packages/durabletask/tests/test_shim.py

@@ -184,16 +184,31 @@ class TestDurableAIAgentSessionManagement:
         mock_executor.get_new_session.assert_called_once_with("test_agent")
         assert session == mock_session
 
-    def test_create_session_forwards_kwargs(self, test_agent: DurableAIAgent[Any], mock_executor: Mock) -> None:
-        """Verify create_session forwards kwargs to executor."""
-        mock_session = DurableAgentSession(service_session_id="session-123")
+    def test_get_session_forwards_service_session_id(
+        self, test_agent: DurableAIAgent[Any], mock_executor: Mock
+    ) -> None:
+        """Verify get_session forwards service_session_id and session_id to executor."""
+        mock_session = DurableAgentSession(service_session_id="svc-123")
         mock_executor.get_new_session.return_value = mock_session
 
-        test_agent.create_session(service_session_id="session-123")
+        session = test_agent.get_session("svc-123", session_id="local-456")
 
-        mock_executor.get_new_session.assert_called_once()
-        _, kwargs = mock_executor.get_new_session.call_args
-        assert kwargs["service_session_id"] == "session-123"
+        mock_executor.get_new_session.assert_called_once_with(
+            "test_agent", service_session_id="svc-123", session_id="local-456"
+        )
+        assert session.service_session_id == "svc-123"
+
+    def test_get_session_without_session_id(self, test_agent: DurableAIAgent[Any], mock_executor: Mock) -> None:
+        """Verify get_session works with only service_session_id (session_id defaults to None)."""
+        mock_session = DurableAgentSession(service_session_id="svc-789")
+        mock_executor.get_new_session.return_value = mock_session
+
+        session = test_agent.get_session("svc-789")
+
+        mock_executor.get_new_session.assert_called_once_with(
+            "test_agent", service_session_id="svc-789", session_id=None
+        )
+        assert session.service_session_id == "svc-789"
 
 
 class TestDurableAgentProviderInterface: