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 21:00:32 +00:00
parent 0c67dbbce5
commit 1e350ea22f
312 changed files with 6669 additions and 11423 deletions
@@ -8,10 +8,10 @@ This folder contains an example demonstrating how to use the Redis context provi

 | File | Description |
 |------|-------------|
-| [`azure_redis_conversation.py`](azure_redis_conversation.py) | Demonstrates conversation persistence with RedisChatMessageStore and Azure Redis with Azure AD (Entra ID) authentication using credential provider. |
+| [`azure_redis_conversation.py`](azure_redis_conversation.py) | Demonstrates conversation persistence with RedisHistoryProvider and Azure Redis with Azure AD (Entra ID) authentication using credential provider. |
 | [`redis_basics.py`](redis_basics.py) | Shows standalone provider usage and agent integration. Demonstrates writing messages to Redis, retrieving context via full‑text or hybrid vector search, and persisting preferences across threads. Also includes a simple tool example whose outputs are remembered. |
-| [`redis_conversation.py`](redis_conversation.py) | Simple example showing conversation persistence with RedisChatMessageStore using traditional connection string authentication. |
-| [`redis_threads.py`](redis_threads.py) | Demonstrates thread scoping. Includes: (1) global thread scope with a fixed `thread_id` shared across operations; (2) per‑operation thread scope where `scope_to_per_operation_thread_id=True` binds memory to a single thread for the provider's lifetime; and (3) multiple agents with isolated memory via different `agent_id` values. |
+| [`redis_conversation.py`](redis_conversation.py) | Simple example showing conversation persistence with RedisContextProvider using traditional connection string authentication. |
+| [`redis_sessions.py`](redis_sessions.py) | Demonstrates thread scoping. Includes: (1) global thread scope with a fixed `thread_id` shared across operations; (2) per‑operation thread scope where `scope_to_per_operation_thread_id=True` binds memory to a single thread for the provider's lifetime; and (3) multiple agents with isolated memory via different `agent_id` values. |


 ## Prerequisites
@@ -1,9 +1,9 @@
 # Copyright (c) Microsoft. All rights reserved.

-"""Azure Managed Redis Chat Message Store with Azure AD Authentication
+"""Azure Managed Redis History Provider with Azure AD Authentication

 This example demonstrates how to use Azure Managed Redis with Azure AD authentication
-to persist conversational details using RedisChatMessageStore.
+to persist conversational details using RedisHistoryProvider.

 Requirements:
  - Azure Managed Redis instance with Azure AD authentication enabled
@@ -22,7 +22,7 @@ import asyncio
 import os

 from agent_framework.openai import OpenAIChatClient
-from agent_framework.redis import RedisChatMessageStore
+from agent_framework.redis import RedisHistoryProvider
 from azure.identity.aio import AzureCliCredential
 from redis.credentials import CredentialProvider

@@ -60,28 +60,27 @@ async def main() -> None:
    azure_credential = AzureCliCredential()
    credential_provider = AzureCredentialProvider(azure_credential, user_object_id)

-    thread_id = "azure_test_thread"
+    session_id = "azure_test_session"

-    # Factory for creating Azure Redis chat message store
-    def chat_message_store_factory():
-        return RedisChatMessageStore(
-            credential_provider=credential_provider,
-            host=redis_host,
-            port=10000,
-            ssl=True,
-            thread_id=thread_id,
-            key_prefix="chat_messages",
-            max_messages=100,
-        )
+    # Create Azure Redis history provider
+    history_provider = RedisHistoryProvider(
+        credential_provider=credential_provider,
+        host=redis_host,
+        port=10000,
+        ssl=True,
+        thread_id=session_id,
+        key_prefix="chat_messages",
+        max_messages=100,
+    )

    # Create chat client
    client = OpenAIChatClient()

-    # Create agent with Azure Redis store
+    # Create agent with Azure Redis history provider
    agent = client.as_agent(
        name="AzureRedisAssistant",
        instructions="You are a helpful assistant.",
-        chat_message_store_factory=chat_message_store_factory,
+        context_providers=[history_provider],
    )

    # Conversation
@@ -32,12 +32,12 @@ import os

 from agent_framework import Message, tool
 from agent_framework.openai import OpenAIChatClient
