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
@@ -0,0 +1,55 @@
+# Mem0 Context Provider Examples
+
+[Mem0](https://mem0.ai/) is a self-improving memory layer for Large Language Models that enables applications to have long-term memory capabilities. The Agent Framework's Mem0 context provider integrates with Mem0's API to provide persistent memory across conversation sessions.
+
+This folder contains examples demonstrating how to use the Mem0 context provider with the Agent Framework for persistent memory and context management across conversations.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`mem0_basic.py`](mem0_basic.py) | Basic example of using Mem0 context provider to store and retrieve user preferences across different conversation sessions. |
+| [`mem0_sessions.py`](mem0_sessions.py) | Advanced example demonstrating different session scoping strategies with Mem0. Covers global session scope (memories shared across all operations), per-operation session scope (memories isolated per session), and multiple agents with different memory configurations for personal vs. work contexts. |
+| [`mem0_oss.py`](mem0_oss.py) | Example of using the Mem0 Open Source self-hosted version as the context provider. Demonstrates setup and configuration for local deployment. |
+
+## Prerequisites
+
+### Required Resources
+
+1. [Mem0 API Key](https://app.mem0.ai/) - Sign up for a Mem0 account and get your API key - _or_ self-host [Mem0 Open Source](https://docs.mem0.ai/open-source/overview)
+2. Azure AI project endpoint (used in these examples)
+3. Azure CLI authentication (run `az login`)
+
+## Configuration
+
+### Environment Variables
+
+Set the following environment variables:
+
+**For Mem0 Platform:**
+- `MEM0_API_KEY`: Your Mem0 API key (alternatively, pass it as `api_key` parameter to `Mem0Provider`). Not required if you are self-hosting [Mem0 Open Source](https://docs.mem0.ai/open-source/overview)
+
+**For Mem0 Open Source:**
+- `OPENAI_API_KEY`: Your OpenAI API key (used by Mem0 OSS for embedding generation and automatic memory extraction)
+
+**For Azure AI:**
+- `AZURE_AI_PROJECT_ENDPOINT`: Your Azure AI project endpoint
+- `AZURE_AI_MODEL_DEPLOYMENT_NAME`: The name of your model deployment
+
+## Key Concepts
+
+### Memory Scoping
+
+The Mem0 context provider supports different scoping strategies:
+
+- **Global Scope** (`scope_to_per_operation_thread_id=False`): Memories are shared across all conversation sessions
+- **Session Scope** (`scope_to_per_operation_thread_id=True`): Memories are isolated per conversation session
+
+### Memory Association
+
+Mem0 records can be associated with different identifiers:
+
+- `user_id`: Associate memories with a specific user
+- `agent_id`: Associate memories with a specific agent
+- `thread_id`: Associate memories with a specific conversation session
+- `application_id`: Associate memories with an application context
@@ -0,0 +1,82 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import uuid
+
+from agent_framework import tool
+from agent_framework.azure import AzureAIAgentClient
+from agent_framework.mem0 import Mem0ContextProvider
+from azure.identity.aio import AzureCliCredential
+
+
+# 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 retrieve_company_report(company_code: str, detailed: bool) -> str:
+    if company_code != "CNTS":
+        raise ValueError("Company code not found")
+    if not detailed:
+        return "CNTS is a company that specializes in technology."
+    return (
+        "CNTS is a company that specializes in technology. "
+        "It had a revenue of $10 million in 2022. It has 100 employees."
+    )
+
+
+async def main() -> None:
+    """Example of memory usage with Mem0 context provider."""
+    print("=== Mem0 Context Provider Example ===")
+
+    # Each record in Mem0 should be associated with agent_id or user_id or application_id or thread_id.
+    # In this example, we associate Mem0 records with user_id.
+    user_id = str(uuid.uuid4())
+
+    # For Azure authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    # For Mem0 authentication, set Mem0 API key via "api_key" parameter or MEM0_API_KEY environment variable.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(credential=credential).as_agent(
+            name="FriendlyAssistant",
+            instructions="You are a friendly assistant.",
+            tools=retrieve_company_report,
+            context_providers=[Mem0ContextProvider(user_id=user_id)],
+        ) as agent,
+    ):
+        # First ask the agent to retrieve a company report with no previous context.
+        # The agent will not be able to invoke the tool, since it doesn't know
+        # the company code or the report format, so it should ask for clarification.
+        query = "Please retrieve my company report"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+        # Now tell the agent the company code and the report format that you want to use
+        # and it should be able to invoke the tool and return the report.
+        query = "I always work with CNTS and I always want a detailed report format. Please remember and retrieve it."
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+        # Mem0 processes and indexes memories asynchronously.
+        # Wait for memories to be indexed before querying in a new thread.
+        # In production, consider implementing retry logic or using Mem0's
+        # eventual consistency handling instead of a fixed delay.
+        print("Waiting for memories to be processed...")
+        await asyncio.sleep(12)  # Empirically determined delay for Mem0 indexing
+
+        print("\nRequest within a new session:")
+        # Create a new session for the agent.
+        # The new session has no context of the previous conversation.
+        session = agent.create_session()
+
+        # Since we have the mem0 component in the session, the agent should be able to
+        # retrieve the company report without asking for clarification, as it will
+        # be able to remember the user preferences from Mem0 component.
+        query = "Please retrieve my company report"
+        print(f"User: {query}")
+        result = await agent.run(query, session=session)
+        print(f"Agent: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,79 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import uuid
+
+from agent_framework import tool
+from agent_framework.azure import AzureAIAgentClient
+from agent_framework.mem0 import Mem0ContextProvider
+from azure.identity.aio import AzureCliCredential
+from mem0 import AsyncMemory
+
+
+# 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 retrieve_company_report(company_code: str, detailed: bool) -> str:
+    if company_code != "CNTS":
+        raise ValueError("Company code not found")
+    if not detailed:
+        return "CNTS is a company that specializes in technology."
+    return (
+        "CNTS is a company that specializes in technology. "
+        "It had a revenue of $10 million in 2022. It has 100 employees."
+    )
+
+
+async def main() -> None:
+    """Example of memory usage with local Mem0 OSS context provider."""
+    print("=== Mem0 Context Provider Example ===")
+
+    # Each record in Mem0 should be associated with agent_id or user_id or application_id or thread_id.
+    # In this example, we associate Mem0 records with user_id.
+    user_id = str(uuid.uuid4())
+
+    # For Azure authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    # By default, local Mem0 authenticates to your OpenAI using the OPENAI_API_KEY environment variable.
+    # See the Mem0 documentation for other LLM providers and authentication options.
+    local_mem0_client = AsyncMemory()
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(credential=credential).as_agent(
+            name="FriendlyAssistant",
+            instructions="You are a friendly assistant.",
+            tools=retrieve_company_report,
+            context_providers=[Mem0ContextProvider(user_id=user_id, mem0_client=local_mem0_client)],
+        ) as agent,
+    ):
+        # First ask the agent to retrieve a company report with no previous context.
+        # The agent will not be able to invoke the tool, since it doesn't know
+        # the company code or the report format, so it should ask for clarification.
+        query = "Please retrieve my company report"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+        # Now tell the agent the company code and the report format that you want to use
+        # and it should be able to invoke the tool and return the report.
+        query = "I always work with CNTS and I always want a detailed report format. Please remember and retrieve it."
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+        print("\nRequest within a new session:")
+
+        # Create a new session for the agent.
+        # The new session has no context of the previous conversation.
+        session = agent.create_session()
+
+        # Since we have the mem0 component in the session, the agent should be able to
+        # retrieve the company report without asking for clarification, as it will
+        # be able to remember the user preferences from Mem0 component.
+        query = "Please retrieve my company report"
+        print(f"User: {query}")
+        result = await agent.run(query, session=session)
+        print(f"Agent: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,167 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import uuid
+
+from agent_framework import tool
+from agent_framework.azure import AzureAIAgentClient
+from agent_framework.mem0 import Mem0ContextProvider
+from azure.identity.aio import AzureCliCredential
+
+
+# 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_user_preferences(user_id: str) -> str:
+    """Mock function to get user preferences."""
+    preferences = {
+        "user123": "Prefers concise responses and technical details",
+        "user456": "Likes detailed explanations with examples",
+    }
+    return preferences.get(user_id, "No specific preferences found")
+
+
+async def example_global_thread_scope() -> None:
+    """Example 1: Global thread_id scope (memories shared across all operations)."""
+    print("1. Global Thread Scope Example:")
+    print("-" * 40)
+
+    global_thread_id = str(uuid.uuid4())
+    user_id = "user123"
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(credential=credential).as_agent(
+            name="GlobalMemoryAssistant",
+            instructions="You are an assistant that remembers user preferences across conversations.",
+            tools=get_user_preferences,
+            context_providers=[Mem0ContextProvider(
+                user_id=user_id,
+                thread_id=global_thread_id,
+                scope_to_per_operation_thread_id=False,  # Share memories across all sessions
+            )],
+        ) as global_agent,
+    ):
+        # Store some preferences in the global scope
+        query = "Remember that I prefer technical responses with code examples when discussing programming."
+        print(f"User: {query}")
+        result = await global_agent.run(query)
+        print(f"Agent: {result}\n")
+
+        # Create a new session - but memories should still be accessible due to global scope
+        new_session = global_agent.create_session()
+        query = "What do you know about my preferences?"
+        print(f"User (new session): {query}")
+        result = await global_agent.run(query, session=new_session)
+        print(f"Agent: {result}\n")
+
+
+async def example_per_operation_thread_scope() -> None:
+    """Example 2: Per-operation thread scope (memories isolated per session).
+
+    Note: When scope_to_per_operation_thread_id=True, the provider is bound to a single session
+    throughout its lifetime. Use the same session object for all operations with that provider.
+    """
+    print("2. Per-Operation Thread Scope Example:")
+    print("-" * 40)
+
+    user_id = "user123"
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(credential=credential).as_agent(
+            name="ScopedMemoryAssistant",
+            instructions="You are an assistant with thread-scoped memory.",
+            tools=get_user_preferences,
+            context_providers=[Mem0ContextProvider(
+                user_id=user_id,
+                scope_to_per_operation_thread_id=True,  # Isolate memories per session
+            )],
+        ) as scoped_agent,
+    ):
+        # Create a specific session for this scoped provider
+        dedicated_session = scoped_agent.create_session()
+
+        # Store some information in the dedicated session
+        query = "Remember that for this conversation, I'm working on a Python project about data analysis."
+        print(f"User (dedicated session): {query}")
+        result = await scoped_agent.run(query, session=dedicated_session)
+        print(f"Agent: {result}\n")
+
+        # Test memory retrieval in the same dedicated session
+        query = "What project am I working on?"
+        print(f"User (same dedicated session): {query}")
+        result = await scoped_agent.run(query, session=dedicated_session)
+        print(f"Agent: {result}\n")
+
+        # Store more information in the same session
+        query = "Also remember that I prefer using pandas and matplotlib for this project."
+        print(f"User (same dedicated session): {query}")
+        result = await scoped_agent.run(query, session=dedicated_session)
+        print(f"Agent: {result}\n")
+
+        # Test comprehensive memory retrieval
+        query = "What do you know about my current project and preferences?"
+        print(f"User (same dedicated session): {query}")
+        result = await scoped_agent.run(query, session=dedicated_session)
+        print(f"Agent: {result}\n")
+
+
+async def example_multiple_agents() -> None:
+    """Example 3: Multiple agents with different thread configurations."""
+    print("3. Multiple Agents with Different Thread Configurations:")
+    print("-" * 40)
+
+    agent_id_1 = "agent_personal"
+    agent_id_2 = "agent_work"
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(credential=credential).as_agent(
+            name="PersonalAssistant",
+            instructions="You are a personal assistant that helps with personal tasks.",
+            context_providers=[Mem0ContextProvider(
+                agent_id=agent_id_1,
+            )],
+        ) as personal_agent,
+        AzureAIAgentClient(credential=credential).as_agent(
+            name="WorkAssistant",
+            instructions="You are a work assistant that helps with professional tasks.",
+            context_providers=[Mem0ContextProvider(
+                agent_id=agent_id_2,
+            )],
+        ) as work_agent,
+    ):
+        # Store personal information
+        query = "Remember that I like to exercise at 6 AM and prefer outdoor activities."
+        print(f"User to Personal Agent: {query}")
+        result = await personal_agent.run(query)
+        print(f"Personal Agent: {result}\n")
+
+        # Store work information
+        query = "Remember that I have team meetings every Tuesday at 2 PM."
+        print(f"User to Work Agent: {query}")
+        result = await work_agent.run(query)
+        print(f"Work Agent: {result}\n")
+
+        # Test memory isolation
+        query = "What do you know about my schedule?"
+        print(f"User to Personal Agent: {query}")
+        result = await personal_agent.run(query)
+        print(f"Personal Agent: {result}\n")
+
+        print(f"User to Work Agent: {query}")
+        result = await work_agent.run(query)
+        print(f"Work Agent: {result}\n")
+
+
+async def main() -> None:
+    """Run all Mem0 thread management examples."""
+    print("=== Mem0 Thread Management Example ===\n")
+
+    await example_global_thread_scope()
+    await example_per_operation_thread_scope()
+    await example_multiple_agents()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())