View a markdown version of this page

Évaluateur personnalisé basé sur un code - Amazon Bedrock AgentCore

É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 :

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

schemaVersion

String

Version du schéma de la charge utile. Actuellement"1.0".

evaluatorId

String

ID de l'évaluateur basé sur le code.

evaluatorName

String

Nom de l'évaluateur basé sur le code.

evaluationLevel

String

Le niveau d'évaluation : TRACETOOL_CALL, ouSESSION.

evaluationInput

Objet

Contient les durées de session pour l'évaluation.

evaluationInput.sessionSpans

List

La session s'étend sur une période d'é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. Voir Utilisation de la vérité fondamentale dans un évaluateur basé sur le code.

evaluationTarget

Objet

Identifie les traces ou les travées 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 de la trace et au niveau de l'outil.

evaluationTarget.spanIds

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

label

Oui

String

Une étiquette catégorique pour le résultat de l'évaluation (par exemple, « PASS », « FAIL », « Good », « Poor »).

value

Non

Number

Un score numérique (par exemple, de 0,0 à 1,0).

explanation

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

errorCode

Oui

String

Code identifiant l'erreur.

errorMessage

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

lambdaArn

Oui

L'ARN de la fonction Lambda à invoquer.

lambdaTimeoutInSeconds

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

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

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

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é 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
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

    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
  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
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.