今日学到：如何使用 Strands Agents 的内置会话持久化

Source: Dev.to

请提供您想要翻译的完整文本内容，我将把它翻译成简体中文并保持原有的格式、Markdown 语法以及技术术语不变。谢谢！

Overview

Strands Agents SDK 包含一个内置的持久化层用于对话历史。通过将 SessionManager 传递给 Agent 构造函数，所有消息和状态更改都会通过生命周期钩子自动持久化——无需手动调用保存/加载。

示例脚本 (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()

使用 uv 运行脚本：

uv run session_demo.py

# /// 块是 PEP 723 的内联元数据；uv run 会读取它并自动安装依赖，因此无需虚拟环境或手动 pip 安装（只需确保已配置 uv 和 AWS 凭证）。

什么在幕后发生

• agent1 和 agent2 是独立的 Agent 实例；它们不共享内存状态。
• 因为两者使用相同的 session_id，FileSessionManager 在创建 agent2 时会从磁盘恢复对话，使其能够回答 “What did I just ask you?”。
• agent_id 用于标识要保存和恢复的代理状态；在使用会话管理器时是必需的。

会话管理器保存的数据

运行脚本后的磁盘布局

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

示例消息文件（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"
}

用户和助手的轮次交替，依次为 message_0.json → message_3.json。

可用的会话管理器后端

安装与设置

• uv（如果尚未安装）：

  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 凭证（S3SessionManager 或 Bedrock 模型所需）：

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

常见错误与提示

• uv: command not found – 确保已安装 uv 并将其添加到 PATH 中。
• NoCredentialError / Unable to locate credentials – 运行 aws configure 或设置相应的环境变量。
• AccessDeniedException when calling the model – 为您的 IAM 角色/用户授予 bedrock:InvokeModel 和 bedrock:InvokeModelWithResponseStream 权限。
• agent_id is required with a session manager – 若省略会抛出 ValueError: agent_id needs to be defined。系统使用 agent_id 作为目录键，以在同一会话中区分不同代理的状态。
• FileSessionManager defaults to /tmp – 在多数操作系统中，该目录在重启后会被清除。请将 storage_dir 设置为持久化位置（例如 ./sessions 或 .data/sessions）。

进一步阅读

• 会话管理文档
• 对话管理文档