Strands Evals

평가 파이프라인 4단계

Case 정의 → 실행 → 평가 → 리포트, 그리고 다시 Case로 — 반복 가능한 품질 루프

평가 3요소

Test Case · Evaluator · Experiment — 품질 시스템의 구성 단위

환경별 평가 전략

개발 · CI/CD · 프로덕션 — 각 환경에 최적화된 평가 방식

테스트와 시뮬레이터

외부 의존성 없는 mock 환경에서 Case Suite를 병렬 실행하고 일괄 평가

ToolSimulator — 도구 mock 테스트

외부 API 의존성을 제거하고 스키마 검증 mock으로 재현 가능한 테스트 구성

핵심 포인트

ToolSimulator()

실제 API 호출 없이 — LLM이 스키마에 맞는 mock 응답을 생성

@tool_simulator.tool()

mock으로 대체할 도구 등록 — tool()은 데코레이터 팩토리라 괄호 필수

task(case)

케이스마다 호출되는 실행 함수 — mock 도구로 에이전트를 만들어 응답을 반환

run_evaluations(task)

task 함수 필수 — Case마다 task를 실행하고 Evaluator로 일괄 채점

코드

from strands import Agent
from strands_evals import Case, Experiment
from strands_evals.evaluators import OutputEvaluator
from strands_evals.simulation.tool_simulator import ToolSimulator

tool_simulator = ToolSimulator()

@tool_simulator.tool()          # 괄호 필수 — tool()은 데코레이터 팩토리
def get_weather(city: str) -> dict:
    """도시의 현재 날씨를 조회합니다"""

def task(case):  # 케이스마다 호출 — mock 도구로 에이전트 실행
    agent = Agent(tools=[tool_simulator.get_tool("get_weather")])
    return str(agent(case.input))

case = Case(input="서울 날씨 알려줘",
    expected_output="서울의 현재 기온은 22도이며 맑습니다")
experiment = Experiment(cases=[case],
    evaluators=[OutputEvaluator(rubric="날씨 정보가 정확한가")])
results = experiment.run_evaluations(task)

Experiment 실행 흐름

Case Suite를 병렬 실행하고 결과를 집계하는 Experiment 워크플로우

1. 1
   Suite 로드

   JSON 또는 Python에서 Case 배열을 로드 — CLI의 strands-evals validate가 JSON 스키마를 검증. 태그로 필터링하여 부분 실행 가능 (예: tag="tool_use").

2. 2
   Agent 구성

   task 함수가 케이스마다 테스트 대상 Agent를 구성하고 ToolSimulator를 바인딩. model_id, temperature 등 설정을 Experiment Config로 고정.

3. 3
   병렬 실행

   asyncio 워커 큐로 Case를 병렬 실행. max_workers로 병렬도 제어 (run_evaluations_async 기본 10, 동기판 기본 1). 각 Case별 실행 시간과 토큰 수 측정.

4. 4
   평가 + 집계

   각 Case의 actual을 Evaluator로 채점. 전체 통과율, 평균 점수, 실패 Case 목록을 EvaluationReport로 출력.

실행 결과 — pass / fail 리포트

run_evaluations(task)가 끝나면 받는 것 — 케이스별 판정과 근거, 그리고 집계

시뮬레이터 유형별 사용처

ToolSimulator · ActorSimulator · Chaos effects — 검증 목적에 맞는 시뮬레이터 선택

평가자

에이전트 출력을 채점하는 클래스 — 빌트인 20종+와 Custom으로 품질을 다각도 측정

빌트인 평가자 20종+

LLM-as-Judge와 규칙 기반을 조합한 사전 정의 평가 클래스

Custom Evaluator 작성

도메인 특화 평가 기준을 Evaluator 서브클래스로 정의

핵심 포인트

Evaluator

서브클래스로 도메인 특화 평가 기준 정의 — evaluate 메서드만 구현

evaluation_case.actual_output

에이전트의 실제 출력 — 여기서 위험 키워드를 검사

EvaluationOutput

