Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Strands Evals SDK는 AI 에이전트 및 LLM 애플리케이션의 성능을 포괄적으로 평가할 수 있는 프레임워크입니다. 이 SDK를 사용하면 복잡한 에이전트 시스템과 LLM 기반 앱의 다양한 측면을 체계적으로 테스트하고 검증할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기◆ <a href="https://github.com/strands-agents/tools">도구(Tools)</a>
◆ <a href="https://github.com/strands-agents/evals">평가(Evaluations)</a>
Strands Evaluation은 AI 에이전트와 LLM 애플리케이션을 평가하기 위한 강력한 프레임워크입니다. 단순 출력 검증부터 복잡한 다중 에이전트 상호작용 분석, 궤적(trajectory) 평가, 자동화된 실험 생성에 이르기까지, Strands Evaluation은 AI 시스템을 측정하고 개선하는 포괄적인 도구를 제공합니다.
다중 평가 유형: 출력 평가, 궤적 분석, 도구 사용 평가, 상호작용 평가
멀티모달 평가: 이미지-텍스트 작업에 대한 내장 루브릭을 갖춘 MLLM-as-a-Judge 평가기
스킬 평가: 스킬이 장착된 에이전트가 어떤 스킬을 선택했는지, 그리고 그들이 지침을 따랐는지를 평가합니다.
동적 시뮬레이터: 현실적인 사용자 행동, 목표 지향적 상호작용, 공유 상태를 갖춘 LLM 기반 도구 시뮬레이션이 가능한 다중 턴 대화 시뮬레이션
LLM-as-a-Judge: 구조화된 채점(structured scoring)을 통해 정교한 평가가 가능한 언어 모델을 사용한 내장 평가기
추적 기반 평가 (Trace-based Evaluation): OpenTelemetry 실행 추적(execution traces)을 통해 에이전트 행동 분석
자동 실험 생성: 컨텍스트 설명으로부터 포괄적인 테스트 스위트를 생성합니다.
사용자 정의 평가기 (Custom Evaluators): 도메인별 평가 로직을 위한 확장 가능한 프레임워크
실험 관리 (Experiment Management): JSON 직렬화(JSON serialization)를 통해 평가 실험 저장, 로드 및 버전 관리
내장 채점 도구: 정확 일치(exact), 순서 일치(in-order), 임의 순서 일치(any-order) 궤적 매칭을 위한 헬퍼 함수
실패 감지 및 근본 원인 분석 (Failure Detection & Root Cause Analysis): 에이전트 세션에서 실패를 자동으로 감지하고, 실행 가능한 수정 권장 사항과 함께 근본 원인을 진단합니다.
카오스 테스트 (Chaos Testing): Strands 플러그인 훅을 통한 결정론적 오류 주입(Deterministic fault injection) — 도구 시간 초과, 네트워크 오류, 응답 손상 등을 시뮬레이션하여 에이전트 복원력 평가
Red Team 평가: 내장된 공격 전략 (Crescendo, GOAT, PAIR, BadLikertJudge, SequentialBreak)을 사용한 적대적 안전성 테스트를 수행합니다. 자세한 내용은 src/strands_evals/experimental/redteam/README.md을 참조하세요.
# Strands Evals SDK 설치
pip install strands-agents-evals
from strands import Agent
from strands_evals import Case, Experiment
from strands_evals.evaluators import OutputEvaluator
...
strands-agents-evals를 설치하면 strands-evals 콘솔 스크립트도 함께 설치됩니다. 이는 CI 및 일회성 사용을 위해 Python API 위에 구현된 얇은(thin) 래퍼입니다. 이 스크립트는 다섯 가지 하위 명령어를 가지고 있습니다:
| 명령어 | 목적 |
|---|---|
strands-evals run | --agent 팩토리 또는 --task 호출 가능한 객체에 대해 실험을 실행하거나, --input + --evaluator/--expected-output/--rubric를 통해 단일 임시(ad-hoc) 케이스를 실행합니다. |
| ... | |
| 공통 흐름: |
# 스키마 검증 후 에이전트 팩토리에 대해 실험 파일을 실행
strands-evals validate experiments/customer_service.json
strands-evals run experiments/customer_service.json \
...
모든 하위 명령어는 --help를 사용하여 전체 플래그 세트(MODULE:CLASS를 통한 사용자 정의 평가기, 추적 속성, --fail-on 종료 코드 규칙, 출력 형식 등)를 확인할 수 있습니다.
Python 3.10 이상이 설치되어 있는지 확인한 후 다음을 수행하세요:
# 가상 환경 생성 및 활성화
python -m venv .venv
source .venv/bin/activate # Windows의 경우: .venv
Scripts
activate
...
LLM-as-a-judge를 사용하여 유연한 채점 기준으로 에이전트 응답을 평가합니다:
from strands_evals.evaluators import OutputEvaluator
evaluator = OutputEvaluator(
...
도우미(helper) 채점 함수를 사용하여 에이전트의 도구 사용 및 행동 시퀀스를 분석합니다:
OpenTelemetry 트레이스를 사용하여 7단계 점수 체계로 에이전트의 유용성을 평가합니다:
from strands_evals.evaluators import HelpfulnessEvaluator
from strands_evals.telemetry import StrandsEvalsTelemetry
from strands_evals.mappers import StrandsInMemorySessionMapper
...
ActorSimulator를 사용하여 동적이고 목표 지향적인 대화를 통해 현실적인 사용자 상호작용을 시뮬레이션합니다:
from strands import Agent
from strands_evals import Case, Experiment, ActorSimulator
from strands_evals.evaluators import HelpfulnessEvaluator, GoalSuccessRateEvaluator
...
주요 이점:
ToolSimulator를 사용하여 LLM(대규모 언어 모델) 기반 응답으로 도구 동작을 시뮬레이션함으로써 통제된 에이전트 평가를 수행합니다. 데코레이터로 도구를 등록하고, 출력 스키마를 정의하며, 선택적으로 관련 도구 간 상태를 공유할 수 있습니다. 이 시뮬레이터는 실제 실행 대신 현실적이며 스키마가 검증된 응답으로 대체합니다:
from typing import Any
from enum import Enum
from pydantic import BaseModel, Field
...
주요 이점:
share_state_id를 통해 상태를 공유하여 일관된 동작을 수행합니다.get_tool()을 통해 Strands의 Agent에 직접 플러그인됩니다.컨텍스트 설명을 기반으로 포괄적인 테스트 스위트를 자동으로 생성합니다:
from strands_evals.generators import ExperimentGenerator
from strands_evals.evaluators import TrajectoryEvaluator
...
에이전트 세션에서 발생하는 실패를 감지하고 근본 원인을 분석하여 실행 가능한 수정 권장 사항을 얻습니다:
from strands_evals import Case, DiagnosisConfig, Experiment
from strands_evals.evaluators import HelpfulnessEvaluator
from strands_evals.types.detector import ConfidenceLevel, DiagnosisTrigger
...
또한 모든 Session 객체(strands_evals.types.trace.Session)에 대해 디텍터들을 독립적으로 사용할 수 있습니다:
from strands_evals.detectors import detect_failures, analyze_root_cause, diagnose_session
from strands_evals.types.detector import ConfidenceLevel
...
결정론적 도구 실패와 응답 손상을 주입하여 에이전트가 역경 조건에 어떻게 대처하는지 평가합니다. 효과는 Strands의 네이티브 플러그인 훅을 통해 전파되며, 사용자의 작업 본체(task body)는 카오스로부터 자유롭습니다:
from strands import Agent
from strands_evals import Case
from strands_evals.chaos import (
...
사용 가능한 효과(effects): Timeout, NetworkError, ExecutionError, ValidationError (도구 호출 취소); TruncateFields, RemoveFields, CorruptValues (응답 손상). strands_evals.evaluators.chaos의 혼돈 인식 평가기(FailureCommunicationEvaluator, PartialCompletionEvaluator, RecoveryStrategyEvaluator)와 쌍을 이루어 사용합니다. 전체 작성 가이드는 SKILL.md를 참조하십시오.
표준화된 출력 형식으로 도메인별 평가 로직을 생성합니다:
from strands_evals.evaluators import Evaluator
from strands_evals.types import EvaluationData, EvaluationOutput
...
Equals는 구조화된 출력을 전체 객체(==)와 비교하므로 0.0 또는 1.0을 점수로 매깁니다.
StructuredOutputSimilarity는 필드별로 비교하고 수정해야 할 필드 이름을 알려줍니다.
결정론적이며 오프라인 방식: LLM 심사관(judge) 없음, 자격 증명(credentials) 필요 없음, 호출당 비용 없음.
from pydantic import BaseModel
from strands_evals import Experiment, StructuredOutputReport
from strands_evals.evaluators import StructuredOutputSimilarity
...
두 개의 라인 항목이 있는 송장(invoice)의 경우, 다른 모든 필드가 정확할 때:
Equals | StructuredOutputSimilarity | |
|---|---|---|
| 리스트 순서 변경, 내용 동일 | 0.0 | 1.0 |
| 수량 하나 오류, 리스트 순서 변경 | 0.0 | 0.9375 |
두 번째 행에서, reason은 weakest fields: line_items=0.75를 표시하고, metrics()는 전체 데이터셋에 걸쳐 line_items.quantity와 같은 중첩된 경로(nested paths)를 보고합니다. match_threshold보다 낮은 점수를 받은 리스트 항목은 부모 경로 아래에서 하나의 잘못된 항목으로 간주되며 자식 경로에서는 계산되지 않으므로, 여기서는 오류가 line_items.quantity가 아닌 line_items에 대해 fd=1로 표시됩니다.
저장된 보고서(Saved reports). 필드 상세 정보는 각 보고서 행에 저장되므로 report.to_file() 및 strands-evals run --output을 거쳐도 유지됩니다. CLI로는 report_cls를 설정할 수 없으므로, StructuredOutputReport.from_file("report.json").metrics()를 사용하여 그 출력을 다시 읽어와야 합니다. 결과 저장소(result store)나 실험 파일에서 읽어온 사례는 모델이 자체 JSON을 통해 왕복(round-trip) 과정을 거치면서 점수를 매길 때 메모리 내의 경우와 동일한 점수를 받지만, 사용자 정의 직렬화기(custom serializer)를 사용하거나 매번 값을 변경하는 검증기(validator)를 사용하는 경우에는 그렇지 않습니다.
평가기당 하나의 스키마(One schema per evaluator). model_cls는 필수입니다. 결과 저장소나 실험 파일은 사례를 일반 딕셔너리(plain dicts)로 반환하며, 모델이 이를 읽어옵니다. 모델의 필드 중 어느 것도 없는 비어있지 않은 값은 실패하고 그 이유와 함께 키 이름이 명시됩니다. 모델과 필드 이름을 공유하는 값을 가진 경우, 다른 키들은 무시되고 해당 값이 모델로 읽힙니다. 모든 평가기는 모든 사례에 대해 실행되므로, 에이전트가 하나 이상의 출력 유형을 방출하는 경우 각 유형마다 별도의 Experiment를 실행해야 합니다.
희소 스키마(sparse schemas)에서의 test_pass. 점수는 양쪽 모두에서 비어 있는 필드를 올바른 것으로 간주합니다. 따라서 정답 데이터가 2개의 필드를 채우는 10개 필드 모델은 빈 예측에 대해 0.80의 점수를 받습니다. 그러므로 test_pass 역시 match_threshold를 통과하기 위해 재현율(recall)을 요구하며, 이는 빈 예측으로는 불가능합니다. 각 행의 metadata에는 더 엄격한 게이트를 위한 정밀도(precision), 재현율(recall), 그리고 F1 점수가 포함됩니다. 중요한 필드에 가중치를 부여하려면 모델을 ComparableField(weight=...)를 가진 까다로운(stickler) StructuredModel로 선언하거나, weight_hints=True를 전달해야 합니다.
stickler 추가가 필요합니다: pip install "strands-agents-evals[stickler]".