View a markdown version of this page

Evaluador personalizado basado en código - Base amazónica AgentCore

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Evaluador personalizado basado en código

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

Requisitos previos

Para usar evaluadores personalizados basados en código, necesitas:

  • Una función de AWS Lambda implementada en la misma región que sus AgentCore recursos de evaluación.

  • Una función de ejecución de IAM que otorga al servicio de AgentCore evaluaciones permiso para invocar su función de Lambda.

  • La función Lambda debe devolver una respuesta JSON que se ajuste al esquema de respuestas descrito en el esquema de respuestas. Esquema de respuesta

Permisos de IAM

Su función de ejecución de servicios necesita el siguiente permiso adicional para invocar las funciones de Lambda para la 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 máximo de ejecución 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 de 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. En la actualidad"1.0".

evaluatorId

Cadena

El ID del evaluador basado en el 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 la duración de las sesiones de evaluación.

evaluationInput.sessionSpans

Enumeración

La sesión se extiende a lo largo de la evaluación. Puede truncarse si la carga útil original supera los 6 MB.

evaluationReferenceInputs

Enumeración

Las entradas de referencia proporcionadas al evaluador se filtran según el nivel de evaluación. Consulte Uso de la verdad básica en un evaluador basado en código.

evaluationTarget

Objeto

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

evaluationTarget.traceIds

Enumeración

Los identificadores de seguimiento del objetivo de evaluación. Preséntelos para las evaluaciones a nivel de rastreo y a nivel de herramienta.

evaluationTarget.spanIds

Enumeración

Los identificadores de longitud del objetivo de evaluación. Preséntelo para las evaluaciones a nivel de herramienta.

Esquema de respuesta

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

Respuesta exitosa

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

label

Sí

Cadena

Una etiqueta categórica para el resultado de la evaluación (por ejemplo, «APROBADO», «NO APROBADO», «BUENO» o «DEFICIENTE»).

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 los humanos 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

Sí

Cadena

Un código que identifica el error.

errorMessage

Sí

Cadena

Una descripción del error legible por humanos.

Cree un evaluador basado en código

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

Parámetros obligatorios: 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

Sí

—

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

lambdaTimeoutInSeconds

No

60

Tiempo de espera en segundos para la invocación de 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 add evaluator \ --name "MyCodeEvaluator" \ --level TRACE \ --type code-based \ --lambda-arn "arn:aws:lambda:us-east-1:123456789012:function:my-eval-function" \ --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 } } }'

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

Una vez creado, usa el evaluador personalizado basado en código con la Evaluate API del mismo modo que usarías cualquier otro evaluador. El servicio gestiona automáticamente la invocación de 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 intervalos 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 básica en un evaluador basado en código

Cuando se configuran las entradas de referencia de Ground Truth, la función Lambda las recibe en el campo. evaluationReferenceInputs 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 de destino.

TOOL_CALL

Session-level entradas de referencia más entradas de referencia que coincidan con el SpaniD de destino.

nota

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

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, introduce el identificador del evaluador en 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

    Ejecútelo desde el directorio de un 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 se deshabilite o elimine la configuración. Para realizar cambios en el evaluador, deshabilite primero la configuración de evaluación en línea o clone el evaluador y cree una nueva configuración.