Session persistence #302

Unshure · 2025-06-27T14:05:39Z

Description

This PR introduces a SessionManagement class to the Strands SDK that is in charge of persisting an agent to some datastore, and re-initializing the agent. The SessionManagement feature set includes:

Introduces an agent id attribute used as a unique id for differentiating agents
SessionManager: Interface for SessionManagers. This interface introduces a append_message_to_agent_session method that is called in the Agent class when adding a message to the agent messages array, as well as an initialize_agent class for initializing an agent
AgentSessionManager: Implementation of the above interface for persisting a single agent to some datastore. This will also re-initialize the agent's messages and state.
Session models: Three new models to represent different data types for session persistence:
- Session: The overarching container to represent a strands agent, and in the future, multi-agent systems. One session can have many agents
- SessionAgent: A persisted version of an agent, storing the agents state and messages
- SessionMessage: A persisted version of a message
SessionDAO: DAO Interface with CRUDL operations for each of the above new models
FileSessionDAO: A implementation of the SessionDAO for storing a session in the local file system. This introduces the following directory and file structure to represent a Session:
- <storage_dir>/session_<session_id>/
  - session.json # Stores session related data
  - agents/agent_<agent_id>/
    - agent.json # Stores agent related data
    - messages/messages_<message_id>.json # Stores message content
S3SessionDAO: Same as the above FileSessionDAO, but stores sessions in S3

Things that still need to be addressed:

all unit tests are vibe-coded, need to do a more thorough review
Integ tests
Update message after guardrail triggers
Order event files
Review docstrings (some seem to be out of date)
Add tests for EventLoopMetric ser/de
Respect created_at time for DAO Update methods

Changes for a follow-up pr:

Support ConversationManager refreshing (SummarizationConversationManager)

#246

Documentation PR

TODO:

Type of Change

New feature

Testing

How have you tested the change?

Vibecoded unit tests and local testing
Still needs:
- Thorough review of unit tests
- Integration tests

• [x] I ran hatch run prepare

Checklist

• [x] I have read the CONTRIBUTING document
• [x] I have added any necessary tests that prove my fix is effective or my feature works
• [ ] I have updated the documentation accordingly
• [ ] I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• [x] My changes generate no new warnings
• [x] Any dependent changes have been merged and published

Additional Notes:
N/A

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

Unshure · 2025-06-27T18:02:41Z

src/strands/session/session_models.py

+    AGENT = "AGENT"
+
+
+@dataclass


Will likely convert these to TypedDict classes. The main reason I had dataclass was for the lambda default_factory, but this introduces more complexity than its worth.

zastrowm · 2025-07-02T13:27:12Z

src/strands/session/agent_session_manager.py

+    from ..agent.agent import Agent
+
+
+class AgentSessionManager(SessionManager):


This name seems so abstract IMHO. I feel like this should be FileSessionManager or something that indicates that it's file based

I wanted this to represent a single agent session manager. Since we eventually want to support multi-agent session managers, I figured we might have a GraphSessionManager or SwarmSessionManager in the future as well.

zastrowm · 2025-07-02T13:30:18Z

src/strands/session/session_manager.py

+    """
+
+    @abstractmethod
+    def append_message_to_agent_session(self, agent: "Agent", message: Message) -> None:


This seems verbose compared to many of our apis is there a need to specify agent_session here?

I'd suggest append_message

zastrowm · 2025-07-02T13:30:56Z

src/strands/session/session_manager.py

+        raise NotImplementedError("Subclasses must implement update_session")
+
+    @abstractmethod
+    def initialize_agent(self, agent: "Agent") -> None:


I'd also suggest just initialize; I'm not entirely convinced we need to repeat agent?

zastrowm · 2025-07-02T13:44:45Z

src/strands/session/agent_session_manager.py

+            agent: The agent whose session to update
+            message: The message to append
+        """
+        if agent.id is None:


I wonder if we should just default a value (like "default")

My concern is that someone just trying to persist a single agent now needs to add both the session_manager and set an id. So someone persisting a personal agent now has more steps?

Not a blocker though

I guess this would work by checking if there is only one agent in the session, that agent is given a generated id. Then when it is re-initialized, the id will be set? I like that

👍

oh, that's better than what I was thinking, because I didn't handle the edge case of "you have multiple sessions on file but the agent has no id set"

zastrowm · 2025-07-02T14:21:49Z

src/strands/session/session_dao.py

