Conditions préalables Autorisations IAM Contrat de fonction Lambda Création d'un évaluateur basé sur un code Exécutez une évaluation à la demande à l'aide d'un évaluateur basé sur le code Exécutez une évaluation en ligne avec un évaluateur basé sur un code

Evaluateur personnalisé basé sur un code

Les évaluateurs personnalisés basés sur du code vous permettent d'utiliser votre propre fonction AWS Lambda pour évaluer par programmation les performances des agents, au lieu de faire appel à un LLM comme juge. Cela vous donne un contrôle total sur la logique d'évaluation : vous pouvez implémenter des contrôles déterministes, appeler des API externes, exécuter des correspondances régulières, calculer des métriques personnalisées ou appliquer des règles spécifiques à l'entreprise.

Conditions préalables

Pour utiliser des évaluateurs personnalisés basés sur du code, vous devez :

Une fonction AWS Lambda déployée dans la même région que vos ressources d' AgentCore évaluation.
Rôle d'exécution IAM qui autorise le service AgentCore Evaluations à invoquer votre fonction Lambda.
La fonction Lambda doit renvoyer une réponse JSON conforme au schéma de réponse décrit dans Schéma de réponse.

Autorisations IAM

Votre rôle d'exécution de service a besoin de l'autorisation supplémentaire suivante pour invoquer les fonctions Lambda à des fins d'évaluation basée sur le code :


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

Contrat de fonction Lambda

Note

Le délai d'exécution maximal de la fonction Lambda est de 5 minutes (300 secondes). La taille maximale de la charge utile d'entrée envoyée à la fonction Lambda est de 6 Mo.

Schéma d'entrée

Votre fonction Lambda reçoit une charge utile JSON dont la structure est la suivante :


{
    "schemaVersion": "1.0",
    "evaluatorId": "my-evaluator-abc1234567",
    "evaluatorName": "MyCodeEvaluator",
    "evaluationLevel": "TRACE",
    "evaluationInput": {
        "sessionSpans": [...]
    },
    "evaluationReferenceInputs": [],
    "evaluationTarget": {
        "traceIds": ["trace123"],
        "spanIds": ["span123"]
    }
}

Champ	Type	Description
`schemaVersion`	Chaîne	Version du schéma de la charge utile. Actuellement`"1.0"`.
`evaluatorId`	Chaîne	L'ID de l'évaluateur basé sur le code.
`evaluatorName`	Chaîne	Le nom de l'évaluateur basé sur le code.
`evaluationLevel`	Chaîne	Le niveau d'évaluation : `TRACETOOL_CALL`, ou`SESSION`.
`evaluationInput`	Objet	Contient les périodes de session pour l'évaluation.
`evaluationInput.sessionSpans`	List	La session s'étend sur l'évaluation. Peut être tronqué si la charge utile d'origine dépasse 6 Mo.
`evaluationReferenceInputs`	List	Entrées de référence fournies à l'évaluateur, filtrées en fonction du niveau d'évaluation. Consultez la section Utilisation de la vérité de base dans un évaluateur basé sur le code.
`evaluationTarget`	Objet	Identifie les traces ou les étendues spécifiques à évaluer. Pour les évaluateurs au niveau de la session, cette valeur est. `None`
`evaluationTarget.traceIds`	List	Les identifiants de trace de la cible d'évaluation. Présent pour les évaluations au niveau des traces et des outils.
`evaluationTarget.spanIds`	List	Les identifiants de span de la cible d'évaluation. Présent pour les évaluations au niveau des outils.

Schéma de la réponse

Votre fonction Lambda doit renvoyer un objet JSON correspondant à l'un des deux formats suivants :

Réponse réussie


{
    "label": "PASS",
    "value": 1.0,
    "explanation": "All validation checks passed."
}

Champ	Obligatoire	Type	Description
`label`	Oui	Chaîne	Une étiquette catégorique pour le résultat de l'évaluation (par exemple, « RÉUSSITE », « ÉCHEC », « Bon », « Mauvais »).
`value`	Non	Nombre	Un score numérique (par exemple, 0,0 à 1,0).
`explanation`	Non	Chaîne	Une explication lisible par l'homme du résultat de l'évaluation.

