Avvia la valutazione in batch

Avvia una valutazione in batch per eseguire i valutatori su più sessioni di agenti. Il servizio rileva le sessioni dai CloudWatch log, esegue ogni valutatore su ogni sessione e produce risultati aggregati.

Esempi di codice

Esempio

AgentCore CLI

La CLI si risolve logGroupNames automaticamente dalla configurazione del serviceNames progetto quando si utilizza: --runtime

agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate Builtin.Helpfulness Builtin.Faithfulness

Con flag opzionali:

# Custom name and lookback window
agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --name my_baseline_eval \
  --lookback-days 1

# Specific sessions
agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --session-ids session-abc123 session-def456

# With ground truth
agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate Builtin.Correctness \
  --ground-truth ground-truth.json

Per impostazione predefinita, il comando avvia il lavoro e ritorna immediatamente. Passa --wait al blocco finché il job non raggiunge lo stato terminale (COMPLETED,, oSTOPPED)FAILED, dopodiché la CLI mostra i punteggi medi per valutatore e salva i risultati in. .cli/jobs/batch-eval-results/

agentcore run batch-evaluationsupporta anche i seguenti flag:

• --wait— blocca finché il processo non raggiunge lo stato terminale.

• --json— emette un output JSON leggibile dalla macchina.

• --kms-key <arn>— crittografa i risultati della valutazione dei batch con una chiave KMS gestita dal cliente.

• --dataset <name>/--dataset-version <version>— richiama l'agente con scenari di set di dati prima della valutazione del batch (ometti la versione per un file locale o usa/). N DRAFT

• --endpoint <name>— mira a un endpoint di runtime specifico (ad esempio,PROMPT_V1); quindi, per impostazione predefinita, è la variabile di ambiente. AGENTCORE_RUNTIME_ENDPOINT DEFAULT

• --evaluator-arn <arns…​>— valutatori di riferimento tramite ARN anziché. -e

  La maggior parte dei flag ha alias brevi: -r (--runtime), (), -e (--evaluator), -n (--name), -d (--lookback-days), () e -s (--session-ids). -g --ground-truth

  Per gestire un processo dopo l'avvio, esegui agentcore stop batch-evaluation -i <id> per interrompere un processo in esecuzione e agentcore archive batch-evaluation -i <id> archiviare un record di lavoro.

AWS SDK (boto3)

import boto3
import uuid
import time
import json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

# All sessions in the log group
response = client.start_batch_evaluation(
    batchEvaluationName=f"baseline_eval_{uuid.uuid4().hex[:8]}",
    evaluators=[
        {"evaluatorId": "Builtin.GoalSuccessRate"},
        {"evaluatorId": "Builtin.Helpfulness"},
        {"evaluatorId": "Builtin.Faithfulness"},
    ],
    dataSourceConfig={
        "cloudWatchLogs": {
            "serviceNames": ["MyAgent.DEFAULT"],
            "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"],
        }
    },
    clientToken=str(uuid.uuid4()),
)

batch_eval_id = response["batchEvaluationId"]
print(f"Started: {batch_eval_id}")

