TIL: Strands Agents의 내장 세션 지속성 사용 방법

I’m happy to translate the article for you, but I don’t have access to the content at the linked URL. Could you please paste the text you’d like translated here? Once you provide the article’s content, I’ll translate it into Korean while preserving the original formatting, markdown, and code blocks.

개요

Strands Agents SDK는 대화 기록을 위한 내장 영속성 레이어를 포함하고 있습니다. Agent 생성자에 SessionManager를 전달하면, 모든 메시지와 상태 변경이 라이프사이클 훅을 통해 자동으로 영속화됩니다—수동으로 저장/로드 호출을 할 필요가 없습니다.

예제 스크립트 (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를 사용하기 때문에, agent2가 생성될 때 FileSessionManager가 디스크에서 대화를 복원하여 “방금 뭐라고 물었지?” 라는 질문에 답할 수 있게 됩니다.
• 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 – 많은 OS에서 이 디렉터리는 재부팅 시 삭제됩니다. storage_dir를 영구적인 위치(예: ./sessions 또는 .data/sessions)로 설정하세요.

추가 읽을거리

• 세션 관리 문서
• 대화 관리 문서