기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
사용자 지정 코드 기반 평가자
사용자 지정 코드 기반 평가자를 사용하면 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.
예
참고
코드 기반 평가자를 참조하는 온라인 평가 구성이 활성화되면 평가자는 자동으로 잠기며 구성이 비활성화되거나 삭제될 때까지 수정하거나 삭제할 수 없습니다. 평가자를 변경하려면 먼저 온라인 평가 구성을 비활성화하거나 평가자를 복제하고 새 구성을 생성합니다.