Sessions are the foundational container for agent conversations, providing persistent context, state management, and continuity across multiple requests.
Overview
The Sessions primitive represents a persistent conversation thread between you and an agent. Each session is a unique, isolated container that maintains:- Conversation History: All messages and responses in chronological order
- Computational State: Files, installed packages, and environment configuration
- Context Memory: Agent’s understanding of ongoing tasks and user preferences
- Tool State: Results from previous tool executions and data gathered
- Session Identity: Unique identifier for tracking and resuming conversations
Automatic Creation
Every agent request creates a new session or continues an existing one
Persistent by Default
Message history and state persist automatically at no extra cost
Isolated Containers
Each session is completely isolated from others for security and privacy
Long-Lived
Sessions can span multiple requests over extended time periods
How Sessions Work
When you make an agent request:- No Session ID: Agentbase creates a new session with fresh state
- With Session ID: Agentbase resumes the existing session with all previous context
- Auto-Pause: After 5 minutes of inactivity, the computational environment pauses
- Auto-Resume: Next request automatically resumes the paused environment
- Expiration: After extended inactivity, sessions eventually expire and clean up
Session Reuse: Pass the same
session parameter to maintain continuity. Each response includes the session ID for use in subsequent requests.Code Examples
Creating a New Session
Continuing a Session
Multi-Turn Conversation
Session Management Pattern
Session Lifecycle
Creation
New sessions are created automatically:Active Phase
Session is actively being used:Pause Phase
After 5 minutes of inactivity:Expiration
After extended inactivity:Use Cases
1. Interactive Development
Multi-session development workflow:2. Customer Support Conversations
Maintain context throughout support interactions:3. Long-Running Research Projects
Accumulate research over multiple sessions:4. Multi-User Collaboration
Separate sessions per user:5. Testing and Iteration
Separate sessions for different test scenarios:6. Scheduled Workflows
Sessions for recurring tasks:Best Practices
Session Organization
One Session Per Workflow
One Session Per Workflow
Store Session Metadata
Store Session Metadata
Clean Up Completed Sessions
Clean Up Completed Sessions
Performance Optimization
Reuse for Related Work
Keep sessions alive for related tasks to avoid cold start overhead
Separate Independent Tasks
Use different sessions for unrelated work to keep context clean
Monitor Session Age
Track session creation time and plan for eventual expiration
Batch Operations
Group related requests in same session to leverage warm state
Error Handling
Handle Session Expiration
Handle Session Expiration
Validate Session State
Validate Session State
Security and Isolation
Integration with Other Primitives
With States
Sessions contain states:With Prompts
Different sessions can have different prompts:With Multi-Agent
Sessions can involve multiple agents:With Custom Tools
Tools are available throughout session:Performance Considerations
Session Startup Time
- New Session (Cold Start): 2-5 seconds to create environment
- Existing Session (Warm): Instant, environment already loaded
- Resumed Session (After Pause): 1-2 seconds to resume
Memory and Context
Very long sessions may accumulate large context:- Short sessions (<10 messages): Optimal performance
- Medium sessions (10-50 messages): Good performance
- Long sessions (50+ messages): Consider periodic summarization
Resource Usage
Monitor session resource consumption:Troubleshooting
Session Not Found
Session Not Found
Problem: Error when trying to use session IDSolutions:
- Verify session ID is correct
- Check if session has expired
- Implement fallback to create new session
Lost Context Between Requests
Lost Context Between Requests
Problem: Agent doesn’t remember previous messagesSolution: Ensure you’re passing the session ID
Slow Session Response
Slow Session Response
Problem: Requests to existing session are slowPossible Causes:
- Session was paused and is resuming
- Large message history
- Heavy computational state
- Keep sessions active with periodic requests
- Summarize long conversations
- Clean up large files
Mixed Context Issues
Mixed Context Issues
Problem: Unrelated context interfering with current taskSolution: Use separate sessions for different workflows
Related Primitives
States
What persists within sessions
Sandbox
Isolated environment for each session
Context Management
Managing conversation context effectively
Multi-Agent
Multiple agents within one session
Additional Resources
API Reference
Session parameters and options
Get Messages
Retrieve session message history
Persistence Guide
How persistence works