View a markdown version of this page

Valutatore personalizzato basato su codice - Fondamento Amazon AgentCore

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Valutatore personalizzato basato su codice

I valutatori personalizzati basati su codice consentono di utilizzare la propria funzione AWS Lambda per valutare programmaticamente le prestazioni degli agenti, invece di utilizzare un LLM come giudice. Questo ti dà il pieno controllo sulla logica di valutazione: puoi implementare controlli deterministici, chiamare API esterne, eseguire regex matching, calcolare metriche personalizzate o applicare regole specifiche per l'azienda.

Prerequisiti

Per utilizzare valutatori personalizzati basati su codice, hai bisogno di:

  • Una funzione AWS Lambda implementata nella stessa regione delle risorse di valutazione. AgentCore

  • Un ruolo di esecuzione IAM che concede al servizio AgentCore Evaluations l'autorizzazione a richiamare la tua funzione Lambda.

  • La funzione Lambda deve restituire una risposta JSON conforme allo schema di risposta descritto in Response schema. Schema di risposta

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 di funzione Lambda

Nota

Il timeout massimo di runtime 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 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 sul codice.

evaluatorName

Stringa

Il nome del valutatore basato sul codice.

evaluationLevel

Stringa

Il livello di valutazione:TRACE,, oTOOL_CALL. SESSION

evaluationInput

Oggetto

Contiene l'intervallo delle sessioni per la valutazione.

evaluationInput.sessionSpans

List

La sessione si estende per la valutazione. 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 del target di valutazione. Presenti per le valutazioni a livello di traccia e a livello di strumento.

evaluationTarget.spanIds

List

Gli span ID del target di valutazione. Presente per le valutazioni a livello di strumento.

Schema di risposta

La 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

Sì

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

Sì

Stringa

Un codice che identifica l'errore.

errorMessage

Sì

Stringa

Una descrizione dell'errore leggibile dall'uomo.

Crea un valutatore basato sul codice

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

Parametri richiesti: nome univoco del valutatore, livello di valutazione (, TRACETOOL_CALL, oSESSION) e una configurazione del valutatore 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

Sì

—

L'ARN della funzione Lambda da invocare.

lambdaTimeoutInSeconds

No

60

Timeout in secondi per l'invocazione Lambda (1—300).

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

Esempio
AgentCore CLI
  1. 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
  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 sul codice

Una volta creato, utilizza il valutatore personalizzato basato su codice con l'EvaluateAPI nello stesso modo in cui useresti 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 degli obiettivi di valutazione

Puoi scegliere come target 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 campo. evaluationReferenceInputs Gli input di riferimento inclusi dipendono dal livello di valutazione:

Livello di valutazione Lambda riceve

SESSION

Tutti gli input di riferimento.

TRACE

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

TOOL_CALL

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

Nota

Per ulteriori informazioni sull'utilizzo delle valutazioni di Ground Truth, vedere Ground truth valuations.

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 a quella localeagentcore.json. Corri agentcore deploy a crearla nel tuo AWS account.

    Nota

    Eseguilo dall'interno di una cartella AgentCore del 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 bloccato automaticamente e non può essere modificato o eliminato finché la configurazione non viene disabilitata o eliminata. Per apportare modifiche al valutatore, disabilita prima la configurazione di valutazione online oppure clona il valutatore e crea una nuova configurazione.