Python: [BREAKING] PR2 — Wire context provider pipeline, remove old types, update all consumers (#3850)

* PR2: Wire context provider pipeline and update all internal consumers

- Replace AgentThread with AgentSession across all packages
- Replace ContextProvider with BaseContextProvider across all packages
- Replace context_provider param with context_providers (Sequence)
- Replace thread= with session= in run() signatures
- Replace get_new_thread() with create_session()
- Add get_session(service_session_id) to agent interface
- DurableAgentThread -> DurableAgentSession
- Remove _notify_thread_of_new_messages from WorkflowAgent
- Wire before_run/after_run context provider pipeline in RawAgent
- Auto-inject InMemoryHistoryProvider when no providers configured

* fix: update all tests for context provider pipeline, fix lazy-loaders, remove old test files

* refactor: update all sample files for context provider pipeline (AgentThread→AgentSession, ContextProvider→BaseContextProvider)

* fix: update remaining ag-ui references (client docstring, getting_started sample)

* fix: make get_session service_session_id keyword-only to avoid confusion with session_id

* refactor: rename _RunContext.thread_messages to session_messages

* refactor: remove _threads.py, _memory.py, and old provider files; migrate devui to use plain message lists

* rename: remove _new_ prefix from test files

* refactor: rewrite SlidingWindowChatMessageStore as SlidingWindowHistoryProvider(InMemoryHistoryProvider)

* fix: read full history from session state directly instead of reaching into provider internals

* fix: update stale .pyi stubs, sample imports, and README references for new provider types

* fix: remove stale message_store, _notify_thread_of_new_messages, and session_id.key references in samples

* refactor: merge context_providers and sessions sample folders into sessions, remove aggregate_context_provider

* refactor: UserInfoMemory stores state in session.state instead of instance attributes

* feat: add Pydantic BaseModel support to session state serialization

Pydantic models stored in session.state are now automatically serialized
via model_dump() and restored via model_validate() during to_dict()/from_dict()
round-trips. Models are auto-registered on first serialization; use
register_state_type() for cold-start deserialization.

Also export register_state_type as a public API.

* fix mem0

* Update sample README links and descriptions for session terminology

- Replace 'thread' with 'session' in sample descriptions across all READMEs
- Update file links for renamed samples (mem0_sessions, redis_sessions, etc.)
- Fix Threads section → Sessions section in main samples/README.md
- Update tools, middleware, workflows, durabletask, azure_functions READMEs
- Update architecture diagrams in concepts/tools/README.md
- Update migration guides (autogen, semantic-kernel)

* Fix broken Redis README link to renamed sample

* Fix Mem0 OSS client search: pass scoping params as direct kwargs

AsyncMemory (OSS) expects user_id/agent_id/run_id as direct kwargs,
while AsyncMemoryClient (Platform) expects them in a filters dict.
Adds tests for both client types.

Port of fix from #3844 to new Mem0ContextProvider.

* Fix rebase issues: restore missing _conversation_state.py and checkpoint decode logic

- Add back _conversation_state.py (encode/decode_chat_messages) lost in rebase
- Fix on_checkpoint_restore to decode cache/conversation with decode_chat_messages
- Fix on_checkpoint_restore to use decode_checkpoint_value for pending requests
- Add tests/workflow/__init__.py for relative import support
- Fix test_agent_executor checkpoint selection (checkpoints[1] not superstep)

* Add STORES_BY_DEFAULT ClassVar to skip redundant InMemoryHistoryProvider injection

Chat clients that store history server-side by default (OpenAI Responses API,
Azure AI Agent) now declare STORES_BY_DEFAULT = True. The agent checks this
during auto-injection and skips InMemoryHistoryProvider unless the user
explicitly sets store=False.

* Fix broken markdown links in azure_ai and redis READMEs

* Fix getting-started samples to use session API instead of removed thread/ContextProvider API

* updates to workflow as agent

* fix group chat import

* Rename Thread→Session throughout, fix service_session_id propagation, remove stale AGUIThread

- Fix: Propagate conversation_id from ChatResponse back to session.service_session_id
  in both streaming and non-streaming paths in _agents.py
- Rename AgentThreadException → AgentSessionException
- Remove stale AGUIThread from ag_ui lazy-loader
- Rename use_service_thread → use_service_session in ag-ui package
- Rename test functions from *_thread_* to *_session_*
- Rename sample files from *_thread* to *_session*
- Update docstrings and comments: thread → session
- Update _mcp.py kwargs filter: add 'session' alongside 'thread'
- Fix ContinuationToken docstring example: thread=thread → session=session
- Fix _clients.py docstring: 'Agent threads' → 'Agent sessions'

* Fix broken markdown links after thread→session file renames

* fix azure ai test

python/samples/02-agents/providers/azure_ai/README.md

@@ -20,7 +20,7 @@ This folder contains examples demonstrating different ways to create and use age
 | [`azure_ai_with_code_interpreter_file_download.py`](azure_ai_with_code_interpreter_file_download.py) | Shows how to download files generated by code interpreter using the OpenAI containers API. |
 | [`azure_ai_with_content_filtering.py`](azure_ai_with_content_filtering.py) | Shows how to enable content filtering (RAI policy) on Azure AI agents using `RaiConfig`. Requires creating an RAI policy in Azure AI Foundry portal first. |
 | [`azure_ai_with_existing_agent.py`](azure_ai_with_existing_agent.py) | Shows how to work with a pre-existing agent by providing the agent name and version to the Azure AI client. Demonstrates agent reuse patterns for production scenarios. |
-| [`azure_ai_with_existing_conversation.py`](azure_ai_with_existing_conversation.py) | Demonstrates how to use an existing conversation created on the service side with Azure AI agents. Shows two approaches: specifying conversation ID at the client level and using AgentThread with an existing conversation ID. |
+| [`azure_ai_with_existing_conversation.py`](azure_ai_with_existing_conversation.py) | Demonstrates how to use an existing conversation created on the service side with Azure AI agents. Shows two approaches: specifying conversation ID at the client level and using AgentSession with an existing conversation ID. |
 | [`azure_ai_with_application_endpoint.py`](azure_ai_with_application_endpoint.py) | Demonstrates calling the Azure AI application-scoped endpoint. |
 | [`azure_ai_with_explicit_settings.py`](azure_ai_with_explicit_settings.py) | Shows how to create an agent with explicitly configured `AzureAIClient` settings, including project endpoint, model deployment, and credentials rather than relying on environment variable defaults. |
 | [`azure_ai_with_file_search.py`](azure_ai_with_file_search.py) | Shows how to use `AzureAIClient.get_file_search_tool()` with Azure AI agents to upload files, create vector stores, and enable agents to search through uploaded documents to answer user questions. |
@@ -31,7 +31,7 @@ This folder contains examples demonstrating different ways to create and use age
 | [`azure_ai_with_search_context_agentic.py`](../../context_providers/azure_ai_search/azure_ai_with_search_context_agentic.py) | Shows how to use AzureAISearchContextProvider with agentic mode. Uses Knowledge Bases for multi-hop reasoning across documents with query planning. Recommended for most scenarios - slightly slower with more token consumption for query planning, but more accurate results. |
 | [`azure_ai_with_search_context_semantic.py`](../../context_providers/azure_ai_search/azure_ai_with_search_context_semantic.py) | Shows how to use AzureAISearchContextProvider with semantic mode. Fast hybrid search with vector + keyword search and semantic ranking for RAG. Best for simple queries where speed is critical. |
 | [`azure_ai_with_sharepoint.py`](azure_ai_with_sharepoint.py) | Shows how to use SharePoint grounding with Azure AI agents to search through SharePoint content and answer user questions with proper citations. Requires a SharePoint connection configured in your Azure AI project. |
-| [`azure_ai_with_thread.py`](azure_ai_with_thread.py) | Demonstrates thread management with Azure AI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+| [`azure_ai_with_session.py`](azure_ai_with_session.py) | Demonstrates session management with Azure AI agents, including automatic session creation for stateless conversations and explicit session management for maintaining conversation context across multiple interactions. |
 | [`azure_ai_with_image_generation.py`](azure_ai_with_image_generation.py) | Shows how to use `AzureAIClient.get_image_generation_tool()` with Azure AI agents to generate images based on text prompts. |
 | [`azure_ai_with_memory_search.py`](azure_ai_with_memory_search.py) | Shows how to use memory search functionality with Azure AI agents for conversation persistence. Demonstrates creating memory stores and enabling agents to search through conversation history. |
 | [`azure_ai_with_microsoft_fabric.py`](azure_ai_with_microsoft_fabric.py) | Shows how to use Microsoft Fabric with Azure AI agents to query Fabric data sources and provide responses based on data analysis. Requires a Microsoft Fabric connection configured in your Azure AI project. |
@@ -92,4 +92,4 @@ python azure_ai_with_code_interpreter.py
 # ... etc
 ```
 
-The examples demonstrate various patterns for working with Azure AI agents, from basic usage to advanced scenarios like thread management and structured outputs.
+The examples demonstrate various patterns for working with Azure AI agents, from basic usage to advanced scenarios like session management and structured outputs.

python/samples/02-agents/providers/azure_ai/azure_ai_basic.py

@@ -19,7 +19,7 @@ Shows both streaming and non-streaming responses with function tools.
 
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
 @tool(approval_mode="never_require")
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/02-agents/providers/azure_ai/azure_ai_provider_methods.py

@@ -29,7 +29,7 @@ Each method returns a Agent that can be used for conversations.
 
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
 @tool(approval_mode="never_require")
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/02-agents/providers/azure_ai/azure_ai_use_latest_version.py

@@ -20,7 +20,7 @@ while subsequent calls with `get_agent()` reuse the latest agent version.
 
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
 @tool(approval_mode="never_require")
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/02-agents/providers/azure_ai/azure_ai_with_existing_conversation.py

@@ -19,7 +19,7 @@ This sample demonstrates usage of AzureAIProjectAgentProvider with existing conv
 
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
 @tool(approval_mode="never_require")
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -61,9 +61,9 @@ async def example_with_conversation_id() -> None:
         print(f"Agent: {result.text}\n")
 
 
-async def example_with_thread() -> None:
-    """This example shows how to specify existing conversation ID with AgentThread."""
-    print("=== Azure AI Agent With Existing Conversation and Thread ===")
+async def example_with_session() -> None:
+    """This example shows how to specify existing conversation ID with AgentSession."""
+    print("=== Azure AI Agent With Existing Conversation and Session ===")
     async with (
         AzureCliCredential() as credential,
         AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project_client,
@@ -81,23 +81,23 @@ async def example_with_thread() -> None:
         conversation_id = conversation.id
         print(f"Conversation ID: {conversation_id}")
 
-        # Create a thread with the existing ID
-        thread = agent.get_new_thread(service_thread_id=conversation_id)
+        # Create a session with the existing ID
+        session = agent.create_session(service_session_id=conversation_id)
 
         query = "What's the weather like in Seattle?"
         print(f"User: {query}")
-        result = await agent.run(query, thread=thread)
+        result = await agent.run(query, session=session)
         print(f"Agent: {result.text}\n")
 
         query = "What was my last question?"
         print(f"User: {query}")
-        result = await agent.run(query, thread=thread)
+        result = await agent.run(query, session=session)
         print(f"Agent: {result.text}\n")
 
 
 async def main() -> None:
     await example_with_conversation_id()
-    await example_with_thread()
+    await example_with_session()
 
 
 if __name__ == "__main__":

python/samples/02-agents/providers/azure_ai/azure_ai_with_explicit_settings.py

@@ -20,7 +20,7 @@ settings rather than relying on environment variable defaults.
 
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # see samples/02-agents/tools/function_tool_with_approval.py
-# and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
 @tool(approval_mode="never_require")
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/02-agents/providers/azure_ai/azure_ai_with_hosted_mcp.py

@@ -3,7 +3,7 @@
 import asyncio
 from typing import Any
 
-from agent_framework import AgentResponse, AgentThread, Message, SupportsAgentRun
+from agent_framework import AgentResponse, AgentSession, Message, SupportsAgentRun
 from agent_framework.azure import AzureAIClient, AzureAIProjectAgentProvider
 from azure.identity.aio import AzureCliCredential
 
@@ -14,8 +14,8 @@ This sample demonstrates integrating hosted Model Context Protocol (MCP) tools w
 """
 
 
-async def handle_approvals_without_thread(query: str, agent: "SupportsAgentRun") -> AgentResponse:
-    """When we don't have a thread, we need to ensure we return with the input, approval request and approval."""
+async def handle_approvals_without_session(query: str, agent: "SupportsAgentRun") -> AgentResponse:
+    """When we don't have a session, we need to ensure we return with the input, approval request and approval."""
 
     result = await agent.run(query, store=False)
     while len(result.user_input_requests) > 0:
@@ -35,10 +35,10 @@ async def handle_approvals_without_thread(query: str, agent: "SupportsAgentRun")
     return result
 
 
-async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", thread: "AgentThread") -> AgentResponse:
-    """Here we let the thread deal with the previous responses, and we just rerun with the approval."""
+async def handle_approvals_with_session(query: str, agent: "SupportsAgentRun", session: "AgentSession") -> AgentResponse:
+    """Here we let the session deal with the previous responses, and we just rerun with the approval."""
 
-    result = await agent.run(query, thread=thread)
+    result = await agent.run(query, session=session)
     while len(result.user_input_requests) > 0:
         new_input: list[Any] = []
         for user_input_needed in result.user_input_requests:
@@ -53,7 +53,7 @@ async def handle_approvals_with_thread(query: str, agent: "SupportsAgentRun", th
                     contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
                 )
             )
-        result = await agent.run(new_input, thread=thread)
+        result = await agent.run(new_input, session=session)
     return result
 
 
@@ -82,13 +82,13 @@ async def run_hosted_mcp_without_approval() -> None:
 
         query = "How to create an Azure storage account using az cli?"
         print(f"User: {query}")
-        result = await handle_approvals_without_thread(query, agent)
+        result = await handle_approvals_without_session(query, agent)
         print(f"{agent.name}: {result}\n")
 
 
-async def run_hosted_mcp_with_approval_and_thread() -> None:
-    """Example showing MCP Tools with approvals using a thread."""
-    print("=== MCP with approvals and with thread ===")
+async def run_hosted_mcp_with_approval_and_session() -> None:
+    """Example showing MCP Tools with approvals using a session."""
+    print("=== MCP with approvals and with session ===")
 
     # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
     # authentication option.
@@ -111,10 +111,10 @@ async def run_hosted_mcp_with_approval_and_thread() -> None:
             tools=[mcp_tool],
         )
 
-        thread = agent.get_new_thread()
+        session = agent.create_session()
         query = "Please summarize the Azure REST API specifications Readme"
         print(f"User: {query}")
-        result = await handle_approvals_with_thread(query, agent, thread)
+        result = await handle_approvals_with_session(query, agent, session)
         print(f"{agent.name}: {result}\n")
 
 
@@ -122,7 +122,7 @@ async def main() -> None:
     print("=== Azure AI Agent with Hosted MCP Tools Example ===\n")
 
     await run_hosted_mcp_without_approval()
-    await run_hosted_mcp_with_approval_and_thread()
+    await run_hosted_mcp_with_approval_and_session()
 
 
 if __name__ == "__main__":

python/samples/02-agents/providers/azure_ai/azure_ai_with_session.py

@@ -10,17 +10,17 @@ from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
 """
-Azure AI Agent with Thread Management Example
+Azure AI Agent with Session Management Example
 
-This sample demonstrates thread management with Azure AI Agent, showing
-persistent conversation capabilities using service-managed threads as well as storing messages in-memory.
+This sample demonstrates session management with Azure AI Agent, showing
+persistent conversation capabilities using service-managed sessions as well as storing messages in-memory.
 """
 
 
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production
 # See:
 # samples/02-agents/tools/function_tool_with_approval.py
-# samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+# samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
 @tool(approval_mode="never_require")
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -30,9 +30,9 @@ def get_weather(
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
 
-async def example_with_automatic_thread_creation() -> None:
-    """Example showing automatic thread creation."""
-    print("=== Automatic Thread Creation Example ===")
+async def example_with_automatic_session_creation() -> None:
+    """Example showing automatic session creation."""
+    print("=== Automatic Session Creation Example ===")
 
     async with (
         AzureCliCredential() as credential,
@@ -44,26 +44,26 @@ async def example_with_automatic_thread_creation() -> None:
             tools=get_weather,
         )
 
-        # First conversation - no thread provided, will be created automatically
+        # First conversation - no session provided, will be created automatically
         query1 = "What's the weather like in Seattle?"
         print(f"User: {query1}")
         result1 = await agent.run(query1)
         print(f"Agent: {result1.text}")
 
-        # Second conversation - still no thread provided, will create another new thread
+        # Second conversation - still no session provided, will create another new session
         query2 = "What was the last city I asked about?"
         print(f"\nUser: {query2}")
         result2 = await agent.run(query2)
         print(f"Agent: {result2.text}")
-        print("Note: Each call creates a separate thread, so the agent doesn't remember previous context.\n")
+        print("Note: Each call creates a separate session, so the agent doesn't remember previous context.\n")
 
 
-async def example_with_thread_persistence_in_memory() -> None:
+async def example_with_session_persistence_in_memory() -> None:
     """
-    Example showing thread persistence across multiple conversations.
+    Example showing session persistence across multiple conversations.
     In this example, messages are stored in-memory.
     """
-    print("=== Thread Persistence Example (In-Memory) ===")
+    print("=== Session Persistence Example (In-Memory) ===")
 
     async with (
         AzureCliCredential() as credential,
@@ -75,38 +75,38 @@ async def example_with_thread_persistence_in_memory() -> None:
             tools=get_weather,
         )
 
-        # Create a new thread that will be reused
-        thread = agent.get_new_thread()
+        # Create a new session that will be reused
+        session = agent.create_session()
 
         # First conversation
         first_query = "What's the weather like in Tokyo?"
         print(f"User: {first_query}")
-        first_result = await agent.run(first_query, thread=thread, options={"store": False})
+        first_result = await agent.run(first_query, session=session, options={"store": False})
         print(f"Agent: {first_result.text}")
 
-        # Second conversation using the same thread - maintains context
+        # Second conversation using the same session - maintains context
         second_query = "How about London?"
         print(f"\nUser: {second_query}")
-        second_result = await agent.run(second_query, thread=thread, options={"store": False})
+        second_result = await agent.run(second_query, session=session, options={"store": False})
         print(f"Agent: {second_result.text}")
 
         # Third conversation - agent should remember both previous cities
         third_query = "Which of the cities I asked about has better weather?"
         print(f"\nUser: {third_query}")
-        third_result = await agent.run(third_query, thread=thread, options={"store": False})
+        third_result = await agent.run(third_query, session=session, options={"store": False})
         print(f"Agent: {third_result.text}")
-        print("Note: The agent remembers context from previous messages in the same thread.\n")
+        print("Note: The agent remembers context from previous messages in the same session.\n")
 
 
-async def example_with_existing_thread_id() -> None:
+async def example_with_existing_session_id() -> None:
     """
-    Example showing how to work with an existing thread ID from the service.
+    Example showing how to work with an existing session ID from the service.
     In this example, messages are stored on the server.
     """
-    print("=== Existing Thread ID Example ===")
+    print("=== Existing Session ID Example ===")
 
-    # First, create a conversation and capture the thread ID
-    existing_thread_id = None
+    # First, create a conversation and capture the session ID
+    existing_session_id = None
 
     async with (
         AzureCliCredential() as credential,
@@ -118,20 +118,20 @@ async def example_with_existing_thread_id() -> None:
             tools=get_weather,
         )
 
-        # Start a conversation and get the thread ID
-        thread = agent.get_new_thread()
+        # Start a conversation and get the session ID
+        session = agent.create_session()
 
         first_query = "What's the weather in Paris?"
         print(f"User: {first_query}")
-        first_result = await agent.run(first_query, thread=thread)
+        first_result = await agent.run(first_query, session=session)
         print(f"Agent: {first_result.text}")
 
-        # The thread ID is set after the first response
-        existing_thread_id = thread.service_thread_id
-        print(f"Thread ID: {existing_thread_id}")
+        # The session ID is set after the first response
+        existing_session_id = session.service_session_id
+        print(f"Session ID: {existing_session_id}")
 
-        if existing_thread_id:
-            print("\n--- Continuing with the same thread ID in a new agent instance ---")
+        if existing_session_id:
+            print("\n--- Continuing with the same session ID in a new agent instance ---")
 
             # Create a new agent instance from the same provider
             second_agent = await provider.create_agent(
@@ -140,22 +140,22 @@ async def example_with_existing_thread_id() -> None:
                 tools=get_weather,
             )
 
-            # Create a thread with the existing ID
-            thread = second_agent.get_new_thread(service_thread_id=existing_thread_id)
+            # Create a session with the existing ID
+            session = second_agent.create_session(service_session_id=existing_session_id)
 
             second_query = "What was the last city I asked about?"
             print(f"User: {second_query}")
-            second_result = await second_agent.run(second_query, thread=thread)
+            second_result = await second_agent.run(second_query, session=session)
             print(f"Agent: {second_result.text}")
-            print("Note: The agent continues the conversation from the previous thread by using thread ID.\n")
+            print("Note: The agent continues the conversation from the previous session by using session ID.\n")
 
 
 async def main() -> None:
-    print("=== Azure AI Agent Thread Management Examples ===\n")
+    print("=== Azure AI Agent Session Management Examples ===\n")
 
-    await example_with_automatic_thread_creation()
-    await example_with_thread_persistence_in_memory()
-    await example_with_existing_thread_id()
+    await example_with_automatic_session_creation()
+    await example_with_session_persistence_in_memory()
+    await example_with_existing_session_id()
 
 
 if __name__ == "__main__":