Redis

新增含有 TextSearchProvider 的 RAG

使用適用於 .NET 的與提供者無關 TextSearchProvider 模式。 透過應用程式選擇的 Redis 用戶端或向量儲存連接器實作其搜尋轉接器，將 Redis 結果映射至 TextSearchProvider.TextSearchResult，並透過 AIContextProviders連接提供者。

此方法支援 Redis 支援的 RAG，無需 Redis 專屬的代理框架上下文提供者套件。

安裝套件

pip install agent-framework-redis --pre

新增可搜尋記憶體

當客服人員應該回憶選定的相關資訊，而非重複播放所有先前訊息時，請使用此模式。

Prerequisites

• 一個支援 RediSearch 的 Redis 部署，例如 Redis Stack 或相容的託管服務。
• Microsoft Foundry 專案及範例代理程式的模型部署。
• 啟用混合向量搜尋時使用的嵌入提供者

配置可搜尋記憶體

可搜尋的記憶擷取可跨不同工作階段運作。 每個提供的 application_id、agent_id 和 user_id 都會作為 AND 篩選條件，而未提供的維度則不會被篩選。 你需要至少提供一個識別碼。 提供所有穩定且受信任的識別碼，代表預期的隔離邊界。

想要混合擷取時，可以加裝 Redis 向量器和向量場設定。

# Create a provider with partition scope and OpenAI embeddings

# Please set OPENAI_API_KEY to use the OpenAI vectorizer.
# For chat responses, also set FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL.

# We attach an embedding vectorizer so the provider can perform hybrid (text + vector)
# retrieval. If you prefer text-only retrieval, instantiate RedisContextProvider 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_URL),
)
# 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 = RedisContextProvider(
    source_id="redis_context",
    redis_url=REDIS_URL,
    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",
)

將記憶體附加於代理

將提供者加入context_providers。 服務提供者會在執行後儲存對話細節，並在後續執行前呈現相關上下文。

# Create chat client for the agent
client = create_chat_client()
# Create agent wired to the Redis context provider. The provider automatically
# persists conversational details and surfaces relevant context on each turn.
agent = Agent(
    client=client,
    name="MemoryEnhancedAssistant",
    instructions=(
        "You are a helpful assistant. Personalize replies using provided context. "
        "Before answering, always check for stored context"
    ),
    tools=[],
    context_providers=[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)

保留對話記錄

當會話在應用程式重新啟動後或在其他實例上必須恢復完整文字記錄時，請使用此模式。

Prerequisites

• 可透過 REDIS_URL 連線的 Redis 部署。
• 針對生產環境部署採用 TLS 與經過驗證的 Redis 使用者。

將 RedisHistoryProvider 連接至 context_providers。 提供者會儲存會話中的訊息，並可限制保留訊息數量。

async def example_manual_memory_store() -> None:
    """Basic example of using Redis history provider."""
    print("=== Basic Redis History Provider Example ===")

    # Create Redis history provider
    redis_provider = RedisHistoryProvider(
        source_id="redis_basic_chat",
        redis_url=REDIS_URL,
        application_id=APPLICATION_ID,
        agent_id="redis-bot",
    )

    # Create agent with Redis history provider
    agent = Agent(
        client=OpenAIChatClient(),
        name="RedisBot",
        instructions="You are a helpful assistant that remembers our conversation using Redis.",
        context_providers=[redis_provider],
    )

    # Create session
    session = agent.create_session()

    # Have a conversation
    print("\n--- Starting conversation ---")
    query1 = "Hello! My name is Alice and I love pizza."
    print(f"User: {query1}")
    response1 = await agent.run(query1, session=session)
    print(f"Agent: {response1.text}")

    query2 = "What do you remember about me?"
    print(f"User: {query2}")

使用由呼叫端管理的 Redis 用戶端

當您的應用程式需要共用連線集區，或設定連線行為（例如具時限的逾時設定和健康檢查）時，請提供 redis_client。 用戶端必須是獨立的非同步 Redis 用戶端，並配置為 decode_responses=True。

from agent_framework.redis import RedisHistoryProvider
from redis.asyncio import Redis

redis_client = Redis.from_url(
    "redis://localhost:6379",
    decode_responses=True,
    socket_connect_timeout=3,
    socket_timeout=5,
)

history_provider = RedisHistoryProvider(
    redis_client=redis_client,
    application_id="support-app",
)

不要將 redis_url 與 credential_provider 或 redis_client 組合使用。 RedisHistoryProvider 會借用用戶端，但不會將其關閉，因此應用程式仍需負責其生命週期。 重試行為仍由呼叫端控制。 若重試在連線中斷情況不明後重新執行寫入，則文字記錄附加作業不具等冪性。

預設為具作用範圍的鍵。 設定穩定且非空的 application_id，並在應用程式具有這些隔離邊界時使用 tenant_id 和 agent_id。 提供者也會根據其 source_id 與非空白的工作階段 ID 來區分每個金鑰的範圍。

使用穩定的會話 ID，並在用戶端在程序重啟後必須恢復相同邏輯對話時，將序列化 AgentSession 的 ID 持續保存在受信任的應用程式儲存中。

早期版本將歷史記錄儲存在 {key_prefix}:{session_id or "default"}。 現有部署可在遷移時暫時設定 key_format="legacy" 。 舊版模式已被棄用，不接受具作用域的識別碼，而且作用域模式絕不會讀取、改寫或刪除舊版金鑰。 只將已驗證的紀錄複製到對應的範圍金鑰中，驗證遷移歷史，然後依照保留政策移除舊金鑰。