feat: Enable multiagent session persistent in Graph/Swarm #1110

JackYPCOnline · 2025-10-29T22:12:56Z

Description

This PR introduces session persistence capabilities to the MultiAgent framework, allowing both Graph and Swarm to save and restore their execution state across sessions.

Key Changes

Core Features Added

Session Management Integration: Both Graph and Swarm now support SessionManager for state persistence
Hook System Integration: Added comprehensive hook support for monitoring and extending execution behavior
State Serialization/Deserialization: Complete state save/restore functionality for resuming interrupted executions

Graph Multi-Agent Enhancements

New Configuration Options

session_manager: Optional SessionManager for state persistence
hooks: List of HookProvider instances for execution monitoring
id: Unique graph identifier (defaults to "default_graph")

State Management

Serialization: Captures current execution state including:
- Completed and failed nodes
- Node execution results
- Next nodes to execute
- Current task and execution order
Deserialization: Restores state and resumes from interruption point
Smart Resume Logic: Automatically determines next ready nodes based on dependencies

Hook Integration

MultiAgentInitializedEvent: Fired when graph is initialized
AfterNodeCallEvent: Fired after each node execution
AfterMultiAgentInvocationEvent: Fired when graph execution completes

Swarm Multi-Agent Enhancements

New Configuration Options

session_manager: Optional SessionManager for state persistence
hooks: List of HookProvider instances for execution monitoring
id: Unique swarm identifier (defaults to "default_swarm")

State Management

Serialization: Captures swarm execution state including:
- Node execution history
- Current active node
- Shared context and handoff messages
- Node results
Deserialization: Restores swarm state and resumes from current node
Context Preservation: Maintains shared context across session boundaries

Implementation Details

Session Persistence Flow

Initialization: Hook providers (including SessionManager) are registered
Execution: State changes trigger hook callbacks for persistence
Interruption: Current state is automatically saved via hooks
Resume: State is restored and execution continues from interruption point

Backward Compatibility

All new parameters are optional with sensible defaults
Existing code continues to work without modification
No breaking changes to public APIs

Example:

def build_graph(sm: FileSessionManager):
    # Create specialized agents
    researcher = Agent(name="researcher", system_prompt="You are a research specialist...")
    # if individual agent's session manager exists, we may want to check the hash of the individual agent's session so we can
    # validate / invalidate the graph's session persistence, if nothing is changed, keep the graph settings,
    # if something changed in individual agent, we may want to invalidate cache, but this can be an option
    #
    analyst = Agent(name="analyst", system_prompt="You are a data analysis specialist...")
    # beside that system prompt might change
    fact_checker = Agent(name="fact_checker", system_prompt="You are a fact checking specialist...")
    report_writer = Agent(name="report_writer", system_prompt="You are a report writing specialist...")
    refine_writer = Agent(name="refine_writer", system_prompt="You are a report refining specialist...")
    # Build the graph
    builder = GraphBuilder()

    # Add nodes
    builder.add_node(researcher, "research")
    builder.add_node(analyst, "analysis")
    builder.add_node(fact_checker, "fact_check")
    builder.add_node(report_writer, "report")
    builder.add_node(refine_writer, "refine")

    # Add edges (dependencies)
    builder.add_edge("research", "analysis")
    builder.add_edge("research", "fact_check")
    builder.add_edge("analysis", "report")
    builder.add_edge("fact_check", "report")
    builder.add_edge("report", "refine")

    # Set entry points (optional - will be auto-detected if not specified)
    builder.set_entry_point("research")

    # Optional: Configure execution limits for safety
    builder.set_execution_timeout(600)  # 10 minute timeout

    # Set session manager on builder
    builder.set_session_manager(sm)

    # Build the graph
    graph = builder.build()

    return graph

session_id = "personal"  # your stable id
    dir = "/Volumes/workplace/Strands/personal/sessions"

    sm = FileSessionManager(session_id=session_id, storage_dir=dir)
    graph = build_graph(sm)
    task = "tell me a simple 100 words story"
    result = graph(task)

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
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
[x ] 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-29T22:14:14Z