🎯 Strands 상태 관리

에이전트 대화의 구조 — 턴 · 세션 · 기억

메시지가 모여 턴, 턴이 모여 세션 — 그리고 그 전부를 기억하는 곳

기억의 실체 — messages[]

모델은 아무것도 기억하지 않음 — 매 턴, 지금까지의 대화 전체를 재전송

상태가 없으면 생기는 세 가지 문제

인메모리 messages[]를 그대로 프로덕션에 두면 생기는 문제

네 가지 이름의 실체

저장·길이·기억·조립 — 각 이름이 Strands에서 실제로 가리키는 것

4계층 지도 — 쌓아가는 선택

워크로드가 복잡해질수록 아래부터 하나씩 쌓이는 계층

모델 입력이 되기까지 — Context 조립 라인

네 계층이 각자의 기여물을 꽂아 넣는, 매 호출 새로 조립되는 Context

SessionManager

세션 영속화 계층 — Agent에 장착하면 저장과 복원이 자동

세션 라이프사이클

명시적으로 열고 닫지 않는 세션 — 상태 사이를 오가는 저장·복원·소멸의 흐름

SessionManager 백엔드

세션 데이터를 어디에 저장할지 선택 — 환경에 맞는 백엔드

세션 저장과 복원

session_id 하나로 전체 대화 상태를 영속화·복원

핵심 포인트

session_manager=

장착 한 줄로 저장·복원 자동 — save()를 호출하지 않음

session_id

복원 키 — 같은 ID로 Agent를 다시 만들면 이전 대화가 그대로

저장 시점

매 턴 자동 — messages[]와 agent.state가 함께 영속화

S3 백엔드

파일시스템 없는 Lambda·Fargate에서도 세션 유지

코드

from strands import Agent
from strands.session import S3SessionManager

# 세션 매니저 — session_id + S3 버킷으로 저장 위치 지정
session_mgr = S3SessionManager(
    session_id="user-123-chat-1",
    bucket="agent-sessions-bucket",
)
agent = Agent(session_manager=session_mgr)
agent("내 AWS 비용을 분석해줘")

# 나중에 — 같은 session_id로 재생성하면 이전 대화 자동 로드
agent2 = Agent(session_manager=S3SessionManager(
    session_id="user-123-chat-1",
    bucket="agent-sessions-bucket",
))
agent2("아까 분석한 결과에서 가장 비싼 서비스는?")

messages[] 밖의 상태 — agent.state

모델에게는 보이지 않지만, 세션과 함께 저장되는 key-value 상태

핵심 포인트

agent.state

대화 밖 key-value 저장소 — 모델 컨텍스트에 전송되지 않음

set / get

카운터·플래그·사용자 메타데이터를 코드에서 직접 읽고 씀

영속화

SessionManager가 messages[]와 함께 저장·복원

용도

요금제·호출 횟수·중간 결과처럼 모델이 몰라도 되는 값

코드

from strands import Agent
from strands.session import FileSessionManager

agent = Agent(
    session_manager=FileSessionManager(session_id="user-123"),
)

# 모델 컨텍스트에 들어가지 않는 key-value 상태
agent.state.set("user_tier", "premium")
agent.state.set("api_calls", 3)
print(agent.state.get("user_tier"))  # "premium"

# 세션 저장소에 messages[]와 함께 영속화 — 재생성해도 유지
agent2 = Agent(
    session_manager=FileSessionManager(session_id="user-123"),
)
print(agent2.state.get("api_calls"))  # 3

세션 격리와 보안

멀티테넌트 환경에서 세션 간 데이터 유출 방지

ConversationManager

대화 길이 관리 계층 — 모델에 보낼 messages[] 분량을 정책으로 결정

SlidingWindow vs Summarizing

대화 이력을 얼마나, 어떻게 보존할지 — 속성 대비와 설정 코드

세 전략의 선택 기준

Null까지 포함한 세 전략 — 워크로드 특성이 가르는 갈림길

MemoryManager

장기 기억 계층 — 세션이 끝나도 남는 사실과 선호를 축적

MemoryManager 기억 사이클

추출·저장은 쓰기, 검색·주입은 읽기 — 네 단계 모두 자동, 개발자는 스토어만 연결

Memory 구현

MemoryManager 설정으로 장기 기억 활성화

핵심 포인트

BedrockKnowledgeBaseStore

장기 기억 저장소 — knowledge_base_id로 연결

MemoryManager(stores=)

스토어 리스트 장착 — 검색·추출·주입이 자동

쓰기

대화에서 기억할 사실을 추출해 스토어에 기록

읽기

질문과 관련된 기억만 recall해 컨텍스트에 주입

코드

from strands import Agent
from strands.memory import MemoryManager
from strands.vended_memory_stores import BedrockKnowledgeBaseStore

# 스토어 — Bedrock Knowledge Base를 장기 기억 저장소로
store = BedrockKnowledgeBaseStore(
    config={"knowledge_base_id": "KB12345678"},
    name="user-memory",
)

# 매니저 장착 — 검색·추출·주입 자동
agent = Agent(memory_manager=MemoryManager(stores=[store]))

# 첫 대화 — 기억 추출 + 저장
agent("나는 Python과 us-east-1 리전을 선호해")

# 나중 대화 — 자동 recall + injection
agent("새 Lambda 함수를 만들어줘")  # Python + us-east-1 자동 적용

