feat: Enable multiagent session persistent in Graph/Swarm

[JackYPCOnline]

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

1. Initialization: Hook providers (including SessionManager) are registered
2. Execution: State changes trigger hook callbacks for persistence
3. Interruption: Current state is automatically saved via hooks
4. 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]

Codecov Report

❌ Patch coverage is 70.66667% with 44 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/multiagent/graph.py	72.09%	21 Missing and 3 partials ⚠️
src/strands/multiagent/swarm.py	68.75%	17 Missing and 3 partials ⚠️

📢 Thoughts on this report? Let us know!