Sessions API

---

FileSessionManager

from elsai.session import FileSessionManager

Persists sessions to the local filesystem.

FileSessionManager(
    session_id="chat-alice",
    storage_dir="./sessions",
)

Parameter	Required	Default	Description
session_id	Yes	—	Session identifier (no path separators)
storage_dir	No	temp dir under elsai/sessions	Directory for session files

---

S3SessionManager

from elsai.session import S3SessionManager

Persists sessions to Amazon S3.

S3SessionManager(
    session_id="chat-alice",
    bucket="my-sessions-bucket",
    prefix="sessions/",
    region_name="us-west-2",
)

Parameter	Required	Default	Description
session_id	Yes	—	Session identifier (no path separators)
bucket	Yes	—	S3 bucket name
prefix	No	""	Key prefix (e.g. "sessions/")
boto_session	No	None	Custom boto3 session
boto_client_config	No	None	Optional boto3 client configuration
region_name	No	None	AWS region for S3

---

RepositorySessionManager

from elsai.session import RepositorySessionManager

Generic session manager backed by a SessionRepository.

RepositorySessionManager(
    session_id="chat-alice",
    session_repository=my_repository,
)

Parameter	Required	Description
session_id	Yes	Session identifier
session_repository	Yes	SessionRepository implementation

---

SessionRepository

from elsai.session import SessionRepository

Abstract base for custom storage backends:

class SessionRepository:
    def create_session(self, session: Session, **kwargs) -> Session: ...
    def read_session(self, session_id: str, **kwargs) -> Session | None: ...
    def create_agent(self, session_id: str, session_agent: SessionAgent, **kwargs) -> None: ...
    def read_agent(self, session_id: str, agent_id: str, **kwargs) -> SessionAgent | None: ...
    def update_agent(self, session_id: str, session_agent: SessionAgent, **kwargs) -> None: ...
    def create_message(
        self, session_id: str, agent_id: str, session_message: SessionMessage, **kwargs
    ) -> None: ...
    def read_message(
        self, session_id: str, agent_id: str, message_id: int, **kwargs
    ) -> SessionMessage | None: ...
    def update_message(
        self, session_id: str, agent_id: str, session_message: SessionMessage, **kwargs
    ) -> None: ...
    def list_messages(
        self, session_id: str, agent_id: str, limit: int | None = None, offset: int = 0, **kwargs
    ) -> list[SessionMessage]: ...

Types Session, SessionAgent, and SessionMessage are imported from elsai.session.

---

Snapshot

from elsai.agent import Snapshot, SnapshotPreset, SnapshotField

An in-memory snapshot of agent state.

SnapshotPreset

Value	Included fields
"session"	messages, state, conversation_manager_state, interrupt_state

SnapshotField

Valid field names: "messages", "state", "conversation_manager_state", "interrupt_state", "system_prompt"

Taking a snapshot

snapshot = agent.take_snapshot(preset="session")
snapshot = agent.take_snapshot(include=["messages", "state"])
snapshot = agent.take_snapshot(preset="session", exclude=["interrupt_state"])
snapshot = agent.take_snapshot(preset="session", app_data={"version": "1.0"})

Restoring from snapshot

agent.load_snapshot(snapshot)

Serialising

import json

# Serialise
snapshot_dict = snapshot.model_dump()
json_str = json.dumps(snapshot_dict)

# Deserialise
from elsai.agent import Snapshot
snapshot = Snapshot(**json.loads(json_str))
agent.load_snapshot(snapshot)

---

Related

• Sessions — file, S3, repository, and A2A session patterns
• A2A sessions — context_id mapping and S3 production backing
• A2A API — A2ASessionStore and session options on A2AServer