Add Sessions for Automatic Conversation History Management

[knowsuchagency]

Overview

Resolves #745

This PR introduces Sessions, a new core feature that automatically maintains conversation history across multiple agent runs, eliminating the need to manually handle .to_input_list() between turns.

Key Features

🧠 Automatic Memory Management

• Zero-effort conversation continuity: Agents automatically remember previous context without manual state management
• Session-based organization: Each conversation is isolated by unique session IDs
• Seamless integration: Works with existing Runner.run(), Runner.run_sync(), and Runner.run_streamed() methods

🔌 Extensible Session Protocol

• Library-agnostic design: Clean protocol interface allows any storage backend
• Drop-in implementations: Easy integration with Redis, PostgreSQL, MongoDB, or any custom storage
• Production-ready interface: Async-first design with proper error handling and type safety
• Vendor flexibility: Library authors can provide their own Session implementations

💾 Built-in SQLite Implementation

• In-memory SQLite: Perfect for temporary conversations during development
• Persistent SQLite: File-based storage for conversations that survive application restarts
• Thread-safe operations: Production-ready with connection pooling and proper concurrency handling

🔧 Simple API

# Before: Manual conversation management result1 = await Runner.run(agent, "What's the weather?") new_input = result1.to_input_list() + [{"role": "user", "content": "How about tomorrow?"}] result2 = await Runner.run(agent, new_input) # After: Automatic with Sessions session = SQLiteSession("user_123") result1 = await Runner.run(agent, "What's the weather?", session=session) result2 = await Runner.run(agent, "How about tomorrow?", session=session) # Remembers context automatically

What's Included

Core Session Protocol

• Session Protocol: Clean, async interface that any storage backend can implement
• Type-safe design: Full type hints and runtime validation
• Standard operations: get_items(), add_items(), pop_item(), clear_session()
• Extensibility-first: Designed for third-party implementations

Reference Implementation

• SQLiteSession Class: Production-ready SQLite implementation
• Automatic schema management: Creates tables and indexes automatically
• Connection pooling: Thread-safe operations with proper resource management
• Flexible storage: In-memory or persistent file-based databases

Runner Integration

• New session parameter: Drop-in addition to existing Runner methods
• Backward compatibility: Zero breaking changes to existing code
• Automatic history management: Prepends conversation history before each run

Session Protocol for Library Authors

The Session protocol provides a clean interface for implementing custom storage backends:

from agents.memory import Session from typing import List class MyCustomSession: """Custom session implementation following the Session protocol.""" def __init__(self, session_id: str): self.session_id = session_id # Your initialization here async def get_items(self, limit: int | None = None) -> List[dict]: """Retrieve conversation history for this session.""" # Your implementation here pass async def add_items(self, items: List[dict]) -> None: """Store new items for this session.""" # Your implementation here pass async def pop_item(self) -> dict | None: """Remove and return the most recent item from this session.""" # Your implementation here pass async def clear_session(self) -> None: """Clear all items for this session.""" # Your implementation here pass # Works seamlessly with any custom implementation result = await Runner.run(agent, "Hello", session=MyCustomSession("session_123"))

Example Third-Party Implementations

# Redis-based session (hypothetical library implementation) from redis_sessions import RedisSession session = RedisSession("user_123", redis_url="redis://localhost:6379") # PostgreSQL-based session (hypothetical library implementation)  from postgres_sessions import PostgreSQLSession session = PostgreSQLSession("user_123", connection_string="postgresql://...") # Cloud-based session (hypothetical library implementation) from cloud_sessions import CloudSession session = CloudSession("user_123", api_key="...", region="us-east-1") # All work identically with the Runner result = await Runner.run(agent, "Hello", session=session)

Benefits

For Application Developers

• Reduces boilerplate: No more manual .to_input_list() management
• Prevents memory leaks: Automatic cleanup and organized storage
• Easier debugging: Clear conversation history tracking
• Flexible storage: Choose the right backend for your needs

