Snapshots와 Interrupts

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로 연동