Memory 활용 패턴

장기 기억으로 에이전트의 개인화 수준을 높이는 3가지 패턴

Context Management

매 호출의 모델 입력을 한도 안에 지키는 자동 방어, 그리고 실행을 멈췄다 이어가는 제어

지키기 vs 멈추기

지키기 = 컨텍스트가 한도를 넘지 않게 유지 · 멈추기 = 실행을 멈췄다 다시 잇는 재개

context_manager 자동 방어

지키기 ① — 한도 접근 감지 시 선제 요약 + 대용량 도구 결과 오프로딩 개입

1. 1
   임계치 감지

   현재 컨텍스트 토큰 수가 모델 한도의 85%를 초과하면 자동 트리거.

2. 2
   선제 요약

   오래된 대화를 LLM이 요약으로 압축. 핵심 정보(결정, 사실, 작업 상태)를 보존.

3. 3
   오프로딩·재요약

   대용량 도구 결과는 ContextOffloader가 스토리지로 오프로드. 요약 후에도 초과가 지속되면 반응적으로 재요약.

4. 4
   모델 호출

   압축된 컨텍스트로 정상 추론 진행. 사용자에게 투명하게 동작.

None

기본값 — 자동 개입 없음, ConversationManager 정책만 동작

'auto'

요약 + 오프로딩을 자동 적용 — 대부분의 프로덕션 권장

'agentic'

모델이 스스로 압축·오프로딩 시점을 판단 (토큰↔정확도 트레이드오프)

큰 도구 결과는 밖으로 — ContextOffloader

지키기 ② — "큰 도구 결과도 매번 다시 전송"되는 비용을 오프로딩으로 차단

핵심 포인트

max_result_tokens

이 크기를 넘는 도구 결과를 외부 저장소로 이동 (기본 2500)

preview_tokens

컨텍스트에는 미리보기만 남김 (기본 1000)

storage

InMemory · File · S3 저장소 선택

Unified Storage

스토리지 백엔드 통합 인터페이스 — 오프로더 저장소에 자동 네임스페이스(auto-namespace) 적용

retrieve_offloaded_content

원본이 필요하면 자동 등록된 도구로 에이전트가 직접 조회

코드

from strands import Agent
from strands.vended_plugins.context_offloader.plugin import ContextOffloader
from strands.vended_plugins.context_offloader.storage import S3Storage

# 2500토큰 초과 도구 결과를 S3로 — 컨텍스트에는 미리보기만
agent = Agent(
    model="us.anthropic.claude-sonnet-4-6",
    plugins=[ContextOffloader(
        max_result_tokens=2500,
        preview_tokens=1000,
        storage=S3Storage(bucket="ctx-offload"),
    )],
)

# 원본이 필요하면 retrieve_offloaded_content 도구로 자동 조회

지키기 두 도구의 분담 — context_manager + ContextOffloader

고르는 것이 아니라 함께 켜는 조합 — 지키는 대상이 다름

멈추기 두 방식 — Checkpoint vs Interrupts

둘 다 "멈췄다 이어가기" — 차이는 멈추는 주체와 이유

Checkpoint — 일시 정지와 재개

멈추기 ① — 도구 사이클 경계에서 멈췄다가 이어서 재개 (experimental, 상태 캡처는 take_snapshot()이 별도)

핵심 포인트

checkpointing=True

체크포인트 활성화 — experimental 기능

stop_reason="checkpoint"

도구 사이클 경계에서 일시 정지하며 반환

to_dict / from_dict

직렬화해 외부 저장소에 보관, checkpointResume로 재개

주의

대화 이력은 캡처하지 않음 — 영속화는 SessionManager 병행

코드

from strands import Agent

# 체크포인트 활성화 — tool_use 사이클 경계에서 일시 정지 (experimental)
agent = Agent(model="us.anthropic.claude-sonnet-4-6", checkpointing=True)

# 실행 — 사이클 경계에 도달하면 stop_reason="checkpoint"로 반환
result = agent("프로젝트 구조를 분석해줘")

# 직렬화 — 체크포인트를 dict로 변환해 외부 저장소에 보관
saved = result.checkpoint.to_dict()

# 재개 — 저장한 dict를 checkpointResume로 그대로 되돌려 전달
agent({"checkpointResume": {"checkpoint": saved}})

Interrupts — 멈추고, 묻고, 재개하는 절차

멈추기 ② — 고위험 동작 앞에서 사람의 승인을 기다리는 HITL 4단계

1. 1
   트리거

   BeforeToolCallEvent에서 event.interrupt(name, reason) 호출 — 고위험 동작(파일 삭제, 결제) 전에 발동.

2. 2
   일시 정지

   stop_reason="interrupt"로 반환 — 재개에 필요한 정보는 result.interrupts에 담김.

3. 3
   사용자 확인

   외부 시스템(UI, Slack, API)이 사용자에게 승인/거부를 요청.

4. 4
   재개 또는 중단

   응답을 interruptResponse로 담아 재호출하면 이어서 실행 — 거부 응답이면 에이전트가 대안 탐색.

HumanInTheLoop

내장 HITL — from strands.vended_interventions.hitl, Agent(interventions=[...])로 장착

allowed_tools

승인 없이 통과시킬 도구 목록 — 나머지는 사람에게 묻습니다.

ask='stdio'

기본은 콘솔 승인 — 콜백을 넘기면 Slack·웹 UI로 연동