Skip to main content
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
Sessions enable sophisticated multi-turn interactions where agents can remember context, build on previous work, and maintain continuity across hours, days, or even weeks.

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:
  1. No Session ID: Agentbase creates a new session with fresh state
  2. With Session ID: Agentbase resumes the existing session with all previous context
  3. Auto-Pause: After 5 minutes of inactivity, the computational environment pauses
  4. Auto-Resume: Next request automatically resumes the paused environment
  5. 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

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

Security and Isolation

Session Isolation: Each session is completely isolated. Never share session IDs between different users or security contexts.

Integration with Other Primitives

With States

Sessions contain states:
Learn more: States Primitive

With Prompts

Different sessions can have different prompts:
Learn more: Prompts Primitive

With Multi-Agent

Sessions can involve multiple agents:
Learn more: Multi-Agent Primitive

With Custom Tools

Tools are available throughout session:
Learn more: Custom Tools Primitive

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

Problem: Error when trying to use session IDSolutions:
  • Verify session ID is correct
  • Check if session has expired
  • Implement fallback to create new session
Problem: Agent doesn’t remember previous messagesSolution: Ensure you’re passing the session ID
Problem: Requests to existing session are slowPossible Causes:
  • Session was paused and is resuming
  • Large message history
  • Heavy computational state
Solutions:
  • Keep sessions active with periodic requests
  • Summarize long conversations
  • Clean up large files
Problem: Unrelated context interfering with current taskSolution: Use separate sessions for different workflows

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
Remember: Sessions are the foundation of continuity in Agentbase. Save session IDs, reuse them for related work, and use separate sessions for independent workflows.