-from agent_framework_redis._provider import RedisProvider
+from agent_framework.redis import RedisContextProvider
 from redisvl.extensions.cache.embeddings import EmbeddingsCache
 from redisvl.utils.vectorize import OpenAITextVectorizer


-# 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 search_flights(origin_airport_code: str, destination_airport_code: str, detailed: bool = False) -> str:
    """Simulated flight-search tool to demonstrate tool memory.
@@ -104,7 +104,7 @@ async def main() -> None:
    # Recommend default for OPENAI_CHAT_MODEL_ID is gpt-4o-mini

    # We attach an embedding vectorizer so the provider can perform hybrid (text + vector)
-    # retrieval. If you prefer text-only retrieval, instantiate RedisProvider without the
+    # retrieval. If you prefer text-only retrieval, instantiate RedisContextProvider without the
    # 'vectorizer' and vector_* parameters.
    vectorizer = OpenAITextVectorizer(
        model="text-embedding-ada-002",
@@ -114,7 +114,7 @@ async def main() -> None:
    # The provider manages persistence and retrieval. application_id/agent_id/user_id
    # scope data for multi-tenant separation; thread_id (set later) narrows to a
    # specific conversation.
-    provider = RedisProvider(
+    provider = RedisContextProvider(
        redis_url="redis://localhost:6379",
        index_name="redis_basics",
        application_id="matrix_of_kermits",
@@ -133,21 +133,27 @@ async def main() -> None:
        Message("system", ["runA CONVO: System Message"]),
    ]

-    # Declare/start a conversation/thread and write messages under 'runA'.
-    # Threads are logical boundaries used by the provider to group and retrieve
-    # conversation-specific context.
-    await provider.thread_created(thread_id="runA")
-    await provider.invoked(request_messages=messages)
+    # Use the provider's before_run/after_run API to store and retrieve messages.
+    # In practice, the agent handles this automatically; this shows the low-level API.
+    from agent_framework import AgentSession, SessionContext

-    # Retrieve relevant memories for a hypothetical model call. The provider uses
-    # the current request messages as the retrieval query and returns context to
-    # be injected into the model's instructions.
-    ctx = await provider.invoking([Message("system", ["B: Assistant Message"])])
+    session = AgentSession(session_id="runA")
+    context = SessionContext()
+    context.extend_messages("input", messages)
+    state = session.state
+
+    # Store messages via after_run
+    await provider.after_run(agent=None, session=session, context=context, state=state)
+
+    # Retrieve relevant memories via before_run
+    query_context = SessionContext()
+    query_context.extend_messages("input", [Message("system", ["B: Assistant Message"])])
+    await provider.before_run(agent=None, session=session, context=query_context, state=state)

    # Inspect retrieved memories that would be injected into instructions
    # (Debug-only output so you can verify retrieval works as expected.)
-    print("Model Invoking Result:")
-    print(ctx)
+    print("Before Run Result:")
+    print(query_context)

    # Drop / delete the provider index in Redis
    await provider.redis_index.delete()
@@ -163,7 +169,7 @@ async def main() -> None:
        cache=EmbeddingsCache(name="openai_embeddings_cache", redis_url="redis://localhost:6379"),
    )
    # Recreate a clean index so the next scenario starts fresh
-    provider = RedisProvider(
+    provider = RedisContextProvider(
        redis_url="redis://localhost:6379",
        index_name="redis_basics_2",
        prefix="context_2",
@@ -187,7 +193,7 @@ async def main() -> None:
            "Before answering, always check for stored context"
        ),
        tools=[],
-        context_provider=provider,
+        context_providers=[provider],
    )

    # Teach a user preference; the agent writes this to the provider's memory
@@ -210,7 +216,7 @@ async def main() -> None:
    print("\n3. Agent + provider + tool: store and recall tool-derived context")
    print("-" * 40)
    # Text-only provider (full-text search only). Omits vectorizer and related params.
-    provider = RedisProvider(
+    provider = RedisContextProvider(
        redis_url="redis://localhost:6379",
        index_name="redis_basics_3",
        prefix="context_3",
@@ -229,7 +235,7 @@ async def main() -> None:
            "Before answering, always check for stored context"
        ),
        tools=search_flights,
-        context_provider=provider,
+        context_providers=[provider],
    )
    # Invoke the tool; outputs become part of memory/context
    query = "Are there any flights from new york city (jfk) to la? Give me details"
@@ -2,7 +2,7 @@

 """Redis Context Provider: Basic usage and agent integration

