Skip to content
Strands Agents SDK

Strands Valkey Session Manager

Section titled “Strands Valkey Session Manager”

{{ community_contribution_banner }}

The Strands Valkey Session Manager is a high-performance session manager for Strands Agents that uses Valkey/Redis for persistent storage. Valkey is a very-low latency cache that enables agents to maintain conversation history and state across multiple interactions, even in distributed environments.

Tested with Amazon ElastiCache Serverless (Redis 7.1, Valkey 8.1), ElastiCache (Redis 7.1, Valkey 8.2), and Upstash.

Installation

Section titled “Installation”
Terminal window
pip install strands-valkey-session-manager

Usage

Section titled “Usage”

Basic Setup

Section titled “Basic Setup”
from strands import Agent
from strands_valkey_session_manager import ValkeySessionManager
from uuid import uuid4
import valkey


# Create a Valkey client
client = valkey.Valkey(host="localhost", port=6379, decode_responses=True)


# Create a session manager with a unique session ID
session_id = str(uuid4())
session_manager = ValkeySessionManager(
    session_id=session_id,
    client=client
)


# Create an agent with the session manager
agent = Agent(session_manager=session_manager)


# Use the agent - all messages are automatically persisted
agent("Hello! Tell me about Valkey.")


# The conversation is now stored in Valkey and can be resumed later using the same session_id


# Display conversation history
messages = session_manager.list_messages(session_id, agent.agent_id)
for msg in messages:
    role = msg.message["role"]
    content = msg.message["content"][0]["text"]
    print(f"** {role.upper()}**: {content}")

Key Features

Section titled “Key Features”
  • Persistent Sessions: Store agent conversations and state in Valkey/Redis
  • Distributed Ready: Share sessions across multiple application instances
  • High Performance: Leverage Valkey’s speed for fast session operations
  • JSON Storage: Native JSON support for complex data structures
  • Automatic Cleanup: Built-in session management and cleanup capabilities

Configuration

Section titled “Configuration”

ValkeySessionManager Parameters

Section titled “ValkeySessionManager Parameters”
  • session_id: Unique identifier for the session
  • client: Configured Valkey client instance (only synchronous versions are supported)

Storage Structure

Section titled “Storage Structure”

The ValkeySessionManager stores data using the following key structure:

session:<session_id>                                        # Session metadata
session:<session_id>:agent:<agent_id>                       # Agent state and metadata
session:<session_id>:agent:<agent_id>:message:<message_id>  # Individual messages

Available Methods

Section titled “Available Methods”

The following methods are used transparently by Strands:

  • create_session(session): Create a new session
  • read_session(session_id): Retrieve session data
  • delete_session(session_id): Remove session and all associated data
  • create_agent(session_id, agent): Store agent in session
  • read_agent(session_id, agent_id): Retrieve agent data
  • update_agent(session_id, agent): Update agent state
  • create_message(session_id, agent_id, message): Store message
  • read_message(session_id, agent_id, message_id): Retrieve message
  • update_message(session_id, agent_id, message): Update message
  • list_messages(session_id, agent_id, limit=None): List all messages

Requirements

Section titled “Requirements”
  • Python 3.10+
  • Valkey/Redis server
  • strands-agents >= 1.0.0
  • valkey >= 6.0.0

References

Section titled “References”