diff --git a/docs/user-guide/concepts/agents/session-management.md b/docs/user-guide/concepts/agents/session-management.md index eefcb6c1..15c7a44e 100644 --- a/docs/user-guide/concepts/agents/session-management.md +++ b/docs/user-guide/concepts/agents/session-management.md @@ -4,18 +4,30 @@ 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 stateful information that is needed by agents and multi-agent systems 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-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. +!!! 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 + Simply create an agent with a session manager and use it: ```python @@ -34,6 +46,31 @@ agent("Hello!") # This conversation is persisted The conversation, and associated state, is persisted to the underlying filesystem. +### Multi-Agent Sessions + +Multi-agent systems(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 graph +session_manager = FileSessionManager(session_id="multi-agent-session") + +# Create graph with session management +graph = Graph( + agents={"researcher": agent1, "writer": agent2}, + session_manager=session_manager +) + +# Use the graph - all orchestrator state is persisted +result = graph("Research and write about AI") +``` + ## Built-in Session Managers Strands offers two built-in session managers for persisting agent sessions: @@ -43,7 +80,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 +97,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 +118,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 +155,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 +172,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 +222,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 +249,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 +279,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-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 +- **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 +353,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