test

python/samples/getting_started/context_providers/redis/README.md

@@ -0,0 +1,113 @@
+# Redis Context Provider Examples
+
+The Redis context provider enables persistent, searchable memory for your agents using Redis (RediSearch). It supports full‑text search and optional hybrid search with vector embeddings, letting agents remember and retrieve user context across sessions and threads.
+
+This folder contains an example demonstrating how to use the Redis context provider with the Agent Framework.
+
+## Examples
+
+| 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. |
+| [`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. |
+
+
+## Prerequisites
+
+### Required resources
+
+1. A running Redis with RediSearch (Redis Stack or a managed service)
+2. Python environment with Agent Framework Redis extra installed
+3. Optional: OpenAI API key if using vector embeddings
+
+### Install the package
+
+```bash
+pip install "agent-framework-redis"
+```
+
+## Running Redis
+
+Pick one option:
+
+### Option A: Docker (local Redis Stack)
+
+```bash
+docker run --name redis -p 6379:6379 -d redis:8.0.3
+```
+
+### Option B: Redis Cloud
+
+Create a free database and get the connection URL at `https://redis.io/cloud/`.
+
+### Option C: Azure Managed Redis
+
+See quickstart: `https://learn.microsoft.com/azure/redis/quickstart-create-managed-redis`
+
+## Configuration
+
+### Environment variables
+
+- `OPENAI_API_KEY` (optional): Required only if you set `vectorizer_choice="openai"` to enable hybrid search.
+
+### Provider configuration highlights
+
+The provider supports both full‑text only and hybrid vector search:
+
+- Set `vectorizer_choice` to `"openai"` or `"hf"` to enable embeddings and hybrid search.
+- When using a vectorizer, also set `vector_field_name` (e.g., `"vector"`).
+- Partition fields for scoping memory: `application_id`, `agent_id`, `user_id`, `thread_id`.
+- Thread scoping: `scope_to_per_operation_thread_id=True` isolates memory per operation thread.
+- Index management: `index_name`, `overwrite_redis_index`, `drop_redis_index`.
+
+## What the example does
+
+`redis_basics.py` walks through three scenarios:
+
+1. Standalone provider usage: adds messages and retrieves context via `invoking`.
+2. Agent integration: teaches the agent a preference and verifies it is remembered across turns.
+3. Agent + tool: calls a sample tool (flight search) and then asks the agent to recall details remembered from the tool output.
+
+It uses OpenAI for both chat (via `OpenAIChatClient`) and, in some steps, optional embeddings for hybrid search.
+
+## How to run
+
+1) Start Redis (see options above). For local default, ensure it's reachable at `redis://localhost:6379`.
+
+2) Set your OpenAI key if using embeddings and for the chat client used in the sample:
+
+```bash
+export OPENAI_API_KEY="<your key>"
+```
+
+3) Run the example:
+
+```bash
+python redis_basics.py
+```
+
+You should see the agent responses and, when using embeddings, context retrieved from Redis. The example includes commented debug helpers you can print, such as index info or all stored docs.
+
+## Key concepts
+
+### Memory scoping
+
+- Global scope: set `application_id`, `agent_id`, `user_id`, or `thread_id` on the provider to filter memory.
+- Per‑operation thread scope: set `scope_to_per_operation_thread_id=True` to isolate memory to the current thread created by the framework.
+
+### Hybrid vector search (optional)
+
+- Enable by setting `vectorizer_choice` to `"openai"` (requires `OPENAI_API_KEY`) or `"hf"` (offline model).
+- Provide `vector_field_name` (e.g., `"vector"`); other vector settings have sensible defaults.
+
+### Index lifecycle controls
+
+- `overwrite_redis_index` and `drop_redis_index` help recreate indexes during iteration.
+
+## Troubleshooting
+
+- Ensure at least one of `application_id`, `agent_id`, `user_id`, or `thread_id` is set; the provider requires a scope.
+- If using embeddings, verify `OPENAI_API_KEY` is set and reachable.
+- Make sure Redis exposes RediSearch (Redis Stack image or managed service with search enabled).

python/samples/getting_started/context_providers/redis/azure_redis_conversation.py

@@ -0,0 +1,123 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Azure Managed Redis Chat Message Store with Azure AD Authentication
+
+This example demonstrates how to use Azure Managed Redis with Azure AD authentication
+to persist conversational details using RedisChatMessageStore.
+
+Requirements:
+  - Azure Managed Redis instance with Azure AD authentication enabled
+  - Azure credentials configured (az login or managed identity)
+  - agent-framework-redis: pip install agent-framework-redis
+  - azure-identity: pip install azure-identity
+
+Environment Variables:
+  - AZURE_REDIS_HOST: Your Azure Managed Redis host (e.g., myredis.redis.cache.windows.net)
+  - OPENAI_API_KEY: Your OpenAI API key
+  - OPENAI_CHAT_MODEL_ID: OpenAI model (e.g., gpt-4o-mini)
+  - AZURE_USER_OBJECT_ID: Your Azure AD User Object ID for authentication
+"""
+
+import asyncio
+import os
+
+from agent_framework.openai import OpenAIChatClient
+from agent_framework.redis import RedisChatMessageStore
+from azure.identity.aio import AzureCliCredential
+from redis.credentials import CredentialProvider
+
+
+class AzureCredentialProvider(CredentialProvider):
+    """Credential provider for Azure AD authentication with Redis Enterprise."""
+
+    def __init__(self, azure_credential: AzureCliCredential, user_object_id: str):
+        self.azure_credential = azure_credential
+        self.user_object_id = user_object_id
+
+    async def get_credentials_async(self) -> tuple[str] | tuple[str, str]:
+        """Get Azure AD token for Redis authentication.
+
+        Returns (username, token) where username is the Azure user's Object ID.
+        """
+        token = await self.azure_credential.get_token("https://redis.azure.com/.default")
+        return (self.user_object_id, token.token)
+
+
+async def main() -> None:
+    redis_host = os.environ.get("AZURE_REDIS_HOST")
+    if not redis_host:
+        print("ERROR: Set AZURE_REDIS_HOST environment variable")
+        return
+
+    # For Azure Redis with Entra ID, username must be your Object ID
+    user_object_id = os.environ.get("AZURE_USER_OBJECT_ID")
+    if not user_object_id:
+        print("ERROR: Set AZURE_USER_OBJECT_ID environment variable")
+        print("Get your Object ID from the Azure Portal")
+        return
+
+    # Create Azure CLI credential provider (uses 'az login' credentials)
+    azure_credential = AzureCliCredential()
+    credential_provider = AzureCredentialProvider(azure_credential, user_object_id)
+
+    thread_id = "azure_test_thread"
+
+    # Factory for creating Azure Redis chat message store
+    chat_message_store_factory = lambda: RedisChatMessageStore(
+        credential_provider=credential_provider,
+        host=redis_host,
+        port=10000,
+        ssl=True,
+        thread_id=thread_id,
+        key_prefix="chat_messages",
+        max_messages=100,
+    )
+
+    # Create chat client
+    client = OpenAIChatClient()
+
+    # Create agent with Azure Redis store
+    agent = client.as_agent(
+        name="AzureRedisAssistant",
+        instructions="You are a helpful assistant.",
+        chat_message_store_factory=chat_message_store_factory,
+    )
+
+    # Conversation
+    query = "Remember that I enjoy gumbo"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    # Ask the agent to recall the stored preference; it should retrieve from memory
+    query = "What do I enjoy?"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    query = "What did I say to you just now?"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    query = "Remember that I have a meeting at 3pm tomorrow"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    query = "Tulips are red"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    query = "What was the first thing I said to you this conversation?"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    # Cleanup
+    await azure_credential.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/context_providers/redis/redis_basics.py

@@ -0,0 +1,248 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Redis Context Provider: Basic usage and agent integration
+
+This example demonstrates how to use the Redis context provider to persist and
+retrieve conversational memory for agents. It covers three progressively more
+realistic scenarios:
+
+1) Standalone provider usage ("basic cache")
+   - Write messages to Redis and retrieve relevant context using full-text or
+     hybrid vector search.
+
+2) Agent + provider
+   - Connect the provider to an agent so the agent can store user preferences
+     and recall them across turns.
+
+3) Agent + provider + tool memory
+   - Expose a simple tool to the agent, then verify that details from the tool
+     outputs are captured and retrievable as part of the agent's memory.
+
+Requirements:
+  - A Redis instance with RediSearch enabled (e.g., Redis Stack)
+  - agent-framework with the Redis extra installed: pip install "agent-framework-redis"
+  - Optionally an OpenAI API key if enabling embeddings for hybrid search
+
+Run:
+  python redis_basics.py
+"""
+
+import asyncio
+import os
+
+from agent_framework import ChatMessage, Role
+from agent_framework.openai import OpenAIChatClient
+from agent_framework_redis._provider import RedisProvider
+from redisvl.extensions.cache.embeddings import EmbeddingsCache
+from redisvl.utils.vectorize import OpenAITextVectorizer
+
+
+def search_flights(origin_airport_code: str, destination_airport_code: str, detailed: bool = False) -> str:
+    """Simulated flight-search tool to demonstrate tool memory.
+
+    The agent can call this function, and the returned details can be stored
+    by the Redis context provider. We later ask the agent to recall facts from
+    these tool results to verify memory is working as expected.
+    """
+    # Minimal static catalog used to simulate a tool's structured output
+    flights = {
+        ("JFK", "LAX"): {
+            "airline": "SkyJet",
+            "duration": "6h 15m",
+            "price": 325,
+            "cabin": "Economy",
+            "baggage": "1 checked bag",
+        },
+        ("SFO", "SEA"): {
+            "airline": "Pacific Air",
+            "duration": "2h 5m",
+            "price": 129,
+            "cabin": "Economy",
+            "baggage": "Carry-on only",
+        },
+        ("LHR", "DXB"): {
+            "airline": "EuroWings",
+            "duration": "6h 50m",
+            "price": 499,
+            "cabin": "Business",
+            "baggage": "2 bags included",
+        },
+    }
+
+    route = (origin_airport_code.upper(), destination_airport_code.upper())
+    if route not in flights:
+        return f"No flights found between {origin_airport_code} and {destination_airport_code}"
+
+    flight = flights[route]
+    if not detailed:
+        return f"Flights available from {origin_airport_code} to {destination_airport_code}."
+
+    return (
+        f"{flight['airline']} operates flights from {origin_airport_code} to {destination_airport_code}. "
+        f"Duration: {flight['duration']}. "
+        f"Price: ${flight['price']}. "
+        f"Cabin: {flight['cabin']}. "
+        f"Baggage policy: {flight['baggage']}."
+    )
+
+
+async def main() -> None:
+    """Walk through provider-only, agent integration, and tool-memory scenarios.
+
+    Helpful debugging (uncomment when iterating):
+      - print(await provider.redis_index.info())
+      - print(await provider.search_all())
+    """
+
+    print("1. Standalone provider usage:")
+    print("-" * 40)
+    # Create a provider with partition scope and OpenAI embeddings
+
+    # Please set the OPENAI_API_KEY and OPENAI_CHAT_MODEL_ID environment variables to use the OpenAI vectorizer
+    # 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
+    # 'vectorizer' and vector_* parameters.
+    vectorizer = OpenAITextVectorizer(
+        model="text-embedding-ada-002",
+        api_config={"api_key": os.getenv("OPENAI_API_KEY")},
+        cache=EmbeddingsCache(name="openai_embeddings_cache", redis_url="redis://localhost:6379"),
+    )
+    # 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(
+        redis_url="redis://localhost:6379",
+        index_name="redis_basics",
+        application_id="matrix_of_kermits",
+        agent_id="agent_kermit",
+        user_id="kermit",
+        redis_vectorizer=vectorizer,
+        vector_field_name="vector",
+        vector_algorithm="hnsw",
+        vector_distance_metric="cosine",
+    )
+
+    # Build sample chat messages to persist to Redis
+    messages = [
+        ChatMessage(role=Role.USER, text="runA CONVO: User Message"),
+        ChatMessage(role=Role.ASSISTANT, text="runA CONVO: Assistant Message"),
+        ChatMessage(role=Role.SYSTEM, text="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)
+
+    # 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([ChatMessage(role=Role.SYSTEM, text="B: Assistant Message")])
+
+    # 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)
+
+    # Drop / delete the provider index in Redis
+    await provider.redis_index.delete()
+
+    # --- Agent + provider: teach and recall a preference ---
+
+    print("\n2. Agent + provider: teach and recall a preference")
+    print("-" * 40)
+    # Fresh provider for the agent demo (recreates index)
+    vectorizer = OpenAITextVectorizer(
+        model="text-embedding-ada-002",
+        api_config={"api_key": os.getenv("OPENAI_API_KEY")},
+        cache=EmbeddingsCache(name="openai_embeddings_cache", redis_url="redis://localhost:6379"),
+    )
+    # Recreate a clean index so the next scenario starts fresh
+    provider = RedisProvider(
+        redis_url="redis://localhost:6379",
+        index_name="redis_basics_2",
+        prefix="context_2",
+        application_id="matrix_of_kermits",
+        agent_id="agent_kermit",
+        user_id="kermit",
+        redis_vectorizer=vectorizer,
+        vector_field_name="vector",
+        vector_algorithm="hnsw",
+        vector_distance_metric="cosine",
+    )
+
+    # 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
+    # persists conversational details and surfaces relevant context on each turn.
+    agent = client.as_agent(
+        name="MemoryEnhancedAssistant",
+        instructions=(
+            "You are a helpful assistant. Personalize replies using provided context. "
+            "Before answering, always check for stored context"
+        ),
+        tools=[],
+        context_provider=provider,
+    )
+
+    # Teach a user preference; the agent writes this to the provider's memory
+    query = "Remember that I enjoy glugenflorgle"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    # Ask the agent to recall the stored preference; it should retrieve from memory
+    query = "What do I enjoy?"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    # Drop / delete the provider index in Redis
+    await provider.redis_index.delete()
+
+    # --- Agent + provider + tool: store and recall tool-derived context ---
+
+    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(
+        redis_url="redis://localhost:6379",
+        index_name="redis_basics_3",
+        prefix="context_3",
+        application_id="matrix_of_kermits",
+        agent_id="agent_kermit",
+        user_id="kermit",
+    )
+
+    # Create agent exposing the flight search tool. Tool outputs are captured by the
+    # provider and become retrievable context for later turns.
+    client = OpenAIChatClient(model_id=os.getenv("OPENAI_CHAT_MODEL_ID"), api_key=os.getenv("OPENAI_API_KEY"))
+    agent = client.as_agent(
+        name="MemoryEnhancedAssistant",
+        instructions=(
+            "You are a helpful assistant. Personalize replies using provided context. "
+            "Before answering, always check for stored context"
+        ),
+        tools=search_flights,
+        context_provider=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"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+    # Verify the agent can recall tool-derived context
+    query = "Which flight did I ask about?"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    # Drop / delete the provider index in Redis
+    await provider.redis_index.delete()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/context_providers/redis/redis_conversation.py

@@ -0,0 +1,113 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Redis Context Provider: Basic usage and agent integration
+
+This example demonstrates how to use the Redis ChatMessageStoreProtocol to persist
+conversational details. Pass it as a constructor argument to create_agent.
+
+Requirements:
+  - A Redis instance with RediSearch enabled (e.g., Redis Stack)
+  - agent-framework with the Redis extra installed: pip install "agent-framework-redis"
+  - Optionally an OpenAI API key if enabling embeddings for hybrid search
+
+Run:
+  python redis_conversation.py
+"""
+
+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 redisvl.extensions.cache.embeddings import EmbeddingsCache
+from redisvl.utils.vectorize import OpenAITextVectorizer
+
+
+async def main() -> None:
+    """Walk through provider and chat message store usage.
+
+    Helpful debugging (uncomment when iterating):
+      - print(await provider.redis_index.info())
+      - print(await provider.search_all())
+    """
+    vectorizer = OpenAITextVectorizer(
+        model="text-embedding-ada-002",
+        api_config={"api_key": os.getenv("OPENAI_API_KEY")},
+        cache=EmbeddingsCache(name="openai_embeddings_cache", redis_url="redis://localhost:6379"),
+    )
+
+    thread_id = "test_thread"
+
+    provider = RedisProvider(
+        redis_url="redis://localhost:6379",
+        index_name="redis_conversation",
+        prefix="redis_conversation",
+        application_id="matrix_of_kermits",
+        agent_id="agent_kermit",
+        user_id="kermit",
+        redis_vectorizer=vectorizer,
+        vector_field_name="vector",
+        vector_algorithm="hnsw",
+        vector_distance_metric="cosine",
+        thread_id=thread_id,
+    )
+    chat_message_store_factory = lambda: 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
+    # persists conversational details and surfaces relevant context on each turn.
+    agent = client.as_agent(
+        name="MemoryEnhancedAssistant",
+        instructions=(
+            "You are a helpful assistant. Personalize replies using provided context. "
+            "Before answering, always check for stored context"
+        ),
+        tools=[],
+        context_provider=provider,
+        chat_message_store_factory=chat_message_store_factory,
+    )
+
+    # Teach a user preference; the agent writes this to the provider's memory
+    query = "Remember that I enjoy gumbo"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    # Ask the agent to recall the stored preference; it should retrieve from memory
+    query = "What do I enjoy?"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    query = "What did I say to you just now?"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    query = "Remember that I have a meeting at 3pm tomorro"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    query = "Tulips are red"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+
+    query = "What was the first thing I said to you this conversation?"
+    result = await agent.run(query)
+    print("User: ", query)
+    print("Agent: ", result)
+    # Drop / delete the provider index in Redis
+    await provider.redis_index.delete()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/context_providers/redis/redis_threads.py

@@ -0,0 +1,251 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Redis Context Provider: Thread scoping examples
+
+This sample demonstrates how conversational memory can be scoped when using the
+Redis context provider. It covers three scenarios:
+
+1) Global thread scope
+   - Provide a fixed thread_id to share memories across operations/threads.
+
+2) Per-operation thread scope
+   - Enable scope_to_per_operation_thread_id to bind the provider to a single
+     thread for the lifetime of that provider instance. Use the same thread
+     object for reads/writes with that provider.
+
+3) Multiple agents with isolated memory
+   - Use different agent_id values to keep memories separated for different
+     agent personas, even when the user_id is the same.
+
+Requirements:
+  - A Redis instance with RediSearch enabled (e.g., Redis Stack)
+  - agent-framework with the Redis extra installed: pip install "agent-framework-redis"
+  - Optionally an OpenAI API key for the chat client in this demo
+
+Run:
+  python redis_threads.py
+"""
+
+import asyncio
+import os
+import uuid
+
+from agent_framework.openai import OpenAIChatClient
+from agent_framework_redis._provider import RedisProvider
+from redisvl.extensions.cache.embeddings import EmbeddingsCache
+from redisvl.utils.vectorize import OpenAITextVectorizer
+
+# Please set the OPENAI_API_KEY and OPENAI_CHAT_MODEL_ID environment variables to use the OpenAI vectorizer
+# Recommend default for OPENAI_CHAT_MODEL_ID is gpt-4o-mini
+
+
+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())
+
+    client = OpenAIChatClient(
+        model_id=os.getenv("OPENAI_CHAT_MODEL_ID", "gpt-4o-mini"),
+        api_key=os.getenv("OPENAI_API_KEY"),
+    )
+
+    provider = RedisProvider(
+        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
+    )
+
+    agent = client.as_agent(
+        name="GlobalMemoryAssistant",
+        instructions=(
+            "You are a helpful assistant. Personalize replies using provided context. "
+            "Before answering, always check for stored context containing information"
+        ),
+        tools=[],
+        context_provider=provider,
+    )
+
+    # Store a preference in the global scope
+    query = "Remember that I prefer technical responses with code examples when discussing programming."
+    print(f"User: {query}")
+    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()
+    query = "What technical responses do I prefer?"
+    print(f"User (new thread): {query}")
+    result = await agent.run(query, thread=new_thread)
+    print(f"Agent: {result}\n")
+
+    # Clean up the Redis index
+    await provider.redis_index.delete()
+
+
+async def example_per_operation_thread_scope() -> None:
+    """Example 2: Per-operation thread scope (memories isolated per thread).
+
+    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.
+    """
+    print("2. Per-Operation Thread Scope Example:")
+    print("-" * 40)
+
+    client = OpenAIChatClient(
+        model_id=os.getenv("OPENAI_CHAT_MODEL_ID", "gpt-4o-mini"),
+        api_key=os.getenv("OPENAI_API_KEY"),
+    )
+
+    vectorizer = OpenAITextVectorizer(
+        model="text-embedding-ada-002",
+        api_config={"api_key": os.getenv("OPENAI_API_KEY")},
+        cache=EmbeddingsCache(name="openai_embeddings_cache", redis_url="redis://localhost:6379"),
+    )
+
+    provider = RedisProvider(
+        redis_url="redis://localhost:6379",
+        index_name="redis_threads_dynamic",
+        # overwrite_redis_index=True,
+        # drop_redis_index=True,
+        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
+        redis_vectorizer=vectorizer,
+        vector_field_name="vector",
+        vector_algorithm="hnsw",
+        vector_distance_metric="cosine",
+    )
+
+    agent = client.as_agent(
+        name="ScopedMemoryAssistant",
+        instructions="You are an assistant with thread-scoped memory.",
+        context_provider=provider,
+    )
+
+    # Create a specific thread for this scoped provider
+    dedicated_thread = agent.get_new_thread()
+
+    # Store some information in the dedicated thread
+    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"Agent: {result}\n")
+
+    # Test memory retrieval in the same dedicated thread
+    query = "What project am I working on?"
+    print(f"User (same dedicated thread): {query}")
+    result = await agent.run(query, thread=dedicated_thread)
+    print(f"Agent: {result}\n")
+
+    # Store more information in the same thread
+    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"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"Agent: {result}\n")
+
+    # Clean up the Redis index
+    await provider.redis_index.delete()
+
+
+async def example_multiple_agents() -> None:
+    """Example 3: Multiple agents with different thread configurations (isolated via agent_id) but within 1 index."""
+    print("3. Multiple Agents with Different Thread Configurations:")
+    print("-" * 40)
+
+    client = OpenAIChatClient(
+        model_id=os.getenv("OPENAI_CHAT_MODEL_ID", "gpt-4o-mini"),
+        api_key=os.getenv("OPENAI_API_KEY"),
+    )
+
+    vectorizer = OpenAITextVectorizer(
+        model="text-embedding-ada-002",
+        api_config={"api_key": os.getenv("OPENAI_API_KEY")},
+        cache=EmbeddingsCache(name="openai_embeddings_cache", redis_url="redis://localhost:6379"),
+    )
+
+    personal_provider = RedisProvider(
+        redis_url="redis://localhost:6379",
+        index_name="redis_threads_agents",
+        application_id="threads_demo_app",
+        agent_id="agent_personal",
+        user_id="threads_demo_user",
+        redis_vectorizer=vectorizer,
+        vector_field_name="vector",
+        vector_algorithm="hnsw",
+        vector_distance_metric="cosine",
+    )
+
+    personal_agent = client.as_agent(
+        name="PersonalAssistant",
+        instructions="You are a personal assistant that helps with personal tasks.",
+        context_provider=personal_provider,
+    )
+
+    work_provider = RedisProvider(
+        redis_url="redis://localhost:6379",
+        index_name="redis_threads_agents",
+        application_id="threads_demo_app",
+        agent_id="agent_work",
+        user_id="threads_demo_user",
+        redis_vectorizer=vectorizer,
+        vector_field_name="vector",
+        vector_algorithm="hnsw",
+        vector_distance_metric="cosine",
+    )
+
+    work_agent = client.as_agent(
+        name="WorkAssistant",
+        instructions="You are a work assistant that helps with professional tasks.",
+        context_provider=work_provider,
+    )
+
+    # 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")
+
+    # Clean up the Redis index (shared)
+    await work_provider.redis_index.delete()
+
+
+async def main() -> None:
+    print("=== Redis Thread Scoping Examples ===\n")
+    await example_global_thread_scope()
+    await example_per_operation_thread_scope()
+    await example_multiple_agents()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())