Évaluateur 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 les performances des agents de manière programmatique, au lieu d'utiliser 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 d'expressions 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 à appeler votre fonction Lambda.
Autorisations IAM
Votre rôle d'exécution de service a besoin de l'autorisation supplémentaire suivante pour appeler les fonctions Lambda pour une é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 |
|---|---|---|
|
|
String |
Version du schéma de la charge utile. Actuellement |
|
|
String |
ID de l'évaluateur basé sur le code. |
|
|
String |
Nom de l'évaluateur basé sur le code. |
|
|
String |
Le niveau d'évaluation : |
|
|
Objet |
Contient les durées de session pour l'évaluation. |
|
|
List |
La session s'étend sur une période d'évaluation. Peut être tronqué si la charge utile d'origine dépasse 6 Mo. |
|
|
List |
Entrées de référence fournies à l'évaluateur, filtrées en fonction du niveau d'évaluation. Voir Utilisation de la vérité fondamentale dans un évaluateur basé sur le code. |
|
|
Objet |
Identifie les traces ou les travées spécifiques à évaluer. Pour les évaluateurs au niveau de la session, cette valeur est. |
|
|
List |
Les identifiants de trace de la cible d'évaluation. Présent pour les évaluations au niveau de la trace et au niveau de l'outil. |
|
|
List |
Les identifiants de durée 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 positive
{ "label": "PASS", "value": 1.0, "explanation": "All validation checks passed." }
| Champ | Obligatoire | Type | Description |
|---|---|---|---|
|
|
Oui |
String |
Une étiquette catégorique pour le résultat de l'évaluation (par exemple, « PASS », « FAIL », « Good », « Poor »). |
|
|
Non |
Number |
Un score numérique (par exemple, de 0,0 à 1,0). |
|
|
Non |
String |
Une explication lisible par l'homme du résultat de l'évaluation. |
Réponse à une erreur
{ "errorCode": "VALIDATION_FAILED", "errorMessage": "Input spans missing required tool call attributes." }
| Champ | Obligatoire | Type | Description |
|---|---|---|---|
|
|
Oui |
String |
Code identifiant l'erreur. |
|
|
Oui |
String |
Description lisible par l'homme de l'erreur. |
Création d'un évaluateur basé sur le 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 obligatoires : nom unique de l'évaluateur, niveau d'évaluation (TRACETOOL_CALL, ouSESSION) et configuration d'évaluateur basée sur le 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 |
|---|---|---|---|
|
|
Oui |
— |
L'ARN de la fonction Lambda à invoquer. |
|
|
Non |
60 |
Délai d'expiration en secondes pour l'appel Lambda (1 à 300). |
Les exemples de code suivants montrent comment créer des évaluateurs basés sur le code en utilisant différentes approches de développement.
Exemple
Exécutez une évaluation à la demande avec un évaluateur basé sur du code
Une fois créé, utilisez l'évaluateur personnalisé basé sur du code avec l'EvaluateAPI de la même manière que n'importe quel autre évaluateur. Le service gère automatiquement l'invocation Lambda, le fan-out parallèle et le mappage des résultats.
Exemple
Utilisation des cibles d'évaluation
Vous pouvez cibler des traces ou des étendues 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"]} )
Utilisation de la vérité fondamentale dans un évaluateur basé sur le code
Lorsque les entrées de référence Ground Truth sont configurées, votre fonction Lambda les reçoit sur le evaluationReferenceInputs terrain. Les entrées de référence incluses dépendent du niveau d'évaluation :
| Mode d’évaluation | Lambda reçoit |
|---|---|
|
|
Toutes les entrées de référence. |
|
|
Session-level entrées de référence plus entrées de référence correspondant au TraceID cible. |
|
|
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é sur le terrain, voir Évaluations de la vérité sur le terrain.
Exécutez une évaluation en ligne avec un évaluateur basé sur le code
Vous pouvez utiliser un évaluateur personnalisé basé sur du code dans une configuration d'évaluation en ligne pour surveiller en permanence le trafic réel de votre agent. Transmettez l'identifiant de l'évaluateur dans la evaluators liste lors de l'appelCreateOnlineEvaluationConfig.
Exemple
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.