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 |
|---|---|---|
|
|
Stringa |
Versione dello schema del payload. Attualmente |
|
|
Stringa |
L'ID del valutatore basato sul codice. |
|
|
Stringa |
Il nome del valutatore basato sul codice. |
|
|
Stringa |
Il livello di valutazione: |
|
|
Oggetto |
Contiene l'intervallo delle sessioni per la valutazione. |
|
|
List |
La sessione si estende per la valutazione. 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 del target di valutazione. Presenti per le valutazioni a livello di traccia e a livello di strumento. |
|
|
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 |
|---|---|---|---|
|
|
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 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 |
|---|---|---|---|
|
|
Sì |
— |
L'ARN della funzione Lambda da invocare. |
|
|
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
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
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 |
|---|---|
|
|
Tutti gli input di riferimento. |
|
|
Session-level ingressi di riferimento più ingressi di riferimento corrispondenti al traceID di destinazione. |
|
|
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
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.