Réponse d'erreur


{
    "errorCode": "VALIDATION_FAILED",
    "errorMessage": "Input spans missing required tool call attributes."
}

Champ	Obligatoire	Type	Description
`errorCode`	Oui	Chaîne	Code identifiant l'erreur.
`errorMessage`	Oui	Chaîne	Description lisible de l'erreur.

Création d'un évaluateur basé sur un code

L'CreateEvaluatorAPI crée un évaluateur basé sur le code en spécifiant un ARN de fonction Lambda et un délai d'expiration facultatif.

Paramètres requis : nom d'évaluateur unique, niveau d'évaluation (TRACETOOL_CALL, ouSESSION) et configuration d'évaluateur basée sur du code contenant l'ARN Lambda.

Code-based configuration de l'évaluateur :


{
    "codeBased": {
        "lambdaConfig": {
            "lambdaArn": "arn:aws:lambda:region:account-id:function:function-name",
            "lambdaTimeoutInSeconds": 60
        }
    }
}

Champ	Obligatoire	Par défaut	Description
`lambdaArn`	Oui	—	L'ARN de la fonction Lambda à invoquer.
`lambdaTimeoutInSeconds`	Non	60	Délai d'attente en secondes pour l'invocation Lambda (1 à 300).

Les exemples de code suivants montrent comment créer des évaluateurs basés sur du code en utilisant différentes approches de développement.

Exemple

AgentCore CLI


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


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


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


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

Exécutez une évaluation à la demande à l'aide d'un évaluateur basé sur le code

Une fois créé, utilisez l'évaluateur personnalisé basé sur le code avec l'EvaluateAPI de la même manière que vous utiliseriez n'importe quel autre évaluateur. Le service gère automatiquement l'invocation Lambda, le ventilateur parallèle et le mappage des résultats.

Exemple

Utilisation de cibles d'évaluation

Vous pouvez cibler des traces ou des intervalles spécifiques, comme avec les LLM-based évaluateurs :


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

Utiliser la vérité de base dans un évaluateur basé sur le code

Lorsque des entrées de référence de base sont configurées, votre fonction Lambda les reçoit evaluationReferenceInputs sur le terrain. Les entrées de référence incluses dépendent du niveau d'évaluation :

Mode d’évaluation	Lambda reçoit
`SESSION`	Toutes les entrées de référence.
`TRACE`	Session-level entrées de référence plus entrées de référence correspondant au TraceID cible.
`TOOL_CALL`	Session-level entrées de référence plus entrées de référence correspondant au SPanID cible.

Note

Pour plus d'informations sur l'utilisation des évaluations de la vérité du terrain, voir Évaluations de la vérité du terrain.

Exécutez une évaluation en ligne avec un évaluateur basé sur un code

Vous pouvez utiliser un évaluateur personnalisé basé sur un code dans une configuration d'évaluation en ligne pour surveiller en permanence le trafic en direct de votre agent. Transmettez l'identifiant de l'évaluateur dans la evaluators liste lors de l'appelCreateOnlineEvaluationConfig.

Exemple

AgentCore CLI

```
agentcore add online-eval \
  --name "your_config_name" \
  --runtime "your_runtime_name" \
  --evaluator "code-based-evaluator-id" \
  --sampling-rate 1.0 \
  --enable-on-create
```
Cette commande ajoute la configuration d'évaluation en ligne à votre configuration localeagentcore.json. Exécutez agentcore deploy pour le créer dans votre AWS compte.

Note
Exécutez-le depuis un répertoire de AgentCore projet (créé avecagentcore create).

AgentCore SDK


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


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


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

Note

Lorsqu'une configuration d'évaluation en ligne faisant référence à un évaluateur basé sur du code est activée, l'évaluateur est automatiquement verrouillé et ne peut pas être modifié ou supprimé tant que la configuration n'est pas désactivée ou supprimée. Pour apporter des modifications à l'évaluateur, désactivez d'abord la configuration d'évaluation en ligne ou clonez l'évaluateur et créez une nouvelle configuration.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Supprimer l'évaluateur

Évaluation en ligne