View a markdown version of this page

사용자 지정 코드 기반 평가자 - Amazon Bedrock AgentCore

사용자 지정 코드 기반 평가자

사용자 지정 코드 기반 평가자를 사용하면 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 유형 설명

schemaVersion

문자열

페이로드의 스키마 버전입니다. 현재 "1.0".

evaluatorId

문자열

코드 기반 평가자의 ID입니다.

evaluatorName

문자열

코드 기반 평가자의 이름입니다.

evaluationLevel

문자열

평가 수준: TRACE , TOOL_CALL 또는 SESSION.

evaluationInput

객체

평가를 위한 세션 범위를 포함합니다.

evaluationInput.sessionSpans

List

세션은 평가할 범위입니다. 원래 페이로드가 6MB를 초과하는 경우 잘릴 수 있습니다.

evaluationReferenceInputs

List

평가자에게 제공되는 참조 입력으로, 평가 수준에 따라 필터링됩니다. 코드 기반 평가자의 실측 정보 사용을 참조하세요.

evaluationTarget

객체

평가할 특정 트레이스 또는 스팬을 식별합니다. 세션 수준 평가자의 경우이 값은 입니다None.

evaluationTarget.traceIds

List

평가 대상의 트레이IDs입니다. 트레이스 수준 및 도구 수준 평가에 사용됩니다.

evaluationTarget.spanIds

List

평가 대상의 범위 IDs. 도구 수준 평가에 사용됩니다.

응답 스키마

Lambda 함수는 다음 두 형식 중 하나와 일치하는 JSON 객체를 반환해야 합니다.

성공 응답

{ "label": "PASS", "value": 1.0, "explanation": "All validation checks passed." }
Field 필수 유형 설명

label

문자열

평가 결과에 대한 범주형 레이블(예: "PASS", "FAIL", "Good", "Poor").

value

아니요

숫자

숫자 점수(예: 0.0~1.0).

explanation

아니요

문자열

평가 결과에 대한 사람이 읽을 수 있는 설명입니다.

오류 응답

{ "errorCode": "VALIDATION_FAILED", "errorMessage": "Input spans missing required tool call attributes." }
Field 필수 유형 설명

errorCode

문자열

오류를 식별하는 코드입니다.

errorMessage

문자열

사람이 읽을 수 있는 오류 설명입니다.

코드 기반 평가자 생성

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 필수 기본값 설명

lambdaArn

호출할 Lambda 함수의 ARN입니다.

lambdaTimeoutInSeconds

아니요

60

Lambda 호출에 대한 초 단위 제한 시간(1~300).

다음 코드 샘플은 다양한 개발 접근 방식을 사용하여 코드 기반 평가자를 생성하는 방법을 보여줍니다.

AgentCore CLI
  1. agentcore eval evaluator create \ --name "MyCodeEvaluator" \ --level TRACE \ --lambda-arn "arn:aws:lambda:us-east-1:123456789012:function:my-eval-function" \ --lambda-timeout 120
AgentCore SDK
  1. from bedrock_agentcore.evaluation.code_based_evaluators import ( EvaluatorInput, EvaluatorOutput, code_based_evaluator, ) import json as _json @code_based_evaluator() def json_response_evaluator(input: EvaluatorInput) -> EvaluatorOutput: """Check if the agent response in the target trace contains valid JSON.""" for span in input.session_spans: if span.get("traceId") != input.target_trace_id: continue if span.get("name", "").startswith("Model:") or span.get("name") == "Agent.invoke": output = span.get("attributes", {}).get("gen_ai.completion", "") try: _json.loads(output) return EvaluatorOutput( value=1.0, label="Pass", explanation="Response contains valid JSON" ) except (ValueError, TypeError): pass return EvaluatorOutput( value=0.0, label="Fail", explanation="No valid JSON found in agent response" )
AWS SDK
  1. import boto3 client = boto3.client('bedrock-agentcore-control') response = client.create_evaluator( evaluatorName="MyCodeEvaluator", level="TRACE", evaluatorConfig={ "codeBased": { "lambdaConfig": { "lambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:my-eval-function", "lambdaTimeoutInSeconds": 120 } } } ) print(f"Evaluator ID: {response['evaluatorId']}") print(f"Evaluator ARN: {response['evaluatorArn']}")
AWS CLI
  1. aws bedrock-agentcore-control create-evaluator \ --evaluator-name 'MyCodeEvaluator' \ --level TRACE \ --evaluator-config '{ "codeBased": { "lambdaConfig": { "lambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:my-eval-function", "lambdaTimeoutInSeconds": 120 } } }'

코드 기반 평가자를 사용하여 온디맨드 평가 실행