+from .session_models import Session, SessionAgent, SessionMessage
+
+
+class SessionDAO(ABC):


How many of the methods on here are actually used within the SessionManager? My concern is that we're adding implementations of things that are potentially useful from the standpoint of callers, but not necessary for the manager. I think I'd rather keep the api surface smaller until we have alignment that the apis are the right ones

Similarly, I wonder if we need the DAO. I'm curious, for something like a provider that wanted to do more than just storing/loading messages? Say if they wanted to affect the prompt or something - would they be implementing a DAO or a SessionManager or both? Do we need both?

I went back and forth on this one a bit.

The general request for this feature is some built-in way to persist and re-initialize an agent as it runs. The interface for a SessionManager should be super basic to support any kind of implementation that may come up.

If we also want to include some implementation of how to actually persist and retrieve an agent, I think a DAO makes sense for that. I included a pretty basic data model to represent agents, messages, and some wrapper around many agents which i'm calling a Session. I imagine if customers wants to build on top of the persistence we have build in, we should probably implement a basic CRUDL api for it. interested in hearing your thoughts.

One aspect that I'm hung up on is the size of the DAO - 15 methods to implement a new backend was more than I was expecting - but is that perhaps because of the intrinsic complexity?

The other aspect is the distinction between the DAO and the SessionManager, and so I'm interested in the eventual full usage. This makes sense to me:

sessions = S3SessionManager() agent = Agent(sessions=sessions, id='default')

while this seems to be a bit less ergonomic:

sessions = SessionManager(dao=S3Dao()) agent = Agent(sessions=sessions, id='default')

zastrowm · 2025-07-02T14:42:42Z

src/strands/session/exceptions.py

+"""Exception classes for session management operations."""
+
+
+class SessionException(Exception):


I think we have one file for all exceptions in src/strands/types/exceptions.py

zastrowm · 2025-07-02T15:02:53Z

src/strands/session/session_models.py

+
+
+@dataclass
+class SessionMessage:


Food for thought?: Have we considered having this in the SDK directly in its implementation of Message and we just strip them when we send it to the providers?

If this is only important for the session persistence, I would probably keep is separated. If we find another usecase for it though, I would be fine with your suggestion.

zastrowm · 2025-07-02T15:04:12Z

src/strands/session/session_models.py

+
+@dataclass
+class SessionAgent:
+    """Agent within a session with lazy message loading."""


Where does the lazy-loading come in to play?

Would this be more clear as AgentMetadata?

Old vibecoded docstring. This can be removed

zastrowm · 2025-07-02T15:05:33Z

src/strands/session/agent_session_manager.py

+
+        except SessionException:
+            # Session doesn't exist, create new one
+            logger.debug("Session not found, creating new session")


Probably best to log the session-id here

zastrowm · 2025-07-02T15:07:37Z

src/strands/agent/agent.py

Could you add an example usage of what it looks like when using a session with an agent, from the caller's perspective?

Yes, ill add an integration test

Unshure temporarily deployed to auto-approve June 27, 2025 14:05 — with GitHub Actions Inactive

ryanycoleman added this to Strands Agents Roadmap Jun 27, 2025

ryanycoleman moved this to We're Working On It in Strands Agents Roadmap Jun 27, 2025

Unshure commented Jun 27, 2025

View reviewed changes

Unshure force-pushed the session-persistence branch from d62b09b to 74d7ed6 Compare July 1, 2025 14:48

Unshure had a problem deploying to auto-approve July 1, 2025 14:48 — with GitHub Actions Failure

feat: Session persistence

3b81f1b

Unshure force-pushed the session-persistence branch from 74d7ed6 to 3b81f1b Compare July 1, 2025 14:49

Unshure temporarily deployed to auto-approve July 1, 2025 14:50 — with GitHub Actions Inactive

zastrowm reviewed Jul 2, 2025

View reviewed changes

		from ..agent.agent import Agent


		class AgentSessionManager(SessionManager):

		from .session_models import Session, SessionAgent, SessionMessage


		class SessionDAO(ABC):

		"""Exception classes for session management operations."""


		class SessionException(Exception):

Session persistence #302

Are you sure you want to change the base?

Session persistence #302

Uh oh!

Conversation

Unshure commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Things that still need to be addressed:

Changes for a follow-up pr:

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zastrowm Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Unshure Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Unshure commented Jun 27, 2025 •

edited

Loading

zastrowm Jul 2, 2025 •

edited

Loading

Unshure Jul 2, 2025 •

edited

Loading