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
2026-06-16 21:04:09 +08:00 · 2026-02-12 22:00:32 +01:00
parent 0c67dbbce5
commit 1e350ea22f
312 changed files with 6669 additions and 11423 deletions
@@ -36,11 +36,11 @@ Once comfortable with these, explore the rest of the samples below.
 | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
 | Azure Chat Agents (Streaming)          | [agents/azure_chat_agents_streaming.py](./agents/azure_chat_agents_streaming.py)                               | Add Azure Chat agents as edges and handle streaming events                                           |
 | Azure AI Agents (Streaming)            | [agents/azure_ai_agents_streaming.py](./agents/azure_ai_agents_streaming.py)                                   | Add Azure AI agents as edges and handle streaming events                                             |
-| Azure AI Agents (Shared Thread)        | [agents/azure_ai_agents_with_shared_thread.py](./agents/azure_ai_agents_with_shared_thread.py)                 | Share a common message thread between multiple Azure AI agents in a workflow                         |
+| Azure AI Agents (Shared Thread)        | [agents/azure_ai_agents_with_shared_session.py](./agents/azure_ai_agents_with_shared_session.py)                 | Share a common message session between multiple Azure AI agents in a workflow                        |
 | Custom Agent Executors                 | [agents/custom_agent_executors.py](./agents/custom_agent_executors.py)                                         | Create executors to handle agent run methods                                                         |
 | Workflow as Agent (Reflection Pattern) | [agents/workflow_as_agent_reflection_pattern.py](./agents/workflow_as_agent_reflection_pattern.py)             | Wrap a workflow so it can behave like an agent (reflection pattern)                                  |
 | Workflow as Agent + HITL               | [agents/workflow_as_agent_human_in_the_loop.py](./agents/workflow_as_agent_human_in_the_loop.py)               | Extend workflow-as-agent with human-in-the-loop capability                                           |
-| Workflow as Agent with Thread          | [agents/workflow_as_agent_with_thread.py](./agents/workflow_as_agent_with_thread.py)                           | Use AgentThread to maintain conversation history across workflow-as-agent invocations                |
+| Workflow as Agent with Session         | [agents/workflow_as_agent_with_session.py](./agents/workflow_as_agent_with_session.py)                           | Use AgentSession to maintain conversation history across workflow-as-agent invocations                |
 | Workflow as Agent kwargs               | [agents/workflow_as_agent_kwargs.py](./agents/workflow_as_agent_kwargs.py)                                     | Pass custom context (data, user tokens) via kwargs through workflow.as_agent() to @ai_function tools |

 ### checkpoint
@@ -7,7 +7,7 @@ from agent_framework import (
    AgentExecutor,
    AgentExecutorRequest,
    AgentExecutorResponse,
-    ChatMessageStore,
+    InMemoryHistoryProvider,
    WorkflowBuilder,
    WorkflowContext,
    WorkflowRunState,
@@ -59,22 +59,23 @@ async def main() -> None:
        credential=AzureCliCredential(),
    )

+    # set the same context provider, with the same source_id, for both agents to share the thread
    writer = client.as_agent(
        instructions=("You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt."),
        name="writer",
+        context_providers=[InMemoryHistoryProvider("memory")],
    )

    reviewer = client.as_agent(
        instructions=("You are a thoughtful reviewer. Give brief feedback on the previous assistant message."),
        name="reviewer",
+        context_providers=[InMemoryHistoryProvider("memory")],
    )

-    shared_thread = writer.get_new_thread()
-    # Set the message store to store messages in memory.
-    shared_thread.message_store = ChatMessageStore()
-
-    writer_executor = AgentExecutor(writer, agent_thread=shared_thread)
-    reviewer_executor = AgentExecutor(reviewer, agent_thread=shared_thread)
+    # Create the shared session
+    shared_session = writer.create_session()
+    writer_executor = AgentExecutor(writer, session=shared_session)
+    reviewer_executor = AgentExecutor(reviewer, session=shared_session)

    workflow = (
        WorkflowBuilder(start_executor=writer_executor)
@@ -88,13 +89,15 @@ async def main() -> None:
        # Setting store=False to avoid storing messages in the service for this example.
        options={"store": False},
    )
