View a markdown version of this page

Valutatore personalizzato basato su codice - Amazon Bedrock AgentCore

Valutatore personalizzato basato su codice

I valutatori personalizzati basati su codice consentono di utilizzare la propria funzione AWS Lambda per valutare a livello di codice le prestazioni degli agenti, anziché utilizzare un LLM come giudice. In questo modo avete il pieno controllo sulla logica di valutazione: potete implementare controlli deterministici, chiamare API esterne, eseguire corrispondenze regex, calcolare metriche personalizzate o applicare qualsiasi regola aziendale specifica.

Prerequisiti

Per utilizzare valutatori personalizzati basati su codice, è necessario:

autorizzazioni IAM

Il ruolo di esecuzione del servizio richiede la seguente autorizzazione aggiuntiva per richiamare le funzioni Lambda per la valutazione basata sul codice:

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

Contratto con funzione Lambda

Nota

Il timeout di esecuzione massimo per la funzione Lambda è di 5 minuti (300 secondi). La dimensione massima del payload di input inviato alla funzione Lambda è di 6 MB.

Schema di input

La tua funzione Lambda riceve un payload JSON con la seguente struttura:

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

schemaVersion

Stringa

Versione dello schema del payload. Attualmente"1.0".

evaluatorId

Stringa

L'ID del valutatore basato su codice.

evaluatorName

Stringa

Il nome del valutatore basato sul codice.

evaluationLevel

Stringa

Il livello di valutazione:TRACE, TOOL_CALL o. SESSION

evaluationInput

Oggetto

Contiene gli intervalli delle sessioni per la valutazione.

evaluationInput.sessionSpans

List

La sessione dura da valutare. Può essere troncato se il payload originale supera i 6 MB.

evaluationReferenceInputs

List

Input di riferimento forniti al valutatore, filtrati in base al livello di valutazione. Vedi Utilizzo della verità fondamentale in un valutatore basato su codice.

evaluationTarget

Oggetto

Identifica le tracce o gli intervalli specifici da valutare. Per i valutatori a livello di sessione, questo valore è. None

evaluationTarget.traceIds

List

Gli ID di traccia dell'obiettivo di valutazione. Presente per valutazioni a livello di traccia e di strumento.

evaluationTarget.spanIds

List

Gli span ID dell'obiettivo di valutazione. Presente per valutazioni a livello di strumento.

Schema di risposta

La tua funzione Lambda deve restituire un oggetto JSON corrispondente a uno dei due formati:

Risposta di successo

{ "label": "PASS", "value": 1.0, "explanation": "All validation checks passed." }
Campo Richiesto Tipo Description

label

Stringa

Un'etichetta categorica per il risultato della valutazione (ad esempio, «PASS», «FAIL», «Good», «Poor»).

value

No

Numero

Un punteggio numerico (ad esempio da 0,0 a 1,0).

explanation

No

Stringa

Una spiegazione leggibile dall'uomo del risultato della valutazione.

Risposta all'errore

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

errorCode

Stringa

Un codice che identifica l'errore.

errorMessage

Stringa

Una descrizione dell'errore leggibile dall'uomo.

Crea un valutatore basato su codice

L'CreateEvaluatorAPI crea un valutatore basato su codice specificando un ARN della funzione Lambda e un timeout opzionale.

Parametri richiesti: un nome di valutazione univoco, un livello di valutazione (TRACETOOL_CALL, oSESSION) e una configurazione di valutazione basata su codice contenente l'ARN Lambda.

Code-based configurazione del valutatore:

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

lambdaArn

L'ARN della funzione Lambda da richiamare.

lambdaTimeoutInSeconds

No

60

Timeout in secondi per la chiamata Lambda (1—300).

I seguenti esempi di codice mostrano come creare valutatori basati sul codice utilizzando diversi approcci di sviluppo.

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

Esegui una valutazione su richiesta con un valutatore basato su codice

Una volta creato, utilizza il valutatore personalizzato basato su codice con l'EvaluateAPI nello stesso modo in cui utilizzeresti qualsiasi altro valutatore. Il servizio gestisce automaticamente l'invocazione Lambda, il fan-out parallelo e la mappatura dei risultati.

Esempio
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

Utilizzo di obiettivi di valutazione

Puoi indirizzare tracce o intervalli specifici, proprio come con i LLM-based valutatori:

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

Utilizzo della verità fondamentale in un valutatore basato su codice

Quando gli input di riferimento Ground Truth sono configurati, la funzione Lambda li riceve sul campoevaluationReferenceInputs. Gli input di riferimento inclusi dipendono dal livello di valutazione:

Livello di valutazione Lambda riceve

SESSION

Tutti gli input di riferimento.

TRACE

Session-level input di riferimento più input di riferimento corrispondenti al traceID di destinazione.

TOOL_CALL

Session-level ingressi di riferimento più input di riferimento corrispondenti allo SpanID di destinazione.

Nota

Per ulteriori informazioni sull'utilizzo delle valutazioni di base della verità, consulta Ground truth evaluations.

Esegui una valutazione online con un valutatore basato su codice

Puoi utilizzare un valutatore personalizzato basato su codice in una configurazione di valutazione online per monitorare continuamente il traffico in tempo reale del tuo agente. Passa l'ID del valutatore nell'elenco quando chiamievaluators. CreateOnlineEvaluationConfig

Esempio
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

    Questo comando aggiunge la configurazione di valutazione online al localeagentcore.json. Esegui agentcore deploy per crearlo nel tuo AWS account.

    Nota

    Eseguilo dall'interno di una directory di AgentCore progetto (creata 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

Quando è abilitata una configurazione di valutazione online che fa riferimento a un valutatore basato su codice, il valutatore viene automaticamente bloccato e non può essere modificato o eliminato finché la configurazione non viene disabilitata o eliminata. Per apportare modifiche al valutatore, disattivate prima la configurazione di valutazione online oppure clonate il valutatore e create una nuova configurazione.