🎯 Strands 제어와 확장

자율에 필요한 경계

모델이 스스로 도구와 반복을 결정하는 에이전트 — 통제 없는 자율이 만드는 사고들

제어의 4계층

자율은 남기고 경계만 세우는 4계층 — 가볍게는 Hooks, 최후에는 Sandbox

계층별 비교

적용 시점·수준·구현 방식이 모두 다른 4개 레이어

요청이 지나는 관문 순서

Hook 검사 → Plugin 정책 → Intervention 판정 → Sandbox 격리 — 네 계층이 번갈아 개입하는 경로

1. 1
   Hook: BeforeModelCallEvent

   모델 호출 전 검사 — 프롬프트 검증, 비용 체크

2. 2
   Plugin: 정책 확인

   deny/steer 규칙 평가 — 위반 시 차단하거나 방향 수정

3. 3
   Hook: BeforeToolCallEvent

   도구 호출 전 인자 검증·로깅

4. 4
   Intervention: 판정

   Cedar 정책이 permit/forbid 판정, HumanInTheLoop이 민감 도구 승인 요구 — 별개 클래스

5. 5
   Sandbox: 격리 실행

   허용된 도구를 컨테이너 내부에서 실행

Hooks

가장 가벼운 제어 계층 — 이벤트마다 콜백을 걸어 관찰하고 개입

8가지 Hook Event

에이전틱 루프 전 구간을 관찰할 수 있는 강타입 이벤트 포인트

Hook 등록

HookProvider 프로토콜로 기존 에이전트 코드 변경 없이 콜백 부착

from strands import Agent
from strands.hooks import BeforeToolCallEvent, HookProvider, HookRegistry

class BlockDangerousTools(HookProvider):
    """위험 도구 호출을 사전 차단"""
    BLOCKED = {"delete_file", "drop_table", "rm_rf"}

    def register_hooks(self, registry: HookRegistry, **kwargs) -> None:
        registry.add_callback(BeforeToolCallEvent, self.check_tool)

    def check_tool(self, event: BeforeToolCallEvent) -> None:
        tool_name = event.tool_use["name"]
        if tool_name in self.BLOCKED:
            event.cancel_tool = f"Blocked: {tool_name} is not allowed"

agent = Agent(
    model="us.anthropic.claude-sonnet-4-6",
    hooks=[BlockDangerousTools()],
)

Hooks 개입 패턴

관찰에서 개입으로 — 취소·예외·마스킹을 조합한 4가지 대표 시나리오

Plugins

확장 계층 — 제어 로직과 도구를 하나의 모듈로 묶어 장착

핵심 플러그인 5종

정책 제어·지시어 로드·컨텍스트 오프로딩·가이던스·실시간 텍스트 주입을 분담하는 플러그인

커스텀 플러그인 작성

Plugin을 상속하여 자체 제어 로직 구현

from strands import Agent
from strands.plugins import Plugin, hook
from strands.hooks import AfterModelCallEvent, BeforeInvocationEvent

class CostGuardPlugin(Plugin):  # 토큰 비용 누적 추적, 예산 초과 시 중단
    name = "cost-guard"

    def __init__(self, budget_usd: float = 1.0):
        super().__init__()
        self.budget_usd = budget_usd
        self.baseline_tokens, self.spent_usd = 0, 0.0

    @hook
    def reset_on_invocation(self, event: BeforeInvocationEvent) -> None:
        # 호출 시작 시점의 누적 토큰을 기준점으로 기록
        metrics = event.agent.event_loop_metrics
        self.baseline_tokens = metrics.accumulated_usage["totalTokens"]
        self.spent_usd = 0.0

    @hook
    def check_cost(self, event: AfterModelCallEvent) -> None:
        total = event.agent.event_loop_metrics.accumulated_usage["totalTokens"]
        # 0.000003은 토큰당 예시 단가 — 사용하는 모델의 실제 단가로 교체
        self.spent_usd = (total - self.baseline_tokens) * 0.000003
        if self.spent_usd >= self.budget_usd:
            raise RuntimeError(f"Budget exceeded: ${self.spent_usd:.4f}")