For Library Authors

• Clean integration: Simple protocol to implement for any storage backend
• Type safety: Full type hints and runtime validation
• Async-first: Modern async/await design throughout
• Documentation: Comprehensive examples and API reference

For Applications

• Better user experience: Seamless conversation continuity
• Scalable architecture: Support for multiple concurrent conversations
• Flexible deployment: In-memory for development, production storage for scale
• Multi-agent support: Same conversation history can be shared across different agents

Usage Examples

Basic Usage with SQLiteSession

from agents import Agent, Runner, SQLiteSession agent = Agent(name="Assistant", instructions="Reply concisely.") session = SQLiteSession("conversation_123") # Conversation flows naturally await Runner.run(agent, "Hi, I'm planning a trip to Japan", session=session) await Runner.run(agent, "What's the best time to visit?", session=session) await Runner.run(agent, "How about cherry blossom season?", session=session)

Multiple Sessions with Isolation

# Different users get separate conversation histories session_alice = SQLiteSession("user_alice") session_bob = SQLiteSession("user_bob") # Completely isolated conversations await Runner.run(agent, "I like pizza", session=session_alice) await Runner.run(agent, "I like sushi", session=session_bob)

Persistent vs In-Memory Storage

# In-memory database (lost when process ends) session = SQLiteSession("user_123") # Persistent file-based database session = SQLiteSession("user_123", "conversations.db")

Session Management Operations

session = SQLiteSession("user_123") # Get all items in a session items = await session.get_items() # Add new items to a session new_items = [ {"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hi there!"} ] await session.add_items(new_items) # Remove and return the most recent item (useful for corrections) last_item = await session.pop_item() # Clear all items from a session await session.clear_session()

Message Correction Pattern

# User wants to correct their last question user_message = await session.pop_item() # Remove user's question assistant_message = await session.pop_item() # Remove agent's response # Ask a corrected question result = await Runner.run( agent, "What's 2 + 3?", # Corrected question session=session )

Technical Details

Session Protocol Design

• Async-first: All operations are async for non-blocking I/O
• Type-safe: Full type hints with runtime validation
• Error handling: Graceful degradation and detailed error messages
• Resource management: Proper cleanup and connection handling

SQLiteSession Implementation

• Thread-safe operations with connection pooling
• Automatic schema management with proper indexing
• JSON serialization for message storage
• Memory-efficient conversation retrieval and storage
• Cross-platform compatibility

Breaking Changes

None. This is a purely additive feature that doesn't affect existing functionality.

Documentation

• Updated core concepts in docs/index.md to highlight Sessions as a key primitive
• New comprehensive guide at docs/sessions.md with protocol implementation examples
• Enhanced docs/running_agents.md with automatic vs manual conversation management
• Full API reference integration via docs/ref/memory.md
• Implementation guide for library authors

Sessions represent a significant architectural improvement for building conversational AI applications with the Agents SDK. The extensible Session protocol enables the ecosystem to provide specialized storage backends while maintaining a consistent, simple API for application developers.

[knowsuchagency]

The changes in run.py should be a lot more straightforward now @rm-openai. The business logic is largely the same with minor edits to accommodate the new Session interface. LMK if you notice any other necessary edits, thanks!

[rm-openai]

@knowsuchagency this is good to merge, just need to fix the lint/types. You can just copy the last 2 commits from this: #1040

(I can't add to this PR unfortunately)

[sebastian-montero]

Thank you for this @knowsuchagency !! Looking forward to seeing it merged.

[knowsuchagency]

Done thanks @rm-openai !

[rm-openai]

Awesome work @knowsuchagency, thanks for bearing with the long review process and getting this in! Excited for people to use it.

[knowsuchagency]

Thanks for all the excellent feedback and patience as well @rm-openai !! I agree it will be a great feature for users 😃

[knowsuchagency]

Thanks for your review also @slyapustin !