Plugins

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

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