생성한 후에는 다른 평가자를 사용하는 것과 동일한 방식으로 Evaluate API와 함께 사용자 지정 코드 기반 평가자를 사용합니다. 서비스는 Lambda 호출, 병렬 팬아웃 및 결과 매핑을 자동으로 처리합니다.

AgentCore CLI
  1. agentcore run eval \ --runtime "your_runtime_name" \ --session-id "your_session_id" \ --evaluator "code-based-evaluator-id"
AgentCore SDK
  1. from bedrock_agentcore.evaluation.client import EvaluationClient client = EvaluationClient( region_name="region" ) results = client.run( evaluator_ids=[ "code-based-evaluator-id", ], session_id="session-id", log_group_name="log-group-name", )
AWS SDK
  1. import boto3 client = boto3.client('bedrock-agentcore') response = client.evaluate( evaluatorId="code-based-evaluator-id", evaluationInput={"sessionSpans": session_span_logs} ) for result in response["evaluationResults"]: if "errorCode" in result: print(f"Error: {result['errorCode']} - {result['errorMessage']}") else: print(f"Label: {result['label']}, Value: {result.get('value')}") print(f"Explanation: {result.get('explanation', '')}")
AWS CLI
  1. aws bedrock-agentcore evaluate \ --cli-input-json file://session_span_logs.json

평가 대상 사용

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는

SESSION

모든 참조 입력.

TRACE

세션 수준 참조 입력과 대상 traceId와 일치하는 참조 입력.

TOOL_CALL

세션 수준 참조 입력과 대상 spanId와 일치하는 참조 입력.

참고

실측 정보 평가 사용에 대한 자세한 내용은 실측 정보 평가를 참조하세요.

코드 기반 평가자를 사용하여 온라인 평가 실행

온라인 평가 구성에서 사용자 지정 코드 기반 평가자를 사용하여 에이전트의 라이브 트래픽을 지속적으로 모니터링할 수 있습니다. 를 호출할 때 evaluators 목록에 평가자 ID를 전달합니다CreateOnlineEvaluationConfig.

AgentCore CLI
  1. agentcore add online-eval \ --name "your_config_name" \ --runtime "your_runtime_name" \ --evaluator "code-based-evaluator-id" \ --sampling-rate 1.0 \ --enable-on-create

    이 명령은 온라인 평가 구성을 로컬 agentcore.json에 추가합니다. agentcore deploy를 실행하여 AWS 계정에서 생성합니다.

    참고

    AgentCore 프로젝트 디렉터리(로 생성됨) 내에서이 작업을 실행합니다agentcore create.

AgentCore SDK
  1. from bedrock_agentcore_starter_toolkit import Evaluation eval_client = Evaluation() config = eval_client.create_online_config( config_name="my_online_eval_config", agent_id="agent-id", sampling_rate=1.0, evaluator_list=["code-based-evaluator-id"], enable_on_create=True ) print(f"Config ID: {config['onlineEvaluationConfigId']}")
AWS SDK
  1. import boto3 client = boto3.client('bedrock-agentcore-control') response = client.create_online_evaluation_config( onlineEvaluationConfigName="my_online_eval_config", rule={"samplingConfig": {"samplingPercentage": 100.0}}, dataSourceConfig={ "cloudWatchLogs": { "logGroupNames": ["/aws/agentcore/my-agent-traces"], "serviceNames": ["my-agent.DEFAULT"] } }, evaluators=[{"evaluatorId": "code-based-evaluator-id"}], evaluationExecutionRoleArn="arn:aws:iam::account-id:role/AgentCoreEvaluationRole", enableOnCreate=True ) print(f"Config ID: {response['onlineEvaluationConfigId']}")
AWS CLI
  1. aws bedrock-agentcore-control create-online-evaluation-config \ --online-evaluation-config-name "my_online_eval_config" \ --rule '{"samplingConfig": {"samplingPercentage": 100.0}}' \ --data-source-config '{"cloudWatchLogs": {"logGroupNames": ["/aws/agentcore/my-agent-traces"], "serviceNames": ["my-agent.DEFAULT"]}}' \ --evaluators '[{"evaluatorId": "code-based-evaluator-id"}]' \ --evaluation-execution-role-arn "arn:aws:iam::account-id:role/AgentCoreEvaluationRole" \ --enable-on-create
참고

코드 기반 평가자를 참조하는 온라인 평가 구성이 활성화되면 평가자는 자동으로 잠기며 구성이 비활성화되거나 삭제될 때까지 수정하거나 삭제할 수 없습니다. 평가자를 변경하려면 먼저 온라인 평가 구성을 비활성화하거나 평가자를 복제하고 새 구성을 생성합니다.