Add Sessions for Automatic Conversation History Management

[knowsuchagency]

Overview

This PR introduces Sessions, a new core feature addressing issue #745 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_messages(), add_messages(), pop_message(), 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_messages(self, amount: int | None = None) -> List[dict]:
        """Retrieve conversation history for this session."""
        # Your implementation here
        pass

    async def add_messages(self, messages: List[dict]) -> None:
        """Store new messages for this session."""
        # Your implementation here
        pass

    async def pop_message(self) -> dict | None:
        """Remove and return the most recent message from this session."""
        # Your implementation here
        pass

    async def clear_session(self) -> None:
        """Clear all messages 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 messages in a session
messages = await session.get_messages()

# Add new messages to a session
new_messages = [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"}
]
await session.add_messages(new_messages)

# Remove and return the most recent message (useful for corrections)
last_message = await session.pop_message()

# Clear all messages from a session
await session.clear_session()

Message Correction Pattern

# User wants to correct their last question
user_message = await session.pop_message()  # Remove user's question
assistant_message = await session.pop_message()  # 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.