TIL: How to Use Strands Agents' Built-In Session Persistence

Source: Dev.to

Overview

The Strands Agents SDK includes a built‑in persistence layer for conversation history. By passing a SessionManager to the Agent constructor, every message and state change is automatically persisted through lifecycle hooks—no manual save/load calls are required.

Example Script (session_demo.py)

# /// script
# requires-python = ">=3.10"
# dependencies = ["strands-agents"]
# ///

from strands import Agent
from strands.session.file_session_manager import FileSessionManager

SESSION_ID = "user-abc-123"
STORAGE_DIR = "./sessions"  # defaults to /tmp/strands/sessions

# First agent instance – ask a question
agent1 = Agent(
    model="global.anthropic.claude-haiku-4-5-20251001-v1:0",
    agent_id="assistant",
    session_manager=FileSessionManager(
        session_id=SESSION_ID, storage_dir=STORAGE_DIR
    ),
)
prompt1 = "What's the capital of France?"
print(f"Prompt: {prompt1}")
agent1(prompt1)
print()

# Second agent instance – same session_id, loads conversation from disk
agent2 = Agent(
    model="global.anthropic.claude-haiku-4-5-20251001-v1:0",
    agent_id="assistant",
    session_manager=FileSessionManager(
        session_id=SESSION_ID, storage_dir=STORAGE_DIR
    ),
)
prompt2 = "What did I just ask you?"
print(f"Prompt: {prompt2}")
agent2(prompt2)
print()

Run the script with uv:

uv run session_demo.py

The # /// block is PEP 723 inline metadata; uv run reads it to install dependencies automatically, so you don’t need a virtual environment or manual pip installs (just have uv and AWS credentials configured).

What Happens Under the Hood

• agent1 and agent2 are separate Agent instances; they share no in‑memory state.
• Because both use the same session_id, FileSessionManager restores the conversation from disk when agent2 is created, allowing it to answer “What did I just ask you?”.
• agent_id identifies which agent’s state to save and restore; it is required when using a session manager.

Data Saved by the Session Manager

On‑Disk Layout After Running the Script

sessions/
└── session_user-abc-123
    ├── agents
    │   └── agent_assistant
    │       ├── agent.json
    │       └── messages
    │           ├── message_0.json
    │           ├── message_1.json
    │           ├── message_2.json
    │           └── message_3.json
    ├── multi_agents
    └── session.json

Example Message File (message_0.json)

{
  "message": {
    "role": "user",
    "content": [
      {
        "text": "What's the capital of France?"
      }
    ]
  },
  "message_id": 0,
  "created_at": "2026-02-17T14:45:31.439081+00:00"
}

User and assistant turns alternate through message_0.json → message_3.json.

Available Session Manager Backends

Installation & Setup

• uv (if not already installed):

  curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS/Linux
  # or on Windows:
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

• AWS credentials (required for S3SessionManager or Bedrock models):

  aws configure
  # or set environment variables:
  export AWS_ACCESS_KEY_ID=...
  export AWS_SECRET_ACCESS_KEY=...

Common Errors & Tips

• uv: command not found – ensure uv is installed and added to your PATH.
• NoCredentialError / Unable to locate credentials – run aws configure or set the appropriate environment variables.
• AccessDeniedException when calling the model – grant bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream permissions to your IAM role/user.
• agent_id is required with a session manager – omitting it raises ValueError: agent_id needs to be defined. The system uses agent_id as a directory key to separate state for different agents within the same session.
• FileSessionManager defaults to /tmp – on many OSes this directory is cleared on reboot. Set storage_dir to a persistent location (e.g., ./sessions or .data/sessions).

Further Reading

• Session Management Documentation
• Conversation Management Documentation