agent = Agent(model="us.anthropic.claude-sonnet-4-6", plugins=[CostGuardPlugin(budget_usd=0.50)])

플러그인 라이프사이클

플러그인 초기화부터 이벤트 구독까지의 동작 순서

1. 1
   Discovery

   Plugin 클래스에서 @hook, @tool 데코레이터가 붙은 메서드를 스캔하여 수집

2. 2
   Hook Registration

   각 @hook 메서드의 타입 힌트를 분석하여 해당 이벤트 타입에 콜백 등록

3. 3
   Tool Registration

   @tool 메서드를 에이전트의 도구 목록에 추가 — 모델이 호출 가능

4. 4
   init_agent 호출

   커스텀 초기화 로직 실행 — 상태 설정, 조건부 훅 추가, 에이전트 속성 접근

5. 5
   Plugin Ready

   등록 완료 후 에이전트 실행 시 이벤트 발생마다 콜백 자동 호출

Interventions

정책 계층 — 도구 호출을 허용·거부·승인 대기로 판정

Hooks vs Interventions

관찰형 제어와 정책형 제어의 근본적 차이

Cedar 정책

permit/forbid 규칙으로 도구 접근을 선언적 제어

// policy.cedar — 에이전트 도구 접근 정책 (action이 곧 도구 이름)

// 읽기 도구는 모든 principal에 허용
permit(
  principal,
  action == Action::"read_file",
  resource
);

// 프로덕션 DB 쓰기는 admin 역할만 — context_enricher가 주입한 role 검사
permit(
  principal,
  action == Action::"write_database",
  resource
) when {
  context.session.role == "admin"
};

// 파일 삭제는 전면 금지
forbid(
  principal,
  action == Action::"delete_file",
  resource
);
// 호출 측 — agent(prompt, invocation_state={"role": "admin"})
// principal은 principal_resolver가 invocation_state에서 해석 (실패 시 fail-closed)

HITL 승인 워크플로우

민감 작업 실행 전 인간 승인을 요구하는 Intervention 흐름

1. 1
   도구 호출 요청

   에이전트가 민감 도구(예: deploy_production) 호출 시도

2. 2
   HumanInTheLoop 판정

   allowed_tools에 없는 민감 도구면 승인 요구

3. 3
   승인 대기

   실행 일시 중지, ask 콜백으로 운영자 질의 — 기본 stdio, 콜백으로 Slack 등 연동

4. 4
   인간 판단

   운영자가 컨텍스트 확인 후 approve 또는 deny 응답

5. 5
   실행 또는 중단

   approve 시 도구 실행 속행, deny 시 에이전트에 거부 사유 전달

Sandbox

격리 계층 — 실행 환경 자체를 분리하는 최후의 방어선

격리 실행 3가지 방식

컨테이너 경계(Docker) · 물리 분리(SSH) · 도구형 셸(Strands Shell) — 격리 수준과 운영 부담의 트레이드오프

Docker Sandbox 연결

Agent 생성 시 sandbox=로 실행 중 컨테이너에 연결 — 파일·셸 작업 격리

from strands import Agent
from strands.sandbox.docker import DockerSandbox

# 사전에 실행 중인 컨테이너에 연결
sandbox = DockerSandbox(container="agent-workspace")

agent = Agent(
    model="us.anthropic.claude-sonnet-4-6",
    sandbox=sandbox,
    # sandbox_bash, sandbox_file_editor 도구가 자동 등록됨
)

# 에이전트의 모든 파일/셸 작업이 컨테이너 내부에서 실행
result = agent("프로젝트의 테스트를 실행하고 결과를 요약해줘")

격리 수준 선택

보안 요구사항에 따라 선택하는 3단계 격리 수준