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:
-
Una función AWS Lambda implementada en la misma región que sus recursos de AgentCore evaluaciones.
-
Una función de ejecución de IAM que otorga permiso al servicio de AgentCore evaluaciones para invocar la función Lambda.
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) |
|---|---|---|
|
|
Cadena |
Versión esquemática de la carga útil. Actualmente |
|
|
Cadena |
El ID del evaluador basado en código. |
|
|
Cadena |
El nombre del evaluador basado en código. |
|
|
Cadena |
El nivel de evaluación: |
|
|
Objeto |
Contiene los intervalos de sesión para la evaluación. |
|
|
Enumeración |
La sesión abarca la evaluación. Se puede truncar si la carga útil original supera los 6 MB. |
|
|
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. |
|
|
Objeto |
Identifica los trazos o tramos específicos que se van a evaluar. Para los evaluadores a nivel de sesión, este valor es. |
|
|
Enumeración |
Los ID de rastreo del objetivo de la evaluación. Están presentes para las evaluaciones a nivel de trazas y herramientas. |
|
|
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) |
|---|---|---|---|
|
|
Sí |
Cadena |
Una etiqueta categórica para el resultado de la evaluación (por ejemplo, «APROBADA», «FALLIDA», «BUENA», «MALA»). |
|
|
No |
Número |
Una puntuación numérica (por ejemplo, de 0,0 a 1,0). |
|
|
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) |
|---|---|---|---|
|
|
Sí |
Cadena |
Un código que identifica el error. |
|
|
Sí |
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) |
|---|---|---|---|
|
|
Sí |
— |
El ARN de la función Lambda que se va a invocar. |
|
|
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
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
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 |
|---|---|
|
|
Todas las entradas de referencia. |
|
|
Session-level entradas de referencia más entradas de referencia que coincidan con el TraceID objetivo. |
|
|
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
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.