Description

This is a split from multiagent session persistent part 2.

• Implement read/write_multiagent_json.
• Rename deserialize function.
• Update origin write function to be atomic write.

For more context, see origin: #900

Overview

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

New APIs Added

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: MultiAgentBase, **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
   |_____ agents/
  └── 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

Integrate with Graph

Can correctly write to session , fire hooks on initializating, node finished, failed. Restore from saved session, start over if completed.

example state json:

{
  "type": "graph",
  "id": "default",
  "status": "executing",
   "failed_nodes": [],
  "completed_nodes": [
    "research"
  ],
  "node_results": {
    "research": {
      "result": {
        "type": "agent_result",
        "message": {
          "role": "assistant",
          "content": [
            {
              "text": "**The Last Letter**\n\nMaria found the yellowed envelope tucked inside her grandmother's old recipe box. Her name was written in shaky handwriting across the front. Inside, a note dated just weeks before Grandma's passing:\n\n\"My dearest Maria, by now you've discovered my secret ingredient wasn't really cinnamon. It was the love I stirred into every batch of cookies, every Sunday dinner, every moment we shared. The recipes are yours now, but remember—the magic isn't in following directions perfectly. It's in cooking with your heart, just like I taught you. Keep our family's love alive in your kitchen. Forever yours, Grandma.\"\n\nMaria smiled through her tears."
            }
          ]
        },
        "stop_reason": "end_turn"
      },
      "execution_time": 9796,
      "status": "completed",
      "accumulated_usage": {
        "inputTokens": 22,
        "outputTokens": 152,
        "totalTokens": 174
      },
      "accumulated_metrics": {
        "latencyMs": 5769
      },
      "execution_count": 1
    }
  },
  "next_nodes_to_execute": [
    "analysis",
    "fact_check"
  ],
  "current_task": "tell me a simple 100 words story",
  "execution_order": [
    "research"
  ]
}

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.