-This example demonstrates how to use the Redis ChatMessageStoreProtocol to persist
+This example demonstrates how to use the Redis context provider to persist
 conversational details. Pass it as a constructor argument to create_agent.

 Requirements:
@@ -18,8 +18,7 @@ import asyncio
 import os

 from agent_framework.openai import OpenAIChatClient
-from agent_framework_redis._chat_message_store import RedisChatMessageStore
-from agent_framework_redis._provider import RedisProvider
+from agent_framework.redis import RedisContextProvider
 from redisvl.extensions.cache.embeddings import EmbeddingsCache
 from redisvl.utils.vectorize import OpenAITextVectorizer

@@ -37,9 +36,9 @@ async def main() -> None:
        cache=EmbeddingsCache(name="openai_embeddings_cache", redis_url="redis://localhost:6379"),
    )

-    thread_id = "test_thread"
+    session_id = "test_session"

-    provider = RedisProvider(
+    provider = RedisContextProvider(
        redis_url="redis://localhost:6379",
        index_name="redis_conversation",
        prefix="redis_conversation",
@@ -50,17 +49,9 @@ async def main() -> None:
        vector_field_name="vector",
        vector_algorithm="hnsw",
        vector_distance_metric="cosine",
-        thread_id=thread_id,
+        thread_id=session_id,
    )

-    def chat_message_store_factory():
-        return RedisChatMessageStore(
-            redis_url="redis://localhost:6379",
-            thread_id=thread_id,
-            key_prefix="chat_messages",
-            max_messages=100,
-        )
-
    # Create chat client for the agent
    client = OpenAIChatClient(model_id=os.getenv("OPENAI_CHAT_MODEL_ID"), api_key=os.getenv("OPENAI_API_KEY"))
    # Create agent wired to the Redis context provider. The provider automatically
@@ -72,8 +63,7 @@ async def main() -> None:
            "Before answering, always check for stored context"
        ),
        tools=[],
-        context_provider=provider,
-        chat_message_store_factory=chat_message_store_factory,
+        context_providers=[provider],
    )

    # Teach a user preference; the agent writes this to the provider's memory
@@ -31,7 +31,7 @@ import os
 import uuid

 from agent_framework.openai import OpenAIChatClient
-from agent_framework_redis._provider import RedisProvider
+from agent_framework.redis import RedisContextProvider
 from redisvl.extensions.cache.embeddings import EmbeddingsCache
 from redisvl.utils.vectorize import OpenAITextVectorizer

@@ -51,16 +51,14 @@ async def example_global_thread_scope() -> None:
        api_key=os.getenv("OPENAI_API_KEY"),
    )

-    provider = RedisProvider(
+    provider = RedisContextProvider(
        redis_url="redis://localhost:6379",
        index_name="redis_threads_global",
-        # overwrite_redis_index=True,
-        # drop_redis_index=True,
        application_id="threads_demo_app",
        agent_id="threads_demo_agent",
        user_id="threads_demo_user",
        thread_id=global_thread_id,
-        scope_to_per_operation_thread_id=False,  # Share memories across all threads
+        scope_to_per_operation_thread_id=False,  # Share memories across all sessions
    )

    agent = client.as_agent(
@@ -70,7 +68,7 @@ async def example_global_thread_scope() -> None:
            "Before answering, always check for stored context containing information"
        ),
        tools=[],
-        context_provider=provider,
+        context_providers=[provider],
    )

    # Store a preference in the global scope
@@ -79,11 +77,11 @@ async def example_global_thread_scope() -> None:
    result = await agent.run(query)
    print(f"Agent: {result}\n")

-    # Create a new thread - memories should still be accessible due to global scope
-    new_thread = agent.get_new_thread()
+    # Create a new session - memories should still be accessible due to global scope
+    new_session = agent.create_session()
    query = "What technical responses do I prefer?"
