Skip to main content
A session is one persistent agent conversation. agent.session controls a hydrated session, while server.sessions lists and manages both persisted and active sessions.

Imports

Hydrated session

str
The owning agent ID.
AgentTurn | None
The current unfinished turn, if one exists.

snapshot

Returns an immutable copy of the current state, messages, replayable events, and framework-owned timestamps. The agent is started automatically if needed.

replace_messages

Validates, copies, and persists a replacement message history. Raises RuntimeError while a turn is active.

clear_messages

Clears and persists the message history. Existing agent.clear() remains available as a compatibility method.

replay_events

Yields replayable application events after the given event ID.

clear_events

Clears persisted replay events and resets the event counter.

turn

Creates the session’s active turn. A session permits one active turn at a time. agent.turn() delegates to this method.

abort

Aborts the active turn and returns True. Returns False when the session is idle.

Server session catalog

Pass the storage shared by server agents when persisted sessions must be discoverable before hydration:
Without session_storage, active agents still appear. Persisted sessions are discovered from active agents’ storage backends.

list

Returns sessions ordered by most recent update. AgentSessionPage.items is an immutable tuple and total_pages is computed from total and page_size.

get

Returns merged persisted and live metadata without hydrating an inactive agent. AgentSessionInfo includes:
  • id
  • persisted and active
  • copied state
  • message_count and event_count
  • created_at and updated_at
  • live last_activity and connection_count

evict

Removes an active agent from memory while preserving persisted session data. Returns whether an active agent was found.

delete

Evicts an active agent and deletes its state, messages, events, and framework session metadata. Returns whether the session existed.

Existing storage data

Session discovery supports existing {agent_id}:state, {agent_id}:messages, and {agent_id}:event_log records. Legacy records receive a small session manifest when first discovered; no manual migration is required.