Sampel Kode Permintaan parameter Sumber sesi Hasil keluaran Respons Kesalahan

Mulai evaluasi batch

Mulai evaluasi batch untuk menjalankan evaluator terhadap beberapa sesi agen. Layanan menemukan sesi dari CloudWatch Log, menjalankan setiap evaluator terhadap setiap sesi, dan menghasilkan hasil agregat.

Sampel Kode

contoh

AgentCore CLI

CLI diselesaikan serviceNames dan secara logGroupNames otomatis dari konfigurasi proyek saat Anda menggunakan: --runtime


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

Dengan bendera opsional:


# 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

Secara default perintah memulai pekerjaan dan segera kembali. L --wait ulus ke blok hingga pekerjaan mencapai status terminal (COMPLETED,FAILED, atauSTOPPED), setelah itu CLI menampilkan skor rata-rata per evaluator dan menyimpan hasil ke. .cli/jobs/batch-eval-results/

agentcore run batch-evaluationjuga mendukung bendera berikut:

--wait— memblokir sampai pekerjaan mencapai status terminal.
--json— memancarkan output JSON yang dapat dibaca mesin.
--kms-key <arn>— mengenkripsi hasil evaluasi batch dengan kunci KMS yang dikelola pelanggan.
--dataset <name>/--dataset-version <version>— panggil agen dengan skenario dataset sebelum evaluasi batch (hilangkan versi untuk file lokal, atau gunakanN/DRAFT).
--endpoint <name>— menargetkan titik akhir runtime tertentu (misalnya,PROMPT_V1); default ke variabel AGENTCORE_RUNTIME_ENDPOINT lingkungan, laluDEFAULT.
--evaluator-arn <arns…>— evaluator referensi oleh ARN alih-alih-e.

Sebagian besar flag memiliki alias pendek: -r (--runtime), (), -e (--evaluator), -n (--name), -d (), (--lookback-days), -s (--session-ids), dan -g (--ground-truth).

Untuk mengelola pekerjaan setelah dimulai, jalankan agentcore stop batch-evaluation -i <id> untuk menghentikan pekerjaan yang sedang berjalan dan agentcore archive batch-evaluation -i <id> mengarsipkan catatan pekerjaan.

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

Dengan pemfilteran ID sesi:


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

Dengan penyaringan rentang waktu:


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

Permintaan parameter

Parameter	Tipe	Diperlukan	Deskripsi
`batchEvaluationName`	Tali	Ya	Nama untuk pekerjaan evaluasi batch. Pola: dimulai dengan huruf, alfanumerik dan garis bawah, maks 48 karakter.
`dataSourceConfig`	Objek	Ya	Di mana menemukan sesi agen. Tentukan `cloudWatchLogs` sumber dengan nama layanan agen Anda dan nama grup log yang tepat atau awalan nama grup log. Lihat Sumber sesi di bawah ini.
`evaluators`	Daftar	Ya	Daftar evaluator. Setiap entri memiliki `evaluatorId` bidang (misalnya,`Builtin.GoalSuccessRate`). Maksimal 10 evaluator.
`evaluationMetadata`	Objek	Tidak	Ber `sessionMetadata` isi, daftar kebenaran dasar per sesi dan metadata. Maksimal 500 entri.
`outputConfig`	Objek	Tidak	CloudWatch Tujuan opsional untuk hasil per sesi dan metrik skor. Tentukan a `cloudWatchConfig` untuk memilih grup log hasil dan namespace metrik. Lihat Hasil keluaran di bawah ini.
`clientToken`	String	Tidak	Token Idempotensi. Jika Anda mencoba lagi permintaan dengan token klien yang sama, layanan mengembalikan pekerjaan yang ada alih-alih membuat yang baru.

Sumber sesi

dataSourceConfigParameter menentukan lokasi CloudWatch Logs tempat layanan menemukan sesi agen.

Bidang wajib

Bidang	Tipe	Deskripsi
`cloudWatchLogs.serviceNames`	Daftar string (tepatnya 1)	Nama layanan yang mengidentifikasi jejak agen Anda CloudWatch. Konvensi:`{RuntimeName}.DEFAULT`.
`cloudWatchLogs.logGroupNames`	Daftar string (1—5)	Salah satu cara untuk memilih grup log input. Tentukan nama grup CloudWatch log yang tepat tempat telemetri agen disimpan. Saling eksklusif dengan`logGroupNamePrefixes`.
`cloudWatchLogs.logGroupNamePrefixes`	Daftar string (1—5)	Salah satu cara untuk memilih grup log input. Layanan menemukan sesi dari setiap grup log yang namanya dimulai dengan salah satu awalan ini, sehingga grup log yang cocok yang baru dibuat diambil secara otomatis. Saling eksklusif dengan`logGroupNames`.

Tentukan dengan tepat salah satu logGroupNames ataulogGroupNamePrefixes. Dalam kedua kasus, serviceNames diperlukan untuk mengidentifikasi jejak agen Anda dalam grup log yang dipilih.

Jika digunakan logGroupNamePrefixes untuk mencocokkan grup log AgentCore Runtime Amazon Bedrock, pastikan runtime mengirimkan rentang ke grup log agen itu sendiri. Untuk agen yang masih menggunakan grup aws/spans log bersama, atur UNIFIED_TRACES_DESTINATION_ENABLED=true pada runtime. Untuk informasi selengkapnya, lihat Tujuan rentang untuk agen yang dihosting di AgentCore runtime Amazon Bedrock.


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

Bidang opsional

Bidang	Tipe	Deskripsi
`cloudWatchLogs.filterConfig.sessionIds`	Daftar string	Evaluasi hanya ID sesi spesifik ini. Ketika dihilangkan, layanan menemukan semua sesi dalam grup log.
`cloudWatchLogs.filterConfig.timeRange.startTime`	Tanggal waktu ISO 8601	Sesi filter dibuat setelah waktu ini.
`cloudWatchLogs.filterConfig.timeRange.endTime`	Tanggal waktu ISO 8601	Sesi filter dibuat sebelum waktu ini.

Hasil keluaran

Secara default, hasil evaluasi batch masuk ke grup log khusus yang dikelola layanan. Gunakan outputConfig.cloudWatchConfig untuk mengontrol di mana hasil per sesi ditulis dan namespace CloudWatch metrik mana yang menerima skor evaluasi.

Pilih di mana hasil ditulis

DEDICATED_LOG_GROUP(default) — Menulis hasil ke grup log hasil khusus. Jika Anda tidak menyet logGroupName el, layanan akan mengelola grup untuk Anda. Untuk menggunakan grup Anda sendiri, atur logGroupName (lihatMenggunakan grup log keluaran kustom).
SOURCE_LOG_GROUP— Menulis hasil kembali ke grup log yang sama tempat pelacakan agen dibaca. Saat Anda menggunakan nilai ini, jangan aturlogGroupName.

Menggunakan grup log keluaran kustom

UntukDEDICATED_LOG_GROUP, atur logGroupName untuk menulis hasil ke grup log yang Anda pilih. Grup log yang ada digunakan apa adanya; jika tidak ada, layanan membuatnya, yang memerlukan peran eksekusi untuk diberikan. logs:CreateLogGroup Nama tidak dapat berada di bawah /aws/bedrock-agentcore/evaluations/ namespace reservasi layanan, selain dari grup default yang dikelola layanan.


# 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"
    }
}

Publikasikan metrik ke namespace kustom

Setel metricsNamespace untuk menerbitkan metrik skor di bawah CloudWatch namespace Anda sendiri, bukan. Bedrock-AgentCore/Evaluations Nilai tidak bisa dimulai denganAWS/.


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

Respons

Bidang	Tipe	Deskripsi
`batchEvaluationId`	String	Pengidentifikasi unik untuk evaluasi batch.
`batchEvaluationArn`	String	ARN dari evaluasi batch.
`batchEvaluationName`	String	Nama yang Anda tentukan.
`status`	String	Status awal. Salah satu dari:`PENDING`,`IN_PROGRESS`.
`evaluators`	Daftar	Evaluator yang digunakan.
`createdAt`	Stempel waktu	Ketika pekerjaan itu diciptakan.
`outputConfig`	Objek	CloudWatch tujuan untuk hasil per sesi dan metrik skor.

Kesalahan

Kesalahan	Status HTTP	Deskripsi
`ValidationException`	400	Parameter permintaan tidak valid. Periksa batasan bidang dan bidang wajib.
`AccessDeniedException`	403	Izin tidak mencukupi. Verifikasi kebijakan IAM.
`ConflictException`	409	Evaluasi batch dengan token klien yang sama sudah ada dengan parameter yang berbeda.
`ThrottlingException`	429	Tingkat permintaan terlampaui. Coba lagi dengan mundur eksponensial.
`InternalServerException`	500	Service-side kesalahan. Coba lagi permintaannya.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Memulai

Dapatkan hasil evaluasi batch