사용자 지정 코드 기반 평가자
사용자 지정 코드 기반 평가자를 사용하면 LLM을 판사로 사용하는 대신 자체 AWS Lambda 함수를 사용하여 에이전트 성능을 프로그래밍 방식으로 평가할 수 있습니다. 이를 통해 평가 로직을 완벽하게 제어할 수 있습니다. 즉, 결정적 검사를 구현하거나, 외부 APIs 호출하거나, 정규식 일치를 실행하거나, 사용자 지정 지표를 계산하거나, 비즈니스별 규칙을 적용할 수 있습니다.
사전 조건
사용자 지정 코드 기반 평가자를 사용하려면 다음이 필요합니다.
-
AgentCore Evaluations 리소스와 동일한 리전에 배포된 AWS Lambda 함수입니다.
-
AgentCore Evaluations 서비스에 Lambda 함수를 호출할 수 있는 권한을 부여하는 IAM 실행 역할입니다.
-
Lambda 함수는 응답 스키마에 설명된 응답 스키마를 준수하는 JSON 응답을 반환해야 합니다.
IAM 권한
코드 기반 평가를 위해 Lambda 함수를 호출하려면 서비스 실행 역할에 다음과 같은 추가 권한이 필요합니다.
{ "Sid": "LambdaInvokeStatement", "Effect": "Allow", "Action": [ "lambda:InvokeFunction", "lambda:GetFunction" ], "Resource": "arn:aws:lambda:region:account-id:function:function-name" }
Lambda 함수 계약
참고
Lambda 함수의 최대 런타임 제한 시간은 5분(300초)입니다. Lambda 함수로 전송되는 최대 입력 페이로드 크기는 6MB입니다.
입력 스키마
Lambda 함수는 다음 구조의 JSON 페이로드를 수신합니다.
{ "schemaVersion": "1.0", "evaluatorId": "my-evaluator-abc1234567", "evaluatorName": "MyCodeEvaluator", "evaluationLevel": "TRACE", "evaluationInput": { "sessionSpans": [...] }, "evaluationReferenceInputs": [], "evaluationTarget": { "traceIds": ["trace123"], "spanIds": ["span123"] } }
| Field | 유형 | 설명 |
|---|---|---|
|
|
문자열 |
페이로드의 스키마 버전입니다. 현재 |
|
|
문자열 |
코드 기반 평가자의 ID입니다. |
|
|
문자열 |
코드 기반 평가자의 이름입니다. |
|
|
문자열 |
평가 수준: |
|
|
객체 |
평가를 위한 세션 범위를 포함합니다. |
|
|
List |
세션은 평가할 범위입니다. 원래 페이로드가 6MB를 초과하는 경우 잘릴 수 있습니다. |
|
|
List |
평가자에게 제공되는 참조 입력으로, 평가 수준에 따라 필터링됩니다. 코드 기반 평가자의 실측 정보 사용을 참조하세요. |
|
|
객체 |
평가할 특정 트레이스 또는 스팬을 식별합니다. 세션 수준 평가자의 경우이 값은 입니다 |
|
|
List |
평가 대상의 트레이IDs입니다. 트레이스 수준 및 도구 수준 평가에 사용됩니다. |
|
|
List |
평가 대상의 범위 IDs. 도구 수준 평가에 사용됩니다. |
응답 스키마
Lambda 함수는 다음 두 형식 중 하나와 일치하는 JSON 객체를 반환해야 합니다.
성공 응답
{ "label": "PASS", "value": 1.0, "explanation": "All validation checks passed." }
| Field | 필수 | 유형 | 설명 |
|---|---|---|---|
|
|
예 |
문자열 |
평가 결과에 대한 범주형 레이블(예: "PASS", "FAIL", "Good", "Poor"). |
|
|
아니요 |
숫자 |
숫자 점수(예: 0.0~1.0). |
|
|
아니요 |
문자열 |
평가 결과에 대한 사람이 읽을 수 있는 설명입니다. |
오류 응답
{ "errorCode": "VALIDATION_FAILED", "errorMessage": "Input spans missing required tool call attributes." }
| Field | 필수 | 유형 | 설명 |
|---|---|---|---|
|
|
예 |
문자열 |
오류를 식별하는 코드입니다. |
|
|
예 |
문자열 |
사람이 읽을 수 있는 오류 설명입니다. |
코드 기반 평가자 생성
CreateEvaluator API는 Lambda 함수 ARN과 선택적 제한 시간을 지정하여 코드 기반 평가자를 생성합니다.
필수 파라미터: 고유한 평가자 이름, 평가 수준(TRACE, TOOL_CALL 또는 SESSION ) 및 Lambda ARN이 포함된 코드 기반 평가자 구성입니다.
코드 기반 평가자 구성:
{ "codeBased": { "lambdaConfig": { "lambdaArn": "arn:aws:lambda:region:account-id:function:function-name", "lambdaTimeoutInSeconds": 60 } } }
| Field | 필수 | 기본값 | 설명 |
|---|---|---|---|
|
|
예 |
— |
호출할 Lambda 함수의 ARN입니다. |
|
|
아니요 |
60 |
Lambda 호출에 대한 초 단위 제한 시간(1~300). |
다음 코드 샘플은 다양한 개발 접근 방식을 사용하여 코드 기반 평가자를 생성하는 방법을 보여줍니다.
예
코드 기반 평가자를 사용하여 온디맨드 평가 실행
생성한 후에는 다른 평가자를 사용하는 것과 동일한 방식으로 Evaluate API와 함께 사용자 지정 코드 기반 평가자를 사용합니다. 서비스는 Lambda 호출, 병렬 팬아웃 및 결과 매핑을 자동으로 처리합니다.
예
평가 대상 사용
LLM 기반 평가자와 마찬가지로 특정 트레이스 또는 스팬을 대상으로 지정할 수 있습니다.
# Trace-level evaluation response = client.evaluate( evaluatorId="code-based-evaluator-id", evaluationInput={"sessionSpans": session_span_logs}, evaluationTarget={"traceIds": ["trace-id-1", "trace-id-2"]} ) # Tool-level evaluation response = client.evaluate( evaluatorId="code-based-evaluator-id", evaluationInput={"sessionSpans": session_span_logs}, evaluationTarget={"spanIds": ["span-id-1", "span-id-2"]} )
코드 기반 평가자에서 실측 정보 사용
실측 정보 참조 입력이 구성되면 Lambda 함수가 evaluationReferenceInputs 필드에서 해당 입력을 수신합니다. 포함된 참조 입력은 평가 수준에 따라 다릅니다.
| 평가 수준 | Lambda는 |
|---|---|
|
|
모든 참조 입력. |
|
|
세션 수준 참조 입력과 대상 traceId와 일치하는 참조 입력. |
|
|
세션 수준 참조 입력과 대상 spanId와 일치하는 참조 입력. |
참고
실측 정보 평가 사용에 대한 자세한 내용은 실측 정보 평가를 참조하세요.
코드 기반 평가자를 사용하여 온라인 평가 실행
온라인 평가 구성에서 사용자 지정 코드 기반 평가자를 사용하여 에이전트의 라이브 트래픽을 지속적으로 모니터링할 수 있습니다. 를 호출할 때 evaluators 목록에 평가자 ID를 전달합니다CreateOnlineEvaluationConfig.
예
참고
코드 기반 평가자를 참조하는 온라인 평가 구성이 활성화되면 평가자는 자동으로 잠기며 구성이 비활성화되거나 삭제될 때까지 수정하거나 삭제할 수 없습니다. 평가자를 변경하려면 먼저 온라인 평가 구성을 비활성화하거나 평가자를 복제하고 새 구성을 생성합니다.