Codebeispiele Anforderungsparameter Quelle der Sitzung Antwort Fehler

Batch-Auswertung starten

Starten Sie eine Batch-Auswertung, um Evaluatoren für mehrere Agentensitzungen auszuführen. Der Dienst erkennt Sitzungen anhand von CloudWatch Protokollen, führt jeden Evaluator für jede Sitzung aus und erzeugt aggregierte Ergebnisse.

Codebeispiele

Beispiel

AgentCore CLI

Die CLI logGroupNames wird automatisch aus der Projektkonfiguration aufgelöstserviceNames, wenn Sie Folgendes verwenden--runtime:


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

Mit optionalen Flags:


# 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

Standardmäßig startet der Befehl den Job und kehrt sofort zurück. An Block übergeben--wait, bis der Job einen Terminalstatus (COMPLETEDFAILED, oderSTOPPED) erreicht. Danach zeigt die CLI Durchschnittswerte pro Evaluator an und speichert die Ergebnisse unter. .cli/jobs/batch-eval-results/

agentcore run batch-evaluationunterstützt auch die folgenden Flags:

--wait— blockiert, bis der Job einen Terminalstatus erreicht.
--json— gibt maschinenlesbare JSON-Ausgabe aus.
--kms-key <arn>— verschlüsselt die Ergebnisse der Batch-Auswertung mit einem vom Kunden verwalteten KMS-Schlüssel.
--dataset <name>/--dataset-version <version>— ruft den Agenten mit Datensatzszenarien vor der Batch-Auswertung auf (lassen Sie die Version für eine lokale Datei weg oder verwenden Sie/). N DRAFT
--endpoint <name>— zielt auf einen bestimmten Laufzeitendpunkt ab (z. B.PROMPT_V1); standardmäßig wird dann die AGENTCORE_RUNTIME_ENDPOINT Umgebungsvariable verwendet. DEFAULT
--evaluator-arn <arns…>— Referenzbewerter nach ARN statt nach. -e

Die meisten Flags haben kurze Aliase: -r (--runtime), -e (--evaluator), -n (--name), -d (--lookback-days), -s (--session-ids) und -g (--ground-truth).

Um einen Job nach dem Start zu verwalten, führen Sie Run aus, agentcore stop batch-evaluation -i <id> um einen laufenden Job zu beenden und einen Jobdatensatz agentcore archive batch-evaluation -i <id> zu archivieren.

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))

Mit Sitzungs-ID-Filterung:


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()),
)

Mit Zeitbereichsfilterung:


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()),
)

Anforderungsparameter

Parameter	Typ	Erforderlich	Beschreibung
`batchEvaluationName`	Zeichenfolge	Ja	Ein Name für den Auftrag zur Batch-Auswertung. Muster: beginnt mit einem alphanumerischen Buchstaben und Unterstrichen, maximal 48 Zeichen.
`dataSourceConfig`	Objekt	Ja	Wo finde ich Agentensitzungen? Geben Sie eine `cloudWatchLogs` Quelle mit den Protokollgruppen und dem Dienstnamen für Ihren Agenten an. Weitere Informationen finden Sie unter Quelle der Sitzung weiter unten in diesem Dokument.
`evaluators`	Auflisten	Ja	Liste der Gutachter. Jeder Eintrag hat ein `evaluatorId` Feld (z. B.`Builtin.GoalSuccessRate`). Maximal 10 Gutachter.
`evaluationMetadata`	Objekt	Nein	Enthält `sessionMetadata` eine Liste mit Ground Truth- und Metadaten pro Sitzung. Maximal 500 Einträge.
`clientToken`	Zeichenfolge	Nein	Idempotenz-Token. Wenn Sie eine Anfrage mit demselben Client-Token erneut versuchen, gibt der Dienst den vorhandenen Job zurück, anstatt einen neuen zu erstellen.

Quelle der Sitzung

Der dataSourceConfig Parameter gibt den Speicherort der CloudWatch Protokolle an, an dem der Dienst Agentensitzungen erkennt.

Pflichtfelder

Feld	Typ	Description
`cloudWatchLogs.serviceNames`	Liste der Zeichenketten (genau 1)	Der Dienstname, der die Spuren Ihres Agenten in identifiziert CloudWatch. Konvention:`{RuntimeName}.DEFAULT`.
`cloudWatchLogs.logGroupNames`	Liste der Zeichenketten (1—5)	CloudWatch Gruppennamen protokollieren, in denen die Agententelemetrie gespeichert ist. Konvention:`/aws/bedrock-agentcore/runtimes/{agentId}-DEFAULT`.

Optionale Felder

Feld	Typ	Description
`cloudWatchLogs.filterConfig.sessionIds`	Liste von Zeichenfolgen	Bewerten Sie nur diese spezifischen Sitzungs-IDs. Wenn dieser Wert nicht angegeben wird, erkennt der Dienst alle Sitzungen in der Protokollgruppe.
`cloudWatchLogs.filterConfig.timeRange.startTime`	ISO 8601 Datum/Uhrzeit	Filtert Sitzungen, die nach dieser Zeit erstellt wurden.
`cloudWatchLogs.filterConfig.timeRange.endTime`	ISO 8601 Datum/Uhrzeit	Filtert Sitzungen, die vor diesem Zeitpunkt erstellt wurden.

Antwort

Feld	Typ	Description
`batchEvaluationId`	Zeichenfolge	Eindeutiger Bezeichner für die Batch-Auswertung.
`batchEvaluationArn`	Zeichenfolge	ARN der Chargenauswertung.
`batchEvaluationName`	Zeichenfolge	Der Name, den Sie angegeben haben.
`status`	Zeichenfolge	Ursprünglicher Status. Einer von:`PENDING`,`IN_PROGRESS`.
`evaluators`	Auflisten	Die verwendeten Gutachter.
`createdAt`	Zeitstempel	Wann der Job erstellt wurde.
`outputConfig`	Objekt	CloudWatch Protokolliert das Ziel für die Ergebnisse pro Sitzung.

Fehler

Fehler	HTTP-Status	Description
`ValidationException`	400	Ungültige Anforderungsparameter. Überprüfen Sie die Feldbeschränkungen und die erforderlichen Felder.
`AccessDeniedException`	403	Unzureichende Berechtigungen. Überprüfen Sie die IAM-Richtlinien.
`ConflictException`	409	Eine Batch-Auswertung mit demselben Client-Token mit unterschiedlichen Parametern ist bereits vorhanden.
`ThrottlingException`	429	Die Anforderungsrate wurde überschritten. Versuchen Sie es erneut mit exponentiellem Backoff.
`InternalServerException`	500	Service-side Fehler. Wiederholen Sie die Anforderung.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Erste Schritte

Holen Sie sich Ergebnisse der Batch-Auswertung