View a markdown version of this page

Evaluador personalizado basado en código - Amazon Bedrock AgentCore

Evaluador personalizado basado en código

Los evaluadores personalizados basados en código le permiten usar su propia función AWS Lambda para evaluar mediante programación el rendimiento de los agentes, en lugar de utilizar un LLM como juez. Esto le da un control total sobre la lógica de evaluación: puede implementar comprobaciones deterministas, llamar a API externas, ejecutar coincidencias de expresiones regulares, calcular métricas personalizadas o aplicar cualquier regla específica de la empresa.

Requisitos previos

Para utilizar evaluadores personalizados basados en código, necesita:

Permisos de IAM

Su función de ejecución de servicios necesita el siguiente permiso adicional para invocar las funciones de Lambda para una evaluación basada en código:

{ "Sid": "LambdaInvokeStatement", "Effect": "Allow", "Action": [ "lambda:InvokeFunction", "lambda:GetFunction" ], "Resource": "arn:aws:lambda:region:account-id:function:function-name" }

Contrato de función Lambda

nota

El tiempo de espera máximo de la función Lambda es de 5 minutos (300 segundos). El tamaño máximo de carga útil de entrada que se envía a la función Lambda es de 6 MB.

Esquema de entrada

La función Lambda recibe una carga útil JSON con la siguiente estructura:

{ "schemaVersion": "1.0", "evaluatorId": "my-evaluator-abc1234567", "evaluatorName": "MyCodeEvaluator", "evaluationLevel": "TRACE", "evaluationInput": { "sessionSpans": [...] }, "evaluationReferenceInputs": [], "evaluationTarget": { "traceIds": ["trace123"], "spanIds": ["span123"] } }
Campo Tipo Description (Descripción)

schemaVersion

Cadena

Versión esquemática de la carga útil. Actualmente"1.0".

evaluatorId

Cadena

El ID del evaluador basado en código.

evaluatorName

Cadena

El nombre del evaluador basado en código.

evaluationLevel

Cadena

El nivel de evaluación:TRACE,TOOL_CALL, o. SESSION

evaluationInput

Objeto

Contiene los intervalos de sesión para la evaluación.

evaluationInput.sessionSpans

Enumeración

La sesión abarca la evaluación. Se puede truncar si la carga útil original supera los 6 MB.

evaluationReferenceInputs

Enumeración

Las entradas de referencia se proporcionan al evaluador y se filtran en función del nivel de evaluación. Consulte Uso de la verdad fundamental en un evaluador basado en código.

evaluationTarget

Objeto

Identifica los trazos o tramos específicos que se van a evaluar. Para los evaluadores a nivel de sesión, este valor es. None

evaluationTarget.traceIds

Enumeración

Los ID de rastreo del objetivo de la evaluación. Están presentes para las evaluaciones a nivel de trazas y herramientas.

evaluationTarget.spanIds

Enumeración

Los identificadores de intervalo del objetivo de la evaluación. Están presentes para las evaluaciones a nivel de herramienta.

Esquema de respuesta

La función Lambda debe devolver un objeto JSON que coincida con uno de estos dos formatos:

Respuesta correcta

{ "label": "PASS", "value": 1.0, "explanation": "All validation checks passed." }
Campo Obligatorio Tipo Description (Descripción)

label

Cadena

Una etiqueta categórica para el resultado de la evaluación (por ejemplo, «APROBADA», «FALLIDA», «BUENA», «MALA»).

value

No

Número

Una puntuación numérica (por ejemplo, de 0,0 a 1,0).

explanation

No

Cadena

Una explicación legible para el ser humano del resultado de la evaluación.

Respuesta de error

{ "errorCode": "VALIDATION_FAILED", "errorMessage": "Input spans missing required tool call attributes." }
Campo Obligatorio Tipo Description (Descripción)

errorCode

Cadena

Un código que identifica el error.

errorMessage

Cadena

Una descripción del error legible para las personas.

Cree un evaluador basado en código

La CreateEvaluator API crea un evaluador basado en código especificando el ARN de una función Lambda y un tiempo de espera opcional.

Parámetros necesarios: un nombre de evaluador único, un nivel de evaluación (TRACETOOL_CALL, oSESSION) y una configuración de evaluador basada en código que contenga el ARN de Lambda.

Code-based configuración del evaluador:

{ "codeBased": { "lambdaConfig": { "lambdaArn": "arn:aws:lambda:region:account-id:function:function-name", "lambdaTimeoutInSeconds": 60 } } }
Campo Obligatorio Predeterminado Description (Descripción)

lambdaArn

El ARN de la función Lambda que se va a invocar.

lambdaTimeoutInSeconds

No

60

Tiempo de espera en segundos para la invocación a Lambda (1—300).

Los siguientes ejemplos de código muestran cómo crear evaluadores basados en código utilizando diferentes enfoques de desarrollo.

ejemplo
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 } } }'

Realice una evaluación bajo demanda con un evaluador basado en código

Una vez creado, utilice el evaluador personalizado basado en código con la Evaluate API del mismo modo que utilizaría cualquier otro evaluador. El servicio gestiona automáticamente la invocación a Lambda, la distribución en paralelo y el mapeo de resultados.

ejemplo
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

Uso de objetivos de evaluación

Puede centrarse en trazas o tramos específicos, al igual que con los LLM-based evaluadores:

# 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"]} )

Uso de la verdad fundamental en un evaluador basado en código

Cuando se configuran las entradas de referencia de verdad fundamental, la función Lambda las recibe en el evaluationReferenceInputs campo. Las entradas de referencia incluidas dependen del nivel de evaluación:

Nivel de evaluación Lambda recibe

SESSION

Todas las entradas de referencia.

TRACE

Session-level entradas de referencia más entradas de referencia que coincidan con el TraceID objetivo.

TOOL_CALL

Session-level entradas de referencia más entradas de referencia que coincidan con el SpAnID objetivo.

nota

Para obtener más información sobre el uso de las evaluaciones de la verdad básica, consulte las evaluaciones de la verdad básica.

Realice una evaluación en línea con un evaluador basado en código

Puede usar un evaluador personalizado basado en código en una configuración de evaluación en línea para monitorear continuamente el tráfico en vivo de su agente. Cuando llames, pasa el identificador del evaluador de la evaluators lista. CreateOnlineEvaluationConfig

ejemplo
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

    Este comando agrega la configuración de evaluación en línea a su localagentcore.json. Ejecute agentcore deploy para crearla en su AWS cuenta.

    nota

    Ejecuta esto desde el interior de un directorio de AgentCore proyecto (creado conagentcore 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
nota

Cuando se habilita una configuración de evaluación en línea que hace referencia a un evaluador basado en código, el evaluador se bloquea automáticamente y no se puede modificar ni eliminar hasta que la configuración esté deshabilitada o eliminada. Para realizar cambios en el evaluador, desactive primero la configuración de evaluación en línea o clone el evaluador y cree una nueva configuración.