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:
-
Una funzione AWS Lambda distribuita nella stessa regione delle risorse di valutazione. AgentCore
-
Un ruolo di esecuzione IAM che concede al servizio AgentCore Evaluations l'autorizzazione a richiamare la funzione Lambda.
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 |
|---|---|---|
|
|
Stringa |
Versione dello schema del payload. Attualmente |
|
|
Stringa |
L'ID del valutatore basato su codice. |
|
|
Stringa |
Il nome del valutatore basato sul codice. |
|
|
Stringa |
Il livello di valutazione: |
|
|
Oggetto |
Contiene gli intervalli delle sessioni per la valutazione. |
|
|
List |
La sessione dura da valutare. Può essere troncato se il payload originale supera i 6 MB. |
|
|
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. |
|
|
Oggetto |
Identifica le tracce o gli intervalli specifici da valutare. Per i valutatori a livello di sessione, questo valore è. |
|
|
List |
Gli ID di traccia dell'obiettivo di valutazione. Presente per valutazioni a livello di traccia e di strumento. |
|
|
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 |
|---|---|---|---|
|
|
Sì |
Stringa |
Un'etichetta categorica per il risultato della valutazione (ad esempio, «PASS», «FAIL», «Good», «Poor»). |
|
|
No |
Numero |
Un punteggio numerico (ad esempio da 0,0 a 1,0). |
|
|
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 |
|---|---|---|---|
|
|
Sì |
Stringa |
Un codice che identifica l'errore. |
|
|
Sì |
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 |
|---|---|---|---|
|
|
Sì |
— |
L'ARN della funzione Lambda da richiamare. |
|
|
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
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
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 |
|---|---|
|
|
Tutti gli input di riferimento. |
|
|
Session-level input di riferimento più input di riferimento corrispondenti al traceID di destinazione. |
|
|
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
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.