# Poll until complete
while True:
    result = client.get_batch_evaluation(batchEvaluationId=batch_eval_id)
    status = result["status"]
    print(f"Status: {status}")

    if status in ("COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "STOPPED"):
        break
    time.sleep(30)

print(json.dumps(result, indent=4, default=str))

Con filtro degli ID di sessione:

response = client.start_batch_evaluation(
    batchEvaluationName=f"targeted-eval-{uuid.uuid4().hex[:8]}",
    evaluators=[
        {"evaluatorId": "Builtin.GoalSuccessRate"},
    ],
    dataSourceConfig={
        "cloudWatchLogs": {
            "serviceNames": ["MyAgent.DEFAULT"],
            "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"],
            "filterConfig": {
                "sessionIds": ["session-001", "session-002", "session-003"]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Con filtraggio dell'intervallo di tempo:

from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)
response = client.start_batch_evaluation(
    batchEvaluationName=f"weekly-eval-{uuid.uuid4().hex[:8]}",
    evaluators=[
        {"evaluatorId": "Builtin.GoalSuccessRate"},
    ],
    dataSourceConfig={
        "cloudWatchLogs": {
            "serviceNames": ["MyAgent.DEFAULT"],
            "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"],
            "filterConfig": {
                "timeRange": {
                    "startTime": (now - timedelta(days=7)).isoformat(),
                    "endTime": now.isoformat(),
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Parametri della richiesta

Parametro	Tipo	Campo obbligatorio	Descrizione
batchEvaluationName	Stringa	Sì	Un nome per il processo di valutazione del batch. Schema: inizia con una lettera alfanumerica e caratteri di sottolineatura, massimo 48 caratteri.
dataSourceConfig	Oggetto	Sì	Dove trovare le sessioni degli agenti. Specificate una cloudWatchLogs fonte con il nome del servizio dell'agente e i nomi esatti dei gruppi di log o i prefissi dei nomi dei gruppi di log. ConsultaOrigine della sessione qui di seguito.
evaluators	List	Sì	Elenco dei valutatori. Ogni voce ha un evaluatorId campo (ad esempio,Builtin.GoalSuccessRate). Massimo 10 valutatori.
evaluationMetadata	Oggetto	No	Contiene sessionMetadata un elenco di informazioni di base e metadati per sessione. Massimo 500 voci.
outputConfig	Oggetto	No	CloudWatch Destinazione opzionale per i risultati e le metriche dei punteggi per sessione. Specifica cloudWatchConfig a per scegliere il gruppo di log dei risultati e il namespace delle metriche. ConsultaOutput dei risultati qui di seguito.
clientToken	Stringa	No	Token di idempotenza. Se si riprova una richiesta con lo stesso token client, il servizio restituisce il job esistente anziché crearne uno nuovo.

Origine della sessione

Il dataSourceConfig parametro specifica la posizione dei CloudWatch log in cui il servizio rileva le sessioni degli agenti.

Campi obbligatori

Campo	Tipo	Description
cloudWatchLogs.serviceNames	Elenco di stringhe (esattamente 1)	Il nome del servizio che identifica le tracce del tuo agente in. CloudWatch Convenzione:{RuntimeName}.DEFAULT.
cloudWatchLogs.logGroupNames	Elenco di stringhe (1—5)	Un modo per selezionare i gruppi di log di input. Specificate i nomi esatti dei gruppi di CloudWatch log in cui è archiviata la telemetria degli agenti. Reciprocamente esclusivo con logGroupNamePrefixes.
cloudWatchLogs.logGroupNamePrefixes	Elenco di stringhe (1—5)	Un modo per selezionare i gruppi di log di input. Il servizio rileva le sessioni di ogni gruppo di log il cui nome inizia con uno di questi prefissi, quindi i gruppi di log corrispondenti appena creati vengono raccolti automaticamente. Reciprocamente esclusivo con logGroupNames.

Specificate esattamente uno tra o. logGroupNames logGroupNamePrefixes In entrambi i casi, serviceNames è necessario identificare le tracce dell'agente all'interno dei gruppi di log selezionati.

Se usi logGroupNamePrefixes per abbinare i gruppi di log AgentCore di Amazon Bedrock Runtime, assicurati che il runtime invii gli intervalli al gruppo di log dell'agente. Per gli agenti che utilizzano ancora il gruppo di aws/spans log condiviso, impostato UNIFIED_TRACES_DESTINATION_ENABLED=true sul runtime. Per ulteriori informazioni, consulta Span destination for agent hosted in Amazon Bedrock runtime AgentCore .

# Match input log groups by prefix instead of exact names
dataSourceConfig={
    "cloudWatchLogs": {
        "logGroupNamePrefixes": ["/aws/bedrock-agentcore/runtimes/MyAgent-"],
        "serviceNames": ["MyAgent.DEFAULT"]
    }
}

Campi facoltativi

Campo	Tipo	Description
cloudWatchLogs.filterConfig.sessionIds	Elenco di stringhe	Valuta solo questi ID di sessione specifici. Se omesso, il servizio rileva tutte le sessioni nel gruppo di log.
cloudWatchLogs.filterConfig.timeRange.startTime	Data/ora ISO 8601	Filtra le sessioni create dopo questo periodo.
cloudWatchLogs.filterConfig.timeRange.endTime	Data/ora ISO 8601	Filtra le sessioni create prima di questo orario.

Output dei risultati

Per impostazione predefinita, i risultati della valutazione in batch vengono inviati a un gruppo di log dedicato e gestito dal servizio. Da utilizzare outputConfig.cloudWatchConfig per controllare dove vengono scritti i risultati per sessione e quale namespace delle CloudWatch metriche riceve i punteggi di valutazione.

Scegli dove vengono scritti i risultati

• DEDICATED_LOG_GROUP(impostazione predefinita): scrive i risultati in un gruppo di log dei risultati dedicato. Se non lo impostilogGroupName, il servizio gestisce il gruppo per te. Per utilizzare il tuo gruppo, imposta logGroupName (vediUsa un gruppo di log di output personalizzato).

• SOURCE_LOG_GROUP— Scrive i risultati nello stesso gruppo di log da cui sono state lette le tracce dell'agente. Quando si utilizza questo valore, non impostarlologGroupName.

Usa un gruppo di log di output personalizzato

PerDEDICATED_LOG_GROUP, imposta per logGroupName scrivere i risultati in un gruppo di log a tua scelta. Un gruppo di log esistente viene utilizzato così com'è; se non esiste, il servizio lo crea, il che richiede la concessione del ruolo di esecuzione. logs:CreateLogGroup Il nome non può essere incluso nel /aws/bedrock-agentcore/evaluations/ namespace riservato al servizio, ad eccezione del gruppo predefinito gestito dal servizio.

# Write results back to the trace source log group
outputConfig={
    "cloudWatchConfig": {
        "resultDestination": "SOURCE_LOG_GROUP"
    }
}

# Write results to a custom dedicated log group
outputConfig={
    "cloudWatchConfig": {
        "resultDestination": "DEDICATED_LOG_GROUP",
        "logGroupName": "/my/team/batch-evaluation-results"
    }
}

Pubblica le metriche in un namespace personalizzato

Imposta metricsNamespace per pubblicare le metriche dei punteggi nel tuo CloudWatch namespace anziché. Bedrock-AgentCore/Evaluations Il valore non può iniziare con. AWS/

outputConfig={
    "cloudWatchConfig": {
        "metricsNamespace": "MyTeam/Evaluations"
    }
}

Risposta

Campo	Tipo	Description
batchEvaluationId	Stringa	Identificatore univoco per la valutazione del batch.
batchEvaluationArn	Stringa	ARN della valutazione del batch.
batchEvaluationName	Stringa	Il nome specificato.
status	Stringa	Stato iniziale. Uno dei:PENDING,IN_PROGRESS.
evaluators	List	I valutatori utilizzati.
createdAt	Time stamp	Quando è stato creato il lavoro.
outputConfig	Oggetto	CloudWatch destinazione per i risultati e le metriche dei punteggi per sessione.

Errori

Errore	Stato HTTP	Description
ValidationException	400	Parametri di richiesta non validi. Controlla i vincoli dei campi e i campi obbligatori.
AccessDeniedException	403	Autorizzazioni insufficienti. Verifica le politiche IAM.
ConflictException	409	Esiste già una valutazione in batch con lo stesso token client con parametri diversi.
ThrottlingException	429	Percentuale di richieste superata. Riprova con un backoff esponenziale.
InternalServerException	500	Service-side errore. Riprova la richiesta .