Feature: Redis Session Management

[rafaelpierre]

Add Redis Session Support and Restructure Memory Module

Context

I've fully switched to OpenAI Agents SDK at my company and I was looking for a distributed-systems friendly session management mechanism. I wasn't sure at the beginning if creating a RedisSession would defeat the "lightweight" purpose of OpenAI Agents SDK, so initially I've published openai-agents-redis on PyPi. It follows the Session protocol and works quite similarly to SQLLiteSession - but with redis as the backend.

Since I think the community would benefit from having this additional option for session management, I'm creating this PR - which incorporates the work I've done to support Redis for session management within OpenAI Agents SDK.

🚀 Overview

This PR introduces Redis-based session storage for the OpenAI Agents SDK and restructures the memory module for better organization and extensibility. The changes provide developers with a distributed, scalable alternative to SQLite sessions while maintaining full backward compatibility.

🎯 Key Features

✨ New Redis Session Implementation

• RedisSession: Full-featured Redis-based session storage with TTL support
• RedisSessionManager: Connection pooling and session management
• Async/await support: Native async context managers for proper resource cleanup
• Automatic expiration: Built-in TTL support for session lifecycle management

🏗️ Memory Module Restructuring

• Provider-based architecture: Organized session implementations under agents.memory.providers
• Clean imports: Improved import paths for better developer experience
• Protocol-based design: Clear contracts for custom session implementations

📁 Changes Summary

New Files

• src/agents/memory/providers/redis.py - Redis session implementation (345 lines)
• src/agents/memory/providers/sqlite.py - Extracted SQLite session (278 lines)
• src/agents/memory/providers/__init__.py - Provider module initialization
• tests/test_redis_session.py - Comprehensive test suite (553 lines, 33 tests)

Modified Files

• src/agents/memory/__init__.py - Updated exports for new structure
• src/agents/memory/session.py - Cleaned up to contain only protocol definitions
• docs/sessions.md - Documentation update
• pyproject.toml - Added Redis dependency
• Documentation updated for new module structure

🔧 Technical Implementation

Redis Session Features

from agents.memory.providers.redis import RedisSession, RedisSessionManager

# Basic usage with TTL
session = RedisSession("user_123", ttl=3600)

# Production usage with connection pooling
manager = RedisSessionManager(max_connections=10, default_ttl=7200)
session = manager.get_session("user_123")

Key Capabilities

• Atomic operations: Redis pipelines ensure data consistency
• Connection pooling: Efficient resource management for production use
• Session management: List, delete, and manage sessions at scale
• Error handling: Robust handling of connection issues and data corruption
• Context managers: Automatic resource cleanup

🧪 Testing

Test Coverage (33 tests)

• 23 tests for RedisSession class
• 9 tests for RedisSessionManager class
• 1 integration test for complete lifecycle

Test Features

• Edge cases: Invalid JSON, empty sessions, connection failures
• Async support: Full async/await testing patterns
• Resource management: Context manager and cleanup testing

Test Results

$ uv run pytest tests/test_redis_session.py -v
============================== 33 passed in 0.07s ==============================

📚 Documentation Updates

sessions.md

• Redis examples: Usage patterns and best practices
• Comparison guide: SQLite vs Redis decision matrix
• Production examples: Connection pooling and session management
• Migration guide: How to switch from SQLite to Redis
• API reference: Updated with new import paths

### Backward Compatibility
- ✅ Existing SQLite functionality preserved
- ✅ Same API contract maintained

## 🔍 Quality Assurance

### Code Quality
- ✅ **Linting**: 100% compliance with project standards
- ✅ **Type hints**: Full type annotation coverage
- ✅ **Documentation**: Docstrings and examples

### Testing
- ✅ **Unit tests**: 33 test cases
- ✅ **Integration tests**: Full lifecycle testing
- ✅ **Mocking**: No external dependencies in tests
- ✅ **Edge cases**: Error conditions and resource cleanup

### Performance
- ✅ **Connection pooling**: Efficient resource usage
- ✅ **Async operations**: Non-blocking I/O throughout
- ✅ **Atomic operations**: Redis pipelines for consistency
- ✅ **Memory efficiency**: Proper resource cleanup

## 🚦 Dependencies

### New Dependencies
- `redis[hiredis]>=6.2.0` - High-performance Redis client with optional C extensions

### Development Setup
```bash
# Redis is included by default
pip install openai-agents

# For development, start Redis:
docker run -d -p 6379:6379 redis:latest

🔮 Future Considerations

This provider-based architecture enables:

• Additional session backends (DynamoDB, MongoDB, etc.)
• Custom session implementations for specific use cases
• Enhanced monitoring and observability features
• Advanced session management capabilities

📋 Checklist

• ✅ Redis session implementation with full feature parity
• ✅ Connection pooling and session management
• ✅ Comprehensive test suite (33 tests, 100% pass rate)
• ✅ Updated documentation with examples and guides
• ✅ Backward compatibility maintained
• ✅ Code quality standards met
• ✅ Production-ready error handling and resource management

---

[rafaelpierre]

@seratch @rm-openai would you mind taking a look?

[seratch]

Left a few general comments. I think supporting redis is a great addition for many developers. I would like @rm-openai to make the final decision on whether we should have this though!

[seratch]

May I ask you to resolve the uv.lock conflicts?

[rafaelpierre]

May I ask you to resolve the uv.lock conflicts?

@seratch sure thing, that is done!

[rafaelpierre]

@seratch tests are failing due to missing redis dependency in uv.lock - I'll do uv sync once I get home since I have no access to pypi.org from work to do it (only have access to a private PyPi mirror, but using it would mess up uv.lock).

I think once that is done, tests will pass

thanks for the reviews and the patience :)

[seratch]

That's weird. This project has many tests with LiteLLM etc. Perhaps, the uv.lock in this PR needs updates to have redis dep for tests.