session-lifecycle

Session Lifecycle

A session is a durable conversation thread between user and agent. Manage it well and you avoid blown context windows, lost state, and confused users.

When to Use

• Designing multi-turn agent UX
• Debugging context-loss or context-overflow
• Choosing when to fork vs resume vs start fresh
• Setting retention policies for session storage

Session States

[idle] → [running] → [idle]        # user sends → agent responds → waits
[idle] → [compacting] → [idle]     # background context reduction
[idle] → [archived]                # user/TTL-triggered

Sessions are long-lived. A single session can span hours to weeks with compaction keeping context in budget.

Creating a Session

// SDK
const sessionId = crypto.randomUUID();
for await (const msg of query({ prompt: firstMessage, options: { sessionId } })) { /* ... */ }

// Managed
const session = await client.beta.sessions.create({ agent_id, metadata: { user_id } });

Always attach your own identifiers in metadata — user ID, tenant, feature flag — so you can filter and audit later.

Resuming

// SDK
for await (const msg of query({ prompt: followUp, options: { resume: sessionId } })) { /* ... */ }

// Managed
await client.beta.sessions.messages.create({ session_id, content: followUp });

Resume when:

• Same user, same topic — preserve context
• Debugging an earlier decision — replay state
• Continuing a long-running workflow

When to Start Fresh

Don't resume when:

• Topic changed completely (user pivoted to a new project)
• Session has stale or incorrect state you can't prompt-correct
• User logged in as a different identity
• Context is so full that compaction would lose critical recent info

Starting fresh is free. Resuming a bad session is expensive.

Compaction

When context approaches the model's limit, older messages are compressed into a summary. Two flavors:

1. Auto-compaction (Managed default, SDK opt-in): system summarizes older turns
2. Manual compaction: your app triggers it, optionally with custom instructions