From 0fecb682ca41d528bb85dbd001c7ddb636c8204b Mon Sep 17 00:00:00 2001 From: Jack Yuan Date: Thu, 30 Oct 2025 17:51:15 -0400 Subject: [PATCH 1/3] feat: include multi-agent session management to current --- .../concepts/agents/session-management.md | 108 +++++++++++++++--- 1 file changed, 91 insertions(+), 17 deletions(-) diff --git a/docs/user-guide/concepts/agents/session-management.md b/docs/user-guide/concepts/agents/session-management.md index cfdd07b5..eaf45bc7 100644 --- a/docs/user-guide/concepts/agents/session-management.md +++ b/docs/user-guide/concepts/agents/session-management.md @@ -4,18 +4,27 @@ Session management in Strands Agents provides a robust mechanism for persisting ## Overview -A session represents all of the stateful information that is needed by an agent to function, including: +A session represents all of the stateful information that is needed by agents and multi-agents to function, including: +**Single Agent Sessions**: - Conversation history (messages) - Agent state (key-value storage) - Other stateful information (like [Conversation Manager](./state.md#conversation-manager)) -Strands provides built-in session persistence capabilities that automatically capture and restore this information, allowing agents to seamlessly continue conversations where they left off. +**Multi-Agent Sessions**: +- Orchestrator state and configuration +- Individual agent states and result within the orchestrator +- Cross-agent shared state and context +- Execution flow and node transition history + +Strands provides built-in session persistence capabilities that automatically capture and restore this information, allowing agents and multi-agents to seamlessly continue conversations where they left off. Beyond the built-in options, [third-party session managers](./#third-party-session-managers) provide additional storage and memory capabilities. ## Basic Usage +### Single Agent Sessions + Simply create an agent with a session manager and use it: ```python @@ -34,6 +43,31 @@ agent("Hello!") # This conversation is persisted The conversation, and associated state, is persisted to the underlying filesystem. +### Multi-Agent Sessions + +Multi-agents(Graph/Swarm) can also use session management to persist their state: + +```python +from strands.multiagent import Graph +from strands.session.file_session_manager import FileSessionManager + +# Create agents +agent1 = Agent(name="researcher") +agent2 = Agent(name="writer") + +# Create a session manager for the orchestrator +session_manager = FileSessionManager(session_id="multi-agent-session") + +# Create orchestrator with session management +orchestrator = Graph( + agents={"researcher": agent1, "writer": agent2}, + session_manager=session_manager +) + +# Use the orchestrator - all orchestrator state is persisted +result = orchestrator("Research and write about AI") +``` + ## Built-in Session Managers Strands offers two built-in session managers for persisting agent sessions: @@ -43,7 +77,7 @@ Strands offers two built-in session managers for persisting agent sessions: ### FileSessionManager -The [`FileSessionManager`](../../../api-reference/session.md#strands.session.file_session_manager.FileSessionManager) provides a simple way to persist agent sessions to the local filesystem: +The [`FileSessionManager`](../../../api-reference/session.md#strands.session.file_session_manager.FileSessionManager) provides a simple way to persist both single agent and multi-agent sessions to the local filesystem: ```python from strands import Agent @@ -60,6 +94,17 @@ agent = Agent(session_manager=session_manager) # Use the agent normally - state and messages will be persisted automatically agent("Hello, I'm a new user!") + +# Multi-agent usage +multi_session_manager = FileSessionManager( + session_id="orchestrator-456", + storage_dir="/path/to/sessions" +) +graph = Graph( + agents={"agent1": agent1, "agent2": agent2}, + session_manager=multi_session_manager +) + ``` #### File Storage Structure @@ -70,12 +115,15 @@ When using [`FileSessionManager`](../../../api-reference/session.md#strands.sess // └── session_/ ├── session.json # Session metadata - └── agents/ - └── agent_/ - ├── agent.json # Agent metadata and state - └── messages/ - ├── message_.json - └── message_.json + ├── agents/ # Single agent storage + │ └── agent_/ + │ ├── agent.json # Agent metadata and state + │ └── messages/ + │ ├── message_.json + │ └── message_.json + └── multi_agents/ # Multi-agent storage + └── multi_agent_/ + └── multi_agent.json # Orchestrator state and configuration ``` ### S3SessionManager @@ -104,6 +152,14 @@ agent = Agent(session_manager=session_manager) # Use the agent normally - state and messages will be persisted to S3 agent("Tell me about AWS S3") + +# Use with multi-agent orchestrator +swarm = Swarm( + agents=[agent1, agent2, agent3], + session_manager=session_manager +) + +result = swarm("Coordinate the task across agents") ``` #### S3 Storage Structure @@ -113,12 +169,15 @@ Just like in the [`FileSessionManager`](../../../api-reference/session.md#strand / └── session_/ ├── session.json # Session metadata - └── agents/ - └── agent_/ - ├── agent.json # Agent metadata and state - └── messages/ - ├── message_.json - └── message_.json + ├── agents/ # Single agent storage + │ └── agent_/ + │ ├── agent.json # Agent metadata and state + │ └── messages/ + │ ├── message_.json + │ └── message_.json + └── multi_agents/ # Multi-agent storage + └── multi_agent_/ + └── multi_agent.json # Orchestrator state and configuration ``` #### Required S3 Permissions @@ -160,13 +219,19 @@ The session management system in Strands Agents works through a combination of e ### 1. Session Persistence Triggers -Session persistence is automatically triggered by several key events in the agent lifecycle: +Session persistence is automatically triggered by several key events in the agent and multi-agent lifecycle: +**Single Agent Events** - **Agent Initialization**: When an agent is created with a session manager, it automatically restores any existing state and messages from the session. - **Message Addition**: When a new message is added to the conversation, it's automatically persisted to the session. - **Agent Invocation**: After each agent invocation, the agent state is synchronized with the session to capture any updates. - **Message Redaction**: When sensitive information needs to be redacted, the session manager can replace the original message with a redacted version while maintaining conversation flow. +**Multi-Agent Events:** +- **Multi-Agent Initialization**: When an orchestrator is created with a session manager, it automatically restores state from the session. +- **Node Execution**: After each node invocation, synchronizes orchestrator state after node transitions +- **Multi-Agent Invocation**: After multiagent finished, captures final orchestrator state after execution + !!! warning "After initializing the agent, direct modifications to `agent.messages` will not be persisted. Utilize the [Conversation Manager](./conversation-management.md) to help manage context of the agent in a way that can be persisted." @@ -181,7 +246,7 @@ The [`Session`](../../../api-reference/types.md#strands.types.session.Session) m - **Purpose**: Provides a namespace for organizing multiple agents and their interactions - **Key Fields**: - `session_id`: Unique identifier for the session - - `session_type`: Type of session (currently "AGENT") + - `session_type`: Type of session (currently "AGENT" for both agent & multiagent in order to keep backward compatibility) - `created_at`: ISO format timestamp of when the session was created - `updated_at`: ISO format timestamp of when the session was last updated @@ -211,6 +276,14 @@ The [`SessionMessage`](../../../api-reference/types.md#strands.types.session.Ses These data models work together to provide a complete representation of an agent's state and conversation history. The session management system handles serialization and deserialization of these models, including special handling for binary data using base64 encoding. +**Multi-Agent State** + +Multi-agents serialize their state as JSON objects containing: + +- **Orchestrator Configuration**: Settings, parameters, and execution preferences +- **Node State**: Current execution state and node transition history +- **Shared Context**: Cross-agent shared state and variables + ## Third-Party Session Managers The following third-party session managers extend Strands with additional storage and memory capabilities: @@ -277,3 +350,4 @@ When implementing session persistence in your applications, consider these best - **Understand Persistence Triggers**: Remember that changes to agent state or messages are only persisted during specific lifecycle events +- **Concurrent Access**: Session managers are not thread-safe; use appropriate locking for concurrent access \ No newline at end of file From 7c463982d500492aebcf8660f937be1d830e6b20 Mon Sep 17 00:00:00 2001 From: Jack Yuan Date: Mon, 3 Nov 2025 12:23:56 -0500 Subject: [PATCH 2/3] fix: rename multi-agents to multi-agent systems --- docs/user-guide/concepts/agents/session-management.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/concepts/agents/session-management.md b/docs/user-guide/concepts/agents/session-management.md index 1263bec3..559e68fe 100644 --- a/docs/user-guide/concepts/agents/session-management.md +++ b/docs/user-guide/concepts/agents/session-management.md @@ -4,7 +4,7 @@ Session management in Strands Agents provides a robust mechanism for persisting ## Overview -A session represents all of the stateful information that is needed by agents and multi-agents to function, including: +A session represents all of stateful information that is needed by agents and multi-agent systems to function, including: **Single Agent Sessions**: - Conversation history (messages) @@ -17,7 +17,7 @@ A session represents all of the stateful information that is needed by agents an - Cross-agent shared state and context - Execution flow and node transition history -Strands provides built-in session persistence capabilities that automatically capture and restore this information, allowing agents and multi-agents to seamlessly continue conversations where they left off. +Strands provides built-in session persistence capabilities that automatically capture and restore this information, allowing agents and multi-agent systems to seamlessly continue conversations where they left off. Beyond the built-in options, [third-party session managers](#third-party-session-managers) provide additional storage and memory capabilities. @@ -45,7 +45,7 @@ The conversation, and associated state, is persisted to the underlying filesyste ### Multi-Agent Sessions -Multi-agents(Graph/Swarm) can also use session management to persist their state: +Multi-agent systems(Graph/Swarm) can also use session management to persist their state: ```python from strands.multiagent import Graph @@ -278,7 +278,7 @@ These data models work together to provide a complete representation of an agent **Multi-Agent State** -Multi-agents serialize their state as JSON objects containing: +Multi-agent systems serialize their state as JSON objects containing: - **Orchestrator Configuration**: Settings, parameters, and execution preferences - **Node State**: Current execution state and node transition history From 86a745b28455821c434ac6dd93cf9e27ca276e5b Mon Sep 17 00:00:00 2001 From: Jack Yuan Date: Wed, 5 Nov 2025 11:54:09 -0500 Subject: [PATCH 3/3] fix: add a warning to avoid mix usage of session manager in multiagent systems --- .../concepts/agents/session-management.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/concepts/agents/session-management.md b/docs/user-guide/concepts/agents/session-management.md index 559e68fe..15c7a44e 100644 --- a/docs/user-guide/concepts/agents/session-management.md +++ b/docs/user-guide/concepts/agents/session-management.md @@ -21,6 +21,9 @@ Strands provides built-in session persistence capabilities that automatically ca Beyond the built-in options, [third-party session managers](#third-party-session-managers) provide additional storage and memory capabilities. +!!! warning + You cannot use a single agent with session manager in a multi-agent system. This will throw an exception. Each agent in a multi-agent system must be created without a session manager, and only the orchestrator should have the session manager. Additionally, multi-agent session managers only track the current state of the Graph/Swarm execution and do not persist individual agent conversation histories. + ## Basic Usage ### Single Agent Sessions @@ -55,17 +58,17 @@ from strands.session.file_session_manager import FileSessionManager agent1 = Agent(name="researcher") agent2 = Agent(name="writer") -# Create a session manager for the orchestrator +# Create a session manager for the graph session_manager = FileSessionManager(session_id="multi-agent-session") -# Create orchestrator with session management -orchestrator = Graph( +# Create graph with session management +graph = Graph( agents={"researcher": agent1, "writer": agent2}, session_manager=session_manager ) -# Use the orchestrator - all orchestrator state is persisted -result = orchestrator("Research and write about AI") +# Use the graph - all orchestrator state is persisted +result = graph("Research and write about AI") ``` ## Built-in Session Managers