# Batch-Auswertung starten
<a name="batch-evaluations-start"></a>

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
<a name="start-batch-eval-examples"></a>

**Example**  
Die CLI `logGroupNames` wird automatisch aus der Projektkonfiguration aufgelöst`serviceNames`, 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 (`COMPLETED``FAILED`, oder`STOPPED`) erreicht. Danach zeigt die CLI Durchschnittswerte pro Evaluator an und speichert die Ergebnisse unter. `.cli/jobs/batch-eval-results/`  
 `agentcore run batch-evaluation`unterstü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.

```
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
<a name="start-batch-eval-params"></a>


| 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](#start-batch-eval-session-source) 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
<a name="start-batch-eval-session-source"></a>

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

### Pflichtfelder
<a name="start-batch-eval-session-source-required"></a>


| 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
<a name="start-batch-eval-session-source-optional"></a>


| 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
<a name="start-batch-eval-response"></a>


| 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
<a name="start-batch-eval-errors"></a>


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