Inkdown
Start writing

OpenAI Agents Python

21 filesยท0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

07_MEMORY_SESSIONS

Shared from "OpenAI Agents Python" on Inkdown

Memory & Sessions - Comprehensive Deep Dive

Overview

Memory and Sessions in the OpenAI Agents SDK enable conversation persistence across agent runs. Think of sessions as "conversation memory" - they allow agents to remember previous interactions, maintain context over time, and provide continuity in multi-turn conversations. This is essential for building chatbots, assistants, and any application where conversation history matters.

Core Concepts

What is a Session?

A session is a persistent store of conversation history between a user and an agent (or multiple agents). It:

  • Stores all messages, tool calls, and outputs from a conversation
  • Retrieves relevant history when resuming a conversation
  • Manages conversation length and token usage
  • Compacts long conversations to preserve context while reducing tokens
Why Sessions Matter
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
  • Context Continuity - Agents remember previous interactions
  • Multi-Turn Conversations - Enable back-and-forth dialogue
  • Token Efficiency - Intelligent history management
  • Conversation Analytics - Track conversation patterns
  • Resume Capability - Pause and resume conversations
  • Multi-Agent History - Track which agent said what
    • Session Types

    The SDK supports several session implementations:

    1. SQLiteSession - Local SQLite database storage
    2. OpenAIConversationsSession - OpenAI's server-managed conversations
    3. OpenAIResponsesCompactionSession - OpenAI Responses API with compaction
    4. Custom Sessions - Implement your own session backend

    Session Interface

    Session ABC

    All sessions implement the SessionABC base class:

    Python

    Key Methods:

    • save_items() - Store conversation items
    • load_items() - Retrieve conversation items
    Session Settings

    Configure session behavior:

    Python

    SQLite Session

    Basic Usage
    Python
    Session Initialization
    Python
    Conversation IDs

    Conversation IDs identify unique conversations:

    Python

    Best practices:

    • Use user IDs for per-user conversations
    • Use thread IDs for conversation threads
    • Use UUIDs for unique identifiers
    • Avoid hardcoded IDs in production
    Session Limits

    Control how much history is loaded:

    Python

    Why limit items:

    • Reduce token usage
    • Improve response time
    • Focus on recent context
    • Manage memory

    OpenAI Conversations Session

    Server-Managed Conversations

    OpenAI provides server-managed conversation storage:

    Python

    Benefits:

    • No local storage needed
    • Automatic prompt caching
    • Better performance
    • Managed by OpenAI

    How it works:

    • OpenAI stores conversation history on their servers
    • Only deltas (new items) are sent
    • The server maintains full context
    • Session persistence is handled automatically
    When to Use

    Use OpenAIConversationsSession when:

    • You want to reduce local storage
    • You're using OpenAI's Responses API
    • You want automatic prompt caching
    • You don't need custom session logic

    Use SQLiteSession when:

    • You need local control over data
    • You want custom session logic
    • You're not using OpenAI exclusively
    • You need to analyze conversation data

    OpenAI Responses Compaction Session

    Intelligent Compaction

    The Responses API supports intelligent conversation compaction:

    Python

    How compaction works:

    • Older messages are summarized
    • Key information is preserved
    • Token usage is reduced
    • Context is maintained
    Compaction Configuration
    Python

    Session Input Callback

    Custom Input Handling

    Control how new input is combined with session history:

    Python

    Use cases:

    • Custom history filtering
    • Special input processing
    • Context window management
    • Custom formatting

    Session and Agent Lifecycle

    Session Persistence Across Runs
    Python
    Session with Handoffs

    Sessions track which agent generated each item:

    Python
    Session with Multiple Conversations
    Python

    Session Implementation Details

    Item Storage

    Sessions store items as input items:

    Python
    Item Retrieval

    Sessions retrieve items with optional limits:

    Python
    Session and RunState

    RunState includes session information:

    Python

    Custom Session Implementation

    Creating a Custom Session

    Implement the SessionABC interface:

    Python
    Using Custom Session
    Python

    Use cases:

    • Redis/MongoDB storage
    • Cloud storage (S3, etc.)
    • Custom encryption
    • Distributed systems

    Session and Tracing

    Session Metadata in Traces

    Sessions include metadata in traces:

    Python
    Session Analytics

    Analyze session data:

    Python

    Session Best Practices

    1. Use Unique Conversation IDs

    Always use unique identifiers:

    Python
    2. Set Appropriate Limits

    Configure session limits based on your needs:

    Python
    3. Handle Session Errors

    Handle session failures gracefully:

    Python
    4. Clean Up Old Sessions

    Implement cleanup for old sessions:

    Python
    5. Monitor Session Performance

    Track session performance:

    Python

    Session Patterns

    1. Per-User Sessions

    Each user gets their own conversation history:

    Python
    2. Thread-Based Sessions

    Each conversation thread gets its own history:

    Python
    3. Session with Context Window Management

    Manage context window with sessions:

    Python
    4. Session with Encryption

    Encrypt sensitive session data:

    Python
    5. Session with Analytics

    Track conversation analytics:

    Python

    Session and Server-Managed Conversations

    Compatibility

    Server-managed conversations have limitations:

    Python
    When to Avoid Server-Managed

    Avoid when:

    • You need custom session logic
    • You need to analyze conversation data locally
    • You're not using OpenAI exclusively
    • You need fine-grained control

    Session and Memory Rollouts

    Sandbox Memory Rollouts

    For sandbox agents, sessions can include memory rollouts:

    Python

    Session Error Handling

    Session Errors

    Handle session-related errors:

    Python
    Recovery Strategies

    Implement recovery strategies:

    Python

    Session Performance

    Optimization Techniques

    Optimize session performance:

    Python
    Monitoring Session Performance

    Track session metrics:

    Python

    Summary

    Sessions enable conversation persistence. Key takeaways:

    1. Sessions store conversation history
    2. SQLiteSession provides local SQLite storage
    3. OpenAIConversationsSession uses server-managed storage
    4. Conversation IDs identify unique conversations
    5. Session limits control history size
    6. Compaction reduces token usage for long conversations
    7. Input callbacks customize history combination
    8. Custom sessions can implement custom backends
    9. SessionABC defines the session interface
    10. Item storage uses input item format
    11. Item retrieval supports optional limits
    12. RunState includes session information
    13. Handoffs are tracked across agents
    14. Multiple conversations can coexist
    15. Tracing includes session metadata
    16. Analytics can track conversation patterns
    17. Encryption can protect sensitive data
    18. Performance can be optimized
    19. Error handling should be graceful
    20. Cleanup prevents data bloat

    Sessions are essential for building conversational agents that remember context across interactions.