feat: add multiagent session/repository management.

[JackYPCOnline]

Description

This is a split from multiagent session persistent part 2.

• This PR introudce sessionType to session manager.
• Implement read/write_multiagent_json.
• Rename deserialize function.
• Update origin write function to be atomic write.

For more context, see origin: #900

fix import issue:

session_manager.py imports from experimental.hooks.multiagent.events

experimental/__init__.py imports from agent_config.py

agent_config.py imports from agent

agent.py imports from session_manager.py

Overview

This PR extends the session management system to support multi-agent workflows alongside existing single-agent functionality.

New APIs Added

SessionType Enum Extension

• Added SessionType.MULTI_AGENT to distinguish multi-agent sessions from single-agent sessions

SessionRepository Interface

def create_multi_agent(self, session_id: str, multi_agent: MultiAgentBase, **kwargs) -> None
def read_multi_agent(self, session_id: str, multi_agent_id: str, **kwargs) -> Optional[dict[str, Any]]  
def update_multi_agent(self, session_id: str, multi_agent_state: dict[str, Any], **kwargs) -> None

SessionManager Base Class

def sync_multi_agent(self, source: MultiAgentBase, **kwargs) -> None
def initialize_multi_agent(self, source: MultiAgentBase, **kwargs) -> None

Implementation Changes

FileSessionManager

• Directory Structure: Multi-agent sessions create multi_agents/ instead of agents/ directory
• Storage Format: Multi-agent state stored as multi_agent_<id>/multi_agent.json
• File Structure:

  session_<id>/
  ├── session.json
  └── multi_agents/
      └── multi_agent_<multi_agent_id>/
          └── multi_agent.json
  

S3SessionManager

• S3 Key Structure: Multi-agent state stored under multi_agents/multi_agent_<id>/multi_agent.json
• Atomic Operations: Uses S3 put_object for state persistence

RepositorySessionManager

• Hook Integration: Registers multi-agent lifecycle hooks for automatic state persistence
• State Management: Handles serialization/deserialization of multi-agent state

Backward Compatibility

• All existing single-agent APIs remain unchanged
• Default session_type=SessionType.AGENT maintains existing behavior
• No breaking changes to current session management workflows

Related Issues

Documentation PR

Type of Change

Bug fix
New feature
Breaking change
Documentation update
Other (please describe):

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• [ 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
• [ x] I have updated the documentation accordingly
• [ x] 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
• Any dependent changes have been merged and published

---

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

[codecov]

Codecov Report

❌ Patch coverage is 87.17949% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/session/session_manager.py	57.14%	7 Missing and 2 partials ⚠️
src/strands/session/file_session_manager.py	91.11%	2 Missing and 2 partials ⚠️
src/strands/session/s3_session_manager.py	92.00%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[JackYPCOnline]

answer this question: #1071 (comment)

I don't think this is a new issue—it's an aspect we overlooked. Even in the single-agent case, we face this file completeness problem. Talked with Patrick and Dean about this change. We don't perform any validation or defensive checks when reading the session file, ensuring its completeness is crucial.