Sessions

Sessions in agent-air represent independent conversation contexts with an LLM. Each session maintains its own conversation history, token tracking, and compaction state. You can run multiple sessions concurrently and switch between them.

Creating Sessions

Programmatic Creation

Create a new session using the controller’s create_session method:

use agent_air::controller::{LLMController, LLMSessionConfig};

let config = LLMSessionConfig::anthropic("api-key", "claude-sonnet-4-20250514")
    .with_system_prompt("You are a helpful assistant.");

let session_id = controller.create_session(config).await?;

The method returns a unique session ID that you use to reference the session in subsequent operations.

Using the /new-session Command

Users can create sessions in the TUI using the /new-session slash command:

/new-session

This creates a new session with the default configuration and switches to it.

Session Configuration

Each session is configured independently. You can create sessions with different models, system prompts, or compaction settings:

// Session for code review
let code_session = LLMSessionConfig::anthropic("key", "claude-sonnet-4-20250514")
    .with_system_prompt("You are a code reviewer. Be thorough and constructive.");

// Session for general questions
let general_session = LLMSessionConfig::anthropic("key", "claude-sonnet-4-20250514")
    .with_system_prompt("You are a helpful assistant.");

let code_id = controller.create_session(code_session).await?;
let general_id = controller.create_session(general_session).await?;

Initial Session State

A new session starts with:

• Empty conversation history
• Zero token counts
• Zero request count
• The system prompt from the configuration

Session Status

Programmatic Access

Query session status using the SessionStatus struct:

pub struct SessionStatus {
    pub session_id: i64,
    pub model: String,
    pub created_at: Instant,
    pub conversation_len: usize,
    pub context_used: i64,
    pub context_limit: i32,
    pub utilization: f64,
    pub total_input: i64,
    pub total_output: i64,
    pub request_count: i64,
}

Key fields:

Using the /status Command

Check the current session in the TUI:

/status

This displays:

• Current session ID
• Agent name and version
• Basic session information

Session Health Indicators

Context Pressure: High utilization (above 0.75) indicates the session is approaching the compaction threshold. The session remains healthy but may compact soon.

Request Count: Tracks API calls made. Useful for monitoring activity and estimating costs.

Conversation Length: Long conversations may benefit from compaction to maintain coherence.

Switching Sessions

Programmatic Switching

Switch the active session in your application:

app.switch_session(target_session_id);

When switching sessions:

1. The current session’s state is saved
2. The target session becomes active
3. The target session’s conversation is restored

Using the /sessions Command

Open the session picker in the TUI:

/sessions

The picker displays all active sessions with:

• Session ID
• Model name
• Context usage and limit
• Creation time
• An asterisk (*) marking the current session

Navigation:

• Up/Down arrows or Ctrl+P/Ctrl+N: Move selection
• Enter: Switch to selected session
• Esc: Cancel and close picker

Independent Session State

Each session maintains independent:

• Conversation history
• Token tracking
• Compaction state

Switching sessions preserves the state of all sessions. Returning to a previous session shows the conversation as it was left.

Session Information

The SessionInfo struct provides metadata for session management:

pub struct SessionInfo {
    pub id: i64,
    pub model: String,
    pub context_used: i64,
    pub context_limit: i32,
    pub created_at: Instant,
}

This is used by the session picker and for programmatic session management.

Multiple Concurrent Sessions

Agent Air supports running multiple sessions concurrently:

// Create multiple sessions
let session_a = controller.create_session(config_a).await?;
let session_b = controller.create_session(config_b).await?;

// Each session processes requests independently
controller.send_message(session_a, "Hello from session A").await?;
controller.send_message(session_b, "Hello from session B").await?;

Each session:

• Has its own conversation history
• Tracks tokens independently
• Can use different models or configurations
• Processes requests in its own async task

Default Commands

The session-related commands are included in the default command set: