feat: add multiagent session/repository management. #1071

JackYPCOnline · 2025-10-22T20:18:55Z

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

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

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.

codecov · 2025-10-22T20:22:48Z