-    print(f"User (new thread): {query}")
-    result = await agent.run(query, thread=new_thread)
+    print(f"User (new session): {query}")
+    result = await agent.run(query, session=new_session)
    print(f"Agent: {result}\n")

    # Clean up the Redis index
@@ -91,10 +89,10 @@ async def example_global_thread_scope() -> None:


 async def example_per_operation_thread_scope() -> None:
-    """Example 2: Per-operation thread scope (memories isolated per thread).
+    """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 thread
-    throughout its lifetime. Use the same thread object for all operations with that provider.
+    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)
@@ -110,7 +108,7 @@ async def example_per_operation_thread_scope() -> None:
        cache=EmbeddingsCache(name="openai_embeddings_cache", redis_url="redis://localhost:6379"),
    )

-    provider = RedisProvider(
+    provider = RedisContextProvider(
        redis_url="redis://localhost:6379",
        index_name="redis_threads_dynamic",
        # overwrite_redis_index=True,
@@ -118,7 +116,7 @@ async def example_per_operation_thread_scope() -> None:
        application_id="threads_demo_app",
        agent_id="threads_demo_agent",
        user_id="threads_demo_user",
-        scope_to_per_operation_thread_id=True,  # Isolate memories per thread
+        scope_to_per_operation_thread_id=True,  # Isolate memories per session
        redis_vectorizer=vectorizer,
        vector_field_name="vector",
        vector_algorithm="hnsw",
@@ -128,34 +126,34 @@ async def example_per_operation_thread_scope() -> None:
    agent = client.as_agent(
        name="ScopedMemoryAssistant",
        instructions="You are an assistant with thread-scoped memory.",
-        context_provider=provider,
+        context_providers=[provider],
    )

-    # Create a specific thread for this scoped provider
-    dedicated_thread = agent.get_new_thread()
+    # Create a specific session for this scoped provider
+    dedicated_session = agent.create_session()

-    # Store some information in the dedicated thread
+    # 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 thread): {query}")
-    result = await agent.run(query, thread=dedicated_thread)
+    print(f"User (dedicated session): {query}")
+    result = await agent.run(query, session=dedicated_session)
    print(f"Agent: {result}\n")

-    # Test memory retrieval in the same dedicated thread
+    # Test memory retrieval in the same dedicated session
    query = "What project am I working on?"
-    print(f"User (same dedicated thread): {query}")
-    result = await agent.run(query, thread=dedicated_thread)
+    print(f"User (same dedicated session): {query}")
+    result = await agent.run(query, session=dedicated_session)
    print(f"Agent: {result}\n")

-    # Store more information in the same thread
+    # 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 thread): {query}")
-    result = await agent.run(query, thread=dedicated_thread)
+    print(f"User (same dedicated session): {query}")
+    result = await 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 thread): {query}")
-    result = await agent.run(query, thread=dedicated_thread)
+    print(f"User (same dedicated session): {query}")
+    result = await agent.run(query, session=dedicated_session)
    print(f"Agent: {result}\n")

    # Clean up the Redis index
@@ -178,7 +176,7 @@ async def example_multiple_agents() -> None:
        cache=EmbeddingsCache(name="openai_embeddings_cache", redis_url="redis://localhost:6379"),
    )

-    personal_provider = RedisProvider(
+    personal_provider = RedisContextProvider(
        redis_url="redis://localhost:6379",
        index_name="redis_threads_agents",
        application_id="threads_demo_app",
@@ -193,10 +191,10 @@ async def example_multiple_agents() -> None:
    personal_agent = client.as_agent(
        name="PersonalAssistant",
        instructions="You are a personal assistant that helps with personal tasks.",
-        context_provider=personal_provider,
+        context_providers=[personal_provider],
    )

-    work_provider = RedisProvider(
+    work_provider = RedisContextProvider(
        redis_url="redis://localhost:6379",
        index_name="redis_threads_agents",
        application_id="threads_demo_app",
@@ -211,7 +209,7 @@ async def example_multiple_agents() -> None:
    work_agent = client.as_agent(
        name="WorkAssistant",
        instructions="You are a work assistant that helps with professional tasks.",
-        context_provider=work_provider,
+        context_providers=[work_provider],
    )

    # Store personal information