Session persistence

[Unshure]

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

• SessionRepository: Repository Interface with create, read, update operations for each of the above new models

• FileSessionManager: A implementation of the SessionRepository and AgentSessionManager 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

• S3SessionManager: Same as the above FileSessionDManager, but stores sessions in S3

Things that will be addressed in follow up pr's:

• Update message after guardrail triggers
• ser/de the conversation manager to persist the previous messages array state.

#246

Documentation PR

TODO:
PR coming, here are some initial docs: https://unshure.github.io/docs/latest/user-guide/concepts/agents/state-sessions/#session-management

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.

[azaylamba]

@Unshure @zastrowm Would this feature be available/merged in near future (coming weeks)? I have a use case of this to persist the context/session of an agent where the agent in deployed in a lambda function. I want to keep the context of the previous invocations of the agent based on session_id.
I am thinking to implement a custom class like DynamoDBConversationManager which would store the conversation in DynamoDB using session_id and can be retrieved/updated across the invocations. Is that a good approach?

[Unshure]

@Unshure @zastrowm Would this feature be available/merged in near future (coming weeks)? I have a use case of this to persist the context/session of an agent where the agent in deployed in a lambda function. I want to keep the context of the previous invocations of the agent based on session_id.
I am thinking to implement a custom class like DynamoDBConversationManager which would store the conversation in DynamoDB using session_id and can be retrieved/updated across the invocations. Is that a good approach?

Hi @azaylamba , planning on getting this feature merged and available by end of this week!

[macsir]

@Unshure @zastrowm Would this feature be available/merged in near future (coming weeks)? I have a use case of this to persist the context/session of an agent where the agent in deployed in a lambda function. I want to keep the context of the previous invocations of the agent based on session_id. I am thinking to implement a custom class like DynamoDBConversationManager which would store the conversation in DynamoDB using session_id and can be retrieved/updated across the invocations. Is that a good approach?

Hi @azaylamba, if it is a long conversation, would it be better to use fargate(ECS) instead of lambda to avoid potential timeout issue?

[azaylamba]

@Unshure @zastrowm Would this feature be available/merged in near future (coming weeks)? I have a use case of this to persist the context/session of an agent where the agent in deployed in a lambda function. I want to keep the context of the previous invocations of the agent based on session_id.
I am thinking to implement a custom class like DynamoDBConversationManager which would store the conversation in DynamoDB using session_id and can be retrieved/updated across the invocations. Is that a good approach?

Hi @azaylamba , planning on getting this feature merged and available by end of this week!

Thanks for the update @Unshure

[azaylamba]

@Unshure @zastrowm Would this feature be available/merged in near future (coming weeks)? I have a use case of this to persist the context/session of an agent where the agent in deployed in a lambda function. I want to keep the context of the previous invocations of the agent based on session_id. I am thinking to implement a custom class like DynamoDBConversationManager which would store the conversation in DynamoDB using session_id and can be retrieved/updated across the invocations. Is that a good approach?

Hi @azaylamba, if it is a long conversation, would it be better to use fargate(ECS) instead of lambda to avoid potential timeout issue?

Hi @macsir , it is not a long conversation and the agent run time won't be long. But the agent should be aware of past interactions and actions, so that those are not repeated (in case action has been already taken by human) and the agent has the historical context.
For the long running tasks/conversations, you are right though and ECS would be a better option.

[zastrowm]

No major blockers - a couple call-outs and questions, but otherwise looks good!

[Unshure]

Latest changes can be viewed here: https://github.com/strands-agents/sdk-python/compare/8b267d21972f72bc0b4cdd59c132c282852dd9ca..0bc4cd0168fbdcfc973d83405abdd1542a6dfa3f