RedisSession

Redis-based session storage for openai-agents.

Class Definition

RedisSession

RedisSession(
    session_id,
    redis_client,
    *,
    key_prefix="openai_agents_session",
    ttl=None,
)

Bases: SessionABC

Redis-based session storage for openai-agents.

Stores conversation history in Redis using a sorted set for ordered retrieval. Each session is stored under a key pattern: {prefix}:{session_id}.

Parameters:

Name	Type	Description	Default
session_id	str	Unique identifier for this session.	required
redis_client	Redis[bytes]	An async Redis client instance.	required
key_prefix	str	Prefix for Redis keys (default: "openai_agents_session").	'openai_agents_session'
ttl	int | None	Time-to-live in seconds for session data. None means no expiration.	None

Example

import redis.asyncio as redis
from openai_agents_session import RedisSession

client = redis.from_url("redis://localhost:6379")
session = RedisSession(
    session_id="user-123",
    redis_client=client,
    ttl=3600,  # 1 hour
)

Source code in src/openai_agents_session/redis.py

def __init__(
    self,
    session_id: str,
    redis_client: Redis[bytes],
    *,
    key_prefix: str = "openai_agents_session",
    ttl: int | None = None,
) -> None:
    self.session_id = session_id
    self._client = redis_client
    self._key_prefix = key_prefix
    self._ttl = ttl

get_items async

get_items(limit=None)

Retrieve the conversation history for this session.

Parameters:

Name	Type	Description	Default
limit	int | None	Maximum number of items to retrieve. If None, returns all items. When specified, returns the most recent limit items.	None

Returns:

Type	Description
list[TResponseInputItem]	List of conversation items in chronological order.

Source code in src/openai_agents_session/redis.py

async def get_items(self, limit: int | None = None) -> list[TResponseInputItem]:
    """Retrieve the conversation history for this session.

    Args:
        limit: Maximum number of items to retrieve. If None, returns all items.
               When specified, returns the most recent `limit` items.

    Returns:
        List of conversation items in chronological order.
    """
    if limit is not None:
        # Get the most recent `limit` items (negative index from the end)
        items = await self._client.lrange(self._key, -limit, -1)
    else:
        items = await self._client.lrange(self._key, 0, -1)

    await self._refresh_ttl()
    return [self._deserialize_item(item) for item in items]

add_items async

add_items(items)

Add new items to the conversation history.

Parameters:

Name	Type	Description	Default
items	list[TResponseInputItem]	List of items to add to the session.	required

Source code in src/openai_agents_session/redis.py

async def add_items(self, items: list[TResponseInputItem]) -> None:
    """Add new items to the conversation history.

    Args:
        items: List of items to add to the session.
    """
    if not items:
        return

    serialized = [self._serialize_item(item) for item in items]
    await self._client.rpush(self._key, *serialized)
    await self._refresh_ttl()

pop_item async

pop_item()

Remove and return the most recent item from the session.

Returns:

Type	Description
TResponseInputItem | None	The most recent item, or None if the session is empty.

Source code in src/openai_agents_session/redis.py

async def pop_item(self) -> TResponseInputItem | None:
    """Remove and return the most recent item from the session.

    Returns:
        The most recent item, or None if the session is empty.
    """
    item = await self._client.rpop(self._key)
    await self._refresh_ttl()

    if item is None:
        return None
    return self._deserialize_item(item)

clear_session async

clear_session()

Clear all items for this session.

Source code in src/openai_agents_session/redis.py

async def clear_session(self) -> None:
    """Clear all items for this session."""
    await self._client.delete(self._key)

Usage Example

import redis.asyncio as redis
from openai_agents_session import RedisSession

# Create client
client = redis.from_url("redis://localhost:6379")

# Create session
session = RedisSession(
    session_id="user-123",
    redis_client=client,
    key_prefix="myapp:sessions",
    ttl=3600,
)

# Add items
await session.add_items([
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"},
])

# Get items
items = await session.get_items()
# [{"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hi there!"}]

# Get limited items
recent = await session.get_items(limit=1)
# [{"role": "assistant", "content": "Hi there!"}]

# Pop last item
last = await session.pop_item()
# {"role": "assistant", "content": "Hi there!"}

# Clear session
await session.clear_session()

Parameters

session_id

• Type: str
• Required: Yes

Unique identifier for the session. Used as part of the Redis key.

redis_client

• Type: Redis[bytes]
• Required: Yes

An async Redis client instance from redis.asyncio.

key_prefix

• Type: str
• Default: "openai_agents_session"

Prefix for Redis keys. The full key format is {key_prefix}:{session_id}.

ttl

• Type: int | None
• Default: None

Time-to-live in seconds. If set, the key will expire after this duration. The TTL is refreshed on every add_items() call.

Methods

get_items

async def get_items(self, limit: int | None = None) -> list[TResponseInputItem]

Retrieve conversation history.

Parameters:

• limit: Maximum number of items to return. Returns the most recent items.

Returns: List of conversation items in chronological order.

add_items

async def add_items(self, items: list[TResponseInputItem]) -> None

Add new items to the conversation history.

Parameters:

• items: List of items to add.

pop_item

async def pop_item(self) -> TResponseInputItem | None

Remove and return the most recent item.

Returns: The removed item, or None if the session is empty.

clear_session

async def clear_session(self) -> None

Delete all items in the session.

Redis Key Structure

Keys are stored as Redis lists:

Key: {key_prefix}:{session_id}
Type: List
Value: [JSON item 1, JSON item 2, ...]

See Also

• Redis Backend Guide
• Quick Start