Strands 에러 처리

에러 처리와 복원력

분산 에이전트 고유의 실패 모드와 단계적 복구 — 장애 격리의 원칙

멀티에이전트 5가지 실패 모드

타임아웃 연쇄·환각 전파·도구 실패·핸드오프 유실·무한 루프 — 격리가 필요한 이유

SDK 내장 안전장치 파라미터

Swarm 생성자·Graph 빌더에 이미 들어 있는 실행 상한 — 직접 구현 전의 1차 방어선

복구 전략 4단계

실패 감지부터 Supervisor Escalation까지 단계적 복구 흐름

1. 1
   Retry (재시도)

   Exponential backoff로 일시적 장애 극복. 모델 호출 스로틀링 재시도는 SDK 기본 내장 — Agent(retry_strategy=ModelRetryStrategy(...)), 기본 max_attempts=6·초기 지연 4초·최대 지연 128초(Python 기준)이며 None을 주면 꺼집니다. is_retryable() 오버라이드로 재시도 대상 예외를 확장할 수 있습니다. 도구 재시도는 AfterToolCallEvent 훅의 retry 플래그로 트리거합니다.

2. 2
   Circuit Breaker (차단)

   연속 N회 실패 시 회로 차단 → 빠른 실패 반환. half-open 상태에서 주기적으로 복구 확인. 장애가 다른 에이전트로 전파되는 것을 방지합니다.

3. 3
   Fallback (대체)

   주 경로 실패 시 대체 에이전트 또는 간소화된 응답 반환. 예: GPT 실패 → Claude로 전환, 검색 실패 → 캐시된 결과 사용.

4. 4
   Supervisor Escalation

   모든 자동 복구 실패 시 Supervisor 에이전트가 개입. 작업을 재분배하거나 사람에게 에스컬레이션. EventBridge → SNS 알림 연동.

Retry + Circuit Breaker 구현

Strands Hooks 기반의 자동 복구 패턴 코드

핵심 포인트

HookProvider

훅 클래스의 베이스 — register_hooks(registry)로 이벤트별 콜백 등록 (필수)

BeforeToolCallEvent

도구 호출 직전 — 회로가 열려 있으면 event.cancel_tool 설정으로 도구만 취소 (예외 전파 없이 루프 지속)

AfterToolCallEvent

도구 호출 직후 — event.exception으로 실패 판별, failures에 횟수·시각 집계 (코드에선 등록만 표시)

hooks=[...]

Agent에 훅 주입 — 이 한 줄로 자동 차단 활성화

코드

import time
from strands import Agent
from strands.hooks import BeforeToolCallEvent, AfterToolCallEvent, HookProvider

class CircuitBreakerHook(HookProvider):
    def __init__(self, threshold=3, reset_timeout=60):
        self.failures, self.th, self.reset = {}, threshold, reset_timeout

    def register_hooks(self, registry, **kwargs):
        registry.add_callback(BeforeToolCallEvent, self.on_before)
        registry.add_callback(AfterToolCallEvent, self.on_after)  # 실패 집계

    def on_before(self, event):  # 임계 초과면 차단 (reset 경과 후 half-open)
        s = self.failures.get(event.tool_use["name"], {})
        if s.get("count", 0) >= self.th and time.time() - s["last"] < self.reset:
            event.cancel_tool = "circuit open"  # 도구만 취소 — 루프는 지속

agent = Agent(hooks=[CircuitBreakerHook()])

노드 레벨 훅 — 멀티에이전트 이벤트 5종

단일 에이전트 훅 8종에 더해 노드 실행을 가로채는 전용 이벤트 — 노드 단위 승인·차단·계측

핵심 포인트

MultiAgentInitializedEvent

Swarm·Graph 초기화 완료 시 1회 — 오케스트레이션 시작점 계측

NodeCallEvent 쌍

Before/AfterNodeCallEvent — 노드(에이전트) 실행 전후, event.node_id로 어느 노드인지 식별하는 위임 추적의 정본 지점

MultiAgentInvocationEvent

Before/After 쌍 — 멀티에이전트 호출 전체의 전후, 실행 단위 비용·시간 집계

cancel_node

BeforeNodeCallEvent에서 설정 — 해당 노드만 취소. event.interrupt()로 실행 전 사람 승인 대기도 가능

hooks=[...]

Swarm·Graph 생성자에 그대로 주입 — 단일 에이전트 훅과 같은 등록 방식

코드

from strands import Agent
from strands.multiagent import Swarm
from strands.hooks import HookProvider, BeforeNodeCallEvent

class NodeApprovalHook(HookProvider):
    def register_hooks(self, registry, **kwargs):
        registry.add_callback(BeforeNodeCallEvent, self.on_node)

    def on_node(self, event):
        # 배포 노드만 실행 전 검사 — 거부되면 그 노드만 취소
        if event.node_id == "deploy" and not approved(event.node_id):
            event.cancel_node = "승인 거부 — deploy 노드 차단"

# 단일 에이전트와 같은 hooks= — Swarm/Graph 생성자 지원
swarm = Swarm(nodes=[research, write, deploy],
              hooks=[NodeApprovalHook()])

운영 장면 — 장애에서 복구까지

리서치 Swarm의 요약 노드 타임아웃부터 session_manager 재개까지 — 안전장치가 개입하는 순서