+
    # The final state should be IDLE since the workflow no longer has messages to
    # process after the reviewer agent responds.
    assert result.get_final_state() == WorkflowRunState.IDLE

-    # The shared thread now contains the conversation between the writer and reviewer. Print it out.
-    print("=== Shared Thread Conversation ===")
-    for message in shared_thread.message_store.messages:
+    # The shared session now contains the conversation between the writer and reviewer. Print it out.
+    print("=== Shared Session Conversation ===")
+    memory_state = shared_session.state.get("memory", {})
+    for message in memory_state.get("messages", []):
        print(f"{message.author_name or message.role}: {message.text}")


@@ -52,7 +52,7 @@ Prerequisites:

 # 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.
+# samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def fetch_product_brief(
    product_name: Annotated[str, Field(description="Product name to look up.")],
@@ -40,7 +40,7 @@ Key Concepts:
 # 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 process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str:
    """Simulated function to process a refund for a given order number."""
@@ -38,7 +38,7 @@ Prerequisites:
 # Define tools that accept custom context via **kwargs
 # 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.
+# samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_user_data(
    query: Annotated[str, Field(description="What user data to retrieve")],
@@ -3,17 +3,17 @@
 import asyncio
 import os

-from agent_framework import AgentThread, ChatMessageStore
+from agent_framework import AgentSession
 from agent_framework.azure import AzureOpenAIResponsesClient
 from agent_framework.orchestrations import SequentialBuilder
 from azure.identity import AzureCliCredential

 """
-Sample: Workflow as Agent with Thread Conversation History and Checkpointing
+Sample: Workflow as Agent with Session Conversation History and Checkpointing

-This sample demonstrates how to use AgentThread with a workflow wrapped as an agent
+This sample demonstrates how to use AgentSession with a workflow wrapped as an agent
 to maintain conversation history across multiple invocations. When using as_agent(),
-the thread's message store history is included in each workflow run, enabling
+the session's history is included in each workflow run, enabling
 the workflow participants to reference prior conversation context.

 It also demonstrates how to enable checkpointing for workflow execution state
@@ -21,8 +21,8 @@ persistence, allowing workflows to be paused and resumed.

 Key concepts:
 - Workflows can be wrapped as agents using workflow.as_agent()
- AgentThread with ChatMessageStore preserves conversation history
- Each call to agent.run() includes thread history + new message
+- AgentSession preserves conversation history
+- Each call to agent.run() includes session history + new message
 - Participants in the workflow see the full conversation context
 - checkpoint_storage parameter enables workflow state persistence

@@ -68,19 +68,18 @@ async def main() -> None:
    # Wrap the workflow as an agent
    agent = workflow.as_agent(name="ConversationalWorkflowAgent")

-    # Create a thread with a ChatMessageStore to maintain history
-    message_store = ChatMessageStore()
-    thread = AgentThread(message_store=message_store)
+    # Create a session to maintain history
+    session = agent.create_session()

    print("=" * 60)
-    print("Workflow as Agent with Thread - Multi-turn Conversation")
+    print("Workflow as Agent with Session - Multi-turn Conversation")
    print("=" * 60)

    # First turn: Introduce a topic
    query1 = "My name is Alex and I'm learning about machine learning."
    print(f"\n[Turn 1] User: {query1}")

-    response1 = await agent.run(query1, thread=thread)
+    response1 = await agent.run(query1, session=session)
    if response1.messages:
        for msg in response1.messages:
            speaker = msg.author_name or msg.role
@@ -90,7 +89,7 @@ async def main() -> None:
    query2 = "What was my name again, and what am I learning about?"
    print(f"\n[Turn 2] User: {query2}")

-    response2 = await agent.run(query2, thread=thread)
+    response2 = await agent.run(query2, session=session)
    if response2.messages:
        for msg in response2.messages:
            speaker = msg.author_name or msg.role
@@ -100,7 +99,7 @@ async def main() -> None:
    query3 = "Can you suggest a good first project for me to try?"
    print(f"\n[Turn 3] User: {query3}")

-    response3 = await agent.run(query3, thread=thread)
+    response3 = await agent.run(query3, session=session)
    if response3.messages:
        for msg in response3.messages:
            speaker = msg.author_name or msg.role
@@ -108,20 +107,20 @@ async def main() -> None:

    # Show the accumulated conversation history
    print("\n" + "=" * 60)
-    print("Full Thread History")
+    print("Full Session History")
    print("=" * 60)
-    if thread.message_store:
-        history = await thread.message_store.list_messages()
-        for i, msg in enumerate(history, start=1):
-            role = msg.role if hasattr(msg.role, "value") else str(msg.role)
-            speaker = msg.author_name or role
-            text_preview = msg.text[:80] + "..." if len(msg.text) > 80 else msg.text
-            print(f"{i:02d}. [{speaker}]: {text_preview}")
+    memory_state = session.state.get("memory", {})
+    history = memory_state.get("messages", [])
+    for i, msg in enumerate(history, start=1):
+        role = msg.role if hasattr(msg.role, "value") else str(msg.role)
+        speaker = msg.author_name or role
+        text_preview = msg.text[:80] + "..." if len(msg.text) > 80 else msg.text
+        print(f"{i:02d}. [{speaker}]: {text_preview}")


-async def demonstrate_thread_serialization() -> None:
+async def demonstrate_session_serialization() -> None:
    """
-    Demonstrates serializing and resuming a thread with a workflow agent.
+    Demonstrates serializing and resuming a session with a workflow agent.

    This shows how conversation history can be persisted and restored,
    enabling long-running conversational workflows.
@@ -140,36 +139,35 @@ async def demonstrate_thread_serialization() -> None:
    workflow = SequentialBuilder(participants=[memory_assistant]).build()
    agent = workflow.as_agent(name="MemoryWorkflowAgent")

-    # Create initial thread and have a conversation
-    thread = AgentThread(message_store=ChatMessageStore())
+    # Create initial session and have a conversation
+    session = agent.create_session()

    print("\n" + "=" * 60)
-    print("Thread Serialization Demo")
+    print("Session Serialization Demo")
    print("=" * 60)

    # First interaction
    query = "Remember this: the secret code is ALPHA-7."
    print(f"\n[Session 1] User: {query}")
-    response = await agent.run(query, thread=thread)
+    response = await agent.run(query, session=session)
    if response.messages:
        print(f"[assistant]: {response.messages[0].text}")

-    # Serialize thread state (could be saved to database/file)
-    serialized_state = await thread.serialize()
-    print("\n[Serialized thread state for persistence]")
+    # Serialize session state (could be saved to database/file)
+    serialized_state = session.to_dict()
+    print("\n[Serialized session state for persistence]")

-    # Simulate a new session by creating a new thread from serialized state
-    restored_thread = AgentThread(message_store=ChatMessageStore())
-    await restored_thread.update_from_thread_state(serialized_state)
+    # Simulate a new session by creating a new session from serialized state
+    restored_session = AgentSession.from_dict(serialized_state)

-    # Continue conversation with restored thread
+    # Continue conversation with restored session
    query = "What was the secret code I told you?"
    print(f"\n[Session 2 - Restored] User: {query}")
-    response = await agent.run(query, thread=restored_thread)
+    response = await agent.run(query, session=restored_session)
    if response.messages:
        print(f"[assistant]: {response.messages[0].text}")


 if __name__ == "__main__":
    asyncio.run(main())
-    asyncio.run(demonstrate_thread_serialization())
+    asyncio.run(demonstrate_session_serialization())
@@ -15,9 +15,9 @@ What you learn:
 - How to resume a workflow-as-agent from a checkpoint

 Key concepts:
- Thread (AgentThread): Maintains conversation history across agent invocations
+- Thread (AgentSession): Maintains conversation history across agent invocations
 - Checkpoint: Persists workflow execution state for pause/resume capability
- These are complementary: threads track conversation, checkpoints track workflow state
+- These are complementary: sessions track conversation, checkpoints track workflow state

 Prerequisites:
 - AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
@@ -28,8 +28,6 @@ import asyncio
 import os

 from agent_framework import (
-    AgentThread,
-    ChatMessageStore,
    InMemoryCheckpointStorage,
 )
 from agent_framework.azure import AzureOpenAIResponsesClient
@@ -102,21 +100,21 @@ async def checkpointing_with_thread() -> None:
    workflow = SequentialBuilder(participants=[assistant]).build()
    agent = workflow.as_agent(name="MemoryAgent")

-    # Create both thread (for conversation) and checkpoint storage (for workflow state)
-    thread = AgentThread(message_store=ChatMessageStore())
+    # Create both session (for conversation) and checkpoint storage (for workflow state)
+    session = agent.create_session()
    checkpoint_storage = InMemoryCheckpointStorage()

    # First turn
    query1 = "My favorite color is blue. Remember that."
    print(f"\n[Turn 1] User: {query1}")
-    response1 = await agent.run(query1, thread=thread, checkpoint_storage=checkpoint_storage)
+    response1 = await agent.run(query1, session=session, checkpoint_storage=checkpoint_storage)
    if response1.messages:
        print(f"[assistant]: {response1.messages[0].text}")

-    # Second turn - agent should remember from thread history
+    # Second turn - agent should remember from session history
    query2 = "What's my favorite color?"
    print(f"\n[Turn 2] User: {query2}")
-    response2 = await agent.run(query2, thread=thread, checkpoint_storage=checkpoint_storage)
+    response2 = await agent.run(query2, session=session, checkpoint_storage=checkpoint_storage)
    if response2.messages:
        print(f"[assistant]: {response2.messages[0].text}")

@@ -124,9 +122,9 @@ async def checkpointing_with_thread() -> None:
    checkpoints = await checkpoint_storage.list_checkpoints(workflow_name=workflow.name)
    print(f"\nTotal checkpoints across both turns: {len(checkpoints)}")

-    if thread.message_store:
-        history = await thread.message_store.list_messages()
-        print(f"Messages in thread history: {len(history)}")
+    memory_state = session.state.get("memory", {})
+    history = memory_state.get("messages", [])
+    print(f"Messages in session history: {len(history)}")


 async def streaming_with_checkpoints() -> None:
@@ -36,7 +36,7 @@ Prerequisites:
 # Define tools that access custom context via **kwargs
 # 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.
+# samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_authenticated_data(
    resource: Annotated[str, "The resource to fetch"],
@@ -39,7 +39,7 @@ MENU_ITEMS = [
 ]


-# 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.
+# 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_sessions.py.
@tool(approval_mode="never_require")
 def get_menu() -> list[dict[str, Any]]:
    """Get all menu items."""
@@ -57,7 +57,7 @@ Prerequisites:
 # 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_current_date() -> str:
    """Get the current date in YYYY-MM-DD format."""
@@ -35,7 +35,7 @@ Key Concepts:
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
 # See:
 # samples/getting_started/tools/function_tool_with_approval.py
-# samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+# samples/getting_started/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str:
    """Simulated function to process a refund for a given order number."""
@@ -32,7 +32,7 @@ Prerequisites:
 # Define tools that accept custom context via **kwargs
 # 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_user_data(
    query: Annotated[str, Field(description="What user data to retrieve")],
@@ -50,7 +50,7 @@ Prerequisites:
 # 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_stock_price(symbol: Annotated[str, "The stock ticker symbol"]) -> str:
    """Get the current stock price for a given symbol."""
@@ -48,7 +48,7 @@ Prerequisites:
 # 1. Define tools for different agents
 # 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 run_tests(test_suite: Annotated[str, "Name of the test suite to run"]) -> str:
    """Run automated tests for the application."""
@@ -58,7 +58,7 @@ def execute_database_query(

 # 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.
+# samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
 def get_database_schema() -> str:
    """Get the current database schema. Does not require approval."""