점수(score) + 통과 여부(test_pass) + 판단 근거(reason)를 리스트로 반환

evaluators=[...]

평가자는 인스턴스로 추가 (문자열 이름 불가) — 빌트인과 혼용 가능

코드

from strands_evals import Experiment
from strands_evals.evaluators import Evaluator, OutputEvaluator
from strands_evals.types import EvaluationOutput

# SQL 쿼리 안전성 평가 — DROP/TRUNCATE/DELETE 감지
class SqlSafetyEvaluator(Evaluator):
    def evaluate(self, evaluation_case) -> list[EvaluationOutput]:
        output = str(evaluation_case.actual_output or "")
        dangerous = ["DROP", "TRUNCATE", "DELETE FROM"]
        has_danger = any(kw in output.upper() for kw in dangerous)
        return [EvaluationOutput(score=0.0 if has_danger else 1.0,
            test_pass=not has_danger, reason=f"위험 키워드: {has_danger}")]

experiment = Experiment(
    cases=sql_cases,
    evaluators=[SqlSafetyEvaluator(), OutputEvaluator(rubric="정답과 일치하는가")],
)

평가 카테고리 3축

정확성 · 안전성 · 효율성 — 에이전트 품질의 세 가지 차원

Chaos와 Red Team

장애를 주입해 복원력을, 적대적 입력을 주입해 방어력을 사전 검증

5가지 Chaos 전략

에이전트의 복원력을 체계적으로 검증하는 장애 주입 패턴

ChaosExperiment 적용

에이전트에 Chaos 주입을 설정하는 코드 패턴

핵심 포인트

ChaosCase(effects=)

tool_effects로 도구별 장애 효과 지정 — 툴당 케이스별 효과 1개

Timeout · NetworkError · TruncateFields

strands_evals.chaos.effects가 제공하는 장애 효과

ChaosPlugin()

파라미터 없이 Agent의 plugins로 주입

ChaosExperiment

장애 환경에서 Case 일괄 실행 — 에이전트의 복원 행동 관찰

코드

from strands import Agent
from strands_evals.chaos import ChaosCase, ChaosExperiment, ChaosPlugin
from strands_evals.chaos import Timeout, NetworkError

chaos_case = ChaosCase(
    name="weather-under-failure",
    input="서울 날씨를 알려줘",
    # 툴당 케이스별 효과 1개 제한 — 도구별로 타깃을 나눠 주입
    effects={"tool_effects": {
        "get_weather": [Timeout()],
        "http_request": [NetworkError()],
    }},
)

agent = Agent(
    model="us.anthropic.claude-sonnet-4-6",
    tools=[http_request, get_weather],
    plugins=[ChaosPlugin()],
)

results = ChaosExperiment(cases=[chaos_case]).run_evaluations()

Red Team 파이프라인

적대적 입력으로 에이전트 방어력을 사전 검증하는 5단계 프로세스

1. 1
   공격 시나리오 정의

   탈옥·프롬프트 인젝션·데이터 유출 등 검증할 공격 시나리오를 구체화. RedTeamExperiment(experimental)가 파이프라인 골격을 제공.

2. 2
   적대적 Case 생성

   AdversarialCaseGenerator가 Crescendo · GOAT · PAIR · BadLikertJudge · SequentialBreak 전략으로 적대적 입력을 자동 생성.

3. 3
   에이전트 실행

   적대적 입력을 에이전트에 주입. Guardrails, System Prompt 방어, 도구 접근 제어가 정상 작동하는지 관찰.

4. 4
   사후 진단

   detect_failures · analyze_root_cause · diagnose_session이 세션을 사후 분석. DiagnosisConfig(trigger=DiagnosisTrigger.ON_FAILURE, confidence_threshold=ConfidenceLevel.MEDIUM)로 실패 시 자동 진단.

5. 5
   취약점 리포트

   공격 성공률, 방어 우회 패턴, 미감지 케이스를 리포트로 정리. 보안 패치 우선순위 결정에 활용.