agent-framework-redis provides robust Redis integration for the Microsoft Agent Framework, offering persistent storage for conversational history and a flexible context provider for long-term memory. It leverages Redis for efficient, thread-safe chat message storage and advanced context management, including optional vector search capabilities. The library is part of the broader Microsoft Agent Framework ecosystem and is actively developed, with its release cadence tied to the main framework.
Install & Compatibility
Where this runs
tested against v1.0.0b260521 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 7.2s
py 3.11
✕ build_error
✓ 6.3s
py 3.12
✕ build_error
✓ 5.8s
py 3.13
✕ build_error
✓ 5.9s
py 3.9
✕ build_error
✕ build_error
134MB installed
● package 134MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RedisChatMessageStore
✓ from agent_framework.redis import RedisChatMessageStore
RedisProvider
✓ from agent_framework.redis import RedisProvider
Used for context management and long-term memory, potentially with vector search. `RedisChatMessageStore` is for chat history.
This quickstart demonstrates how to initialize `RedisChatMessageStore`, add messages to it, retrieve messages, and observe message trimming if a `max_messages` limit is set. It also shows how to clear the session history. For local development, ensure a Redis server is running (e.g., via Docker: `docker run -d -p 6379:6379 redis:latest`).
import asyncio
import os
from agent_framework.redis import RedisChatMessageStore
from agent_framework.core.message import Message, Role
async def main():
# Connect to Redis. Replace with your Redis URL or environment variable.
# For local Redis, use redis://localhost:6379
redis_url = os.environ.get('REDIS_URL', 'redis://localhost:6379')
session_id = 'my-unique-conversation-123'
# Initialize the Redis chat message store
# max_messages can be set to limit history, None for unlimited
store = RedisChatMessageStore(
redis_url=redis_url,
thread_id=session_id,
max_messages=10 # Example: retain last 10 messages
)
print(f"Storing messages for session: {session_id}")
# Add messages to the store
await store.add_messages([
Message(role=Role.USER, content='Hello, agent!', author_name='User'),
Message(role=Role.ASSISTANT, content='Hi there! How can I help you?', author_name='Agent')
])
# Retrieve messages from the store
retrieved_messages = await store.get_messages()
print("\nRetrieved messages:")
for msg in retrieved_messages:
print(f"[{msg.author_name} ({msg.role.value})]: {msg.content}")
# Add more messages to test trimming
for i in range(1, 15):
await store.add_messages([
Message(role=Role.USER, content=f'Message {i}', author_name=f'User{i}')
])
print(f"\nRetrieved messages after adding more (max_messages={store.max_messages}):")
trimmed_messages = await store.get_messages()
for msg in trimmed_messages:
print(f"[{msg.author_name} ({msg.role.value})]: {msg.content}")
# Clear the session history
await store.clear()
print("\nMessages cleared. Current messages:")
print(await store.get_messages())
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
gotchaThe current version `1.0.0b260409` indicates a beta release. While the core `agent-framework` is stable (v1.0.0), specific integration packages like `agent-framework-redis` might still undergo API changes or have unfinalized features before a stable release. Always refer to the latest official documentation.fixAlways pin to exact versions (`==`) in production environments and review release notes for updates. Consult the Microsoft Agent Framework GitHub repository for the latest status.
affects: 1.0.0b*
breakingThe broader Microsoft Agent Framework (which `agent-framework-redis` is a part of) underwent significant breaking changes leading up to its 1.0.0 stable release, particularly in `agent-framework-core` and `agent-framework-openai`. Although `agent-framework-redis` itself wasn't explicitly listed with all breaking changes, updates to the parent framework could implicitly affect its usage or require dependency version bumps.fixMigrate to `agent-framework` version 1.0.0 or higher. Carefully review the migration guide for the main `microsoft/agent-framework` repository if upgrading from pre-1.0.0 versions.
affects: <1.0.0 (of parent framework)
gotchaWhen initializing `RedisChatMessageStore` or `RedisProvider`, you must provide either `redis_url` or a combination of `credential_provider` (for Azure AD auth) and `host`. Providing both `redis_url` and `credential_provider`, or neither, will raise a `ValueError`.fixEnsure that only one method of Redis connection configuration is used: either pass a `redis_url` string, or pass a `credential_provider` instance along with the `host` parameter. Never both, and never neither.
affects: All versions
gotchaThe library offers `RedisChatMessageStore` for managing conversational chat history and `RedisProvider` for general context management and long-term memory, potentially with vector search. Confusing these or using the wrong class for a specific memory pattern is a common footgun.fix`RedisChatMessageStore` is designed for chronological storage of `Message` objects in a chat-like format. `RedisProvider` is intended for storing and retrieving more flexible 'context' or 'memories', often leveraging Redis's search capabilities. Understand the distinct purposes of each class before implementing.
affects: All versions
Upgrade
Version history
1.0.0b260521latest on PyPI
Audit
Dependencies
redisrequiredCore Redis client for communication.
typing-extensionsrequiredProvides backports of standard library typing features.
azure-identityoptionalRequired for Azure AD authentication when using `CredentialProvider` with Azure Managed Redis.
Resources
No resource links recorded.