Evaluator berbasis kode khusus
Evaluator berbasis kode khusus memungkinkan Anda menggunakan fungsi AWS Lambda Anda sendiri untuk mengevaluasi kinerja agen secara terprogram, alih-alih menggunakan LLM sebagai juri. Ini memberi Anda kontrol penuh atas logika evaluasi — Anda dapat menerapkan pemeriksaan deterministik, memanggil API eksternal, menjalankan pencocokan regex, menghitung metrik kustom, atau menerapkan aturan khusus bisnis apa pun.
Prasyarat
Untuk menggunakan evaluator berbasis kode khusus, Anda memerlukan:
-
Fungsi AWS Lambda yang digunakan di Wilayah yang sama dengan sumber daya Evaluasi Anda AgentCore .
-
Peran eksekusi IAM yang memberikan izin layanan AgentCore Evaluasi untuk menjalankan fungsi Lambda Anda.
Izin IAM
Peran eksekusi layanan Anda memerlukan izin tambahan berikut untuk menjalankan fungsi Lambda untuk evaluasi berbasis kode:
{ "Sid": "LambdaInvokeStatement", "Effect": "Allow", "Action": [ "lambda:InvokeFunction", "lambda:GetFunction" ], "Resource": "arn:aws:lambda:region:account-id:function:function-name" }
Kontrak fungsi Lambda
catatan
Batas waktu runtime maksimum untuk fungsi Lambda adalah 5 menit (300 detik). Ukuran payload input maksimum yang dikirim ke fungsi Lambda adalah 6 MB.
Skema masukan
Fungsi Lambda Anda menerima muatan JSON dengan struktur berikut:
{ "schemaVersion": "1.0", "evaluatorId": "my-evaluator-abc1234567", "evaluatorName": "MyCodeEvaluator", "evaluationLevel": "TRACE", "evaluationInput": { "sessionSpans": [...] }, "evaluationReferenceInputs": [], "evaluationTarget": { "traceIds": ["trace123"], "spanIds": ["span123"] } }
| Bidang | Tipe | Deskripsi |
|---|---|---|
|
|
String |
Versi skema payload. Saat ini |
|
|
String |
ID evaluator berbasis kode. |
|
|
String |
Nama evaluator berbasis kode. |
|
|
String |
Tingkat evaluasi: |
|
|
Objek |
Berisi rentang sesi untuk evaluasi. |
|
|
Daftar |
Sesi ini mencakup untuk mengevaluasi. Dapat terpotong jika muatan asli melebihi 6 MB. |
|
|
Daftar |
Input referensi diberikan kepada evaluator, disaring berdasarkan tingkat evaluasi. Lihat Menggunakan kebenaran dasar dalam evaluator berbasis kode. |
|
|
Objek |
Mengidentifikasi jejak atau bentang tertentu untuk dievaluasi. Untuk evaluator tingkat sesi, nilai ini adalah. |
|
|
Daftar |
ID jejak target evaluasi. Hadir untuk evaluasi tingkat jejak dan tingkat alat. |
|
|
Daftar |
ID rentang target evaluasi. Hadir untuk evaluasi tingkat alat. |
Skema respons
Fungsi Lambda Anda harus mengembalikan objek JSON yang cocok dengan salah satu dari dua format:
Respon sukses
{ "label": "PASS", "value": 1.0, "explanation": "All validation checks passed." }
| Bidang | Diperlukan | Tipe | Deskripsi |
|---|---|---|---|
|
|
Ya |
String |
Label kategoris untuk hasil evaluasi (misalnya, “LULUS”, “GAGAL”, “Baik”, “Buruk”). |
|
|
Tidak |
Bilangan |
Skor numerik (misalnya, 0,0 hingga 1,0). |
|
|
Tidak |
String |
Penjelasan yang dapat dibaca manusia tentang hasil evaluasi. |
Respon kesalahan
{ "errorCode": "VALIDATION_FAILED", "errorMessage": "Input spans missing required tool call attributes." }
| Bidang | Diperlukan | Tipe | Deskripsi |
|---|---|---|---|
|
|
Ya |
String |
Kode yang mengidentifikasi kesalahan. |
|
|
Ya |
String |
Deskripsi kesalahan yang dapat dibaca manusia. |
Buat evaluator berbasis kode
CreateEvaluatorAPI membuat evaluator berbasis kode dengan menentukan ARN fungsi Lambda dan batas waktu opsional.
Parameter yang diperlukan: Nama evaluator unik, tingkat evaluasi (TRACE,, atauSESSION)TOOL_CALL, dan konfigurasi evaluator berbasis kode yang berisi Lambda ARN.
Code-based konfigurasi evaluator:
{ "codeBased": { "lambdaConfig": { "lambdaArn": "arn:aws:lambda:region:account-id:function:function-name", "lambdaTimeoutInSeconds": 60 } } }
| Bidang | Diperlukan | Default | Deskripsi |
|---|---|---|---|
|
|
Ya |
— |
ARN dari fungsi Lambda untuk memanggil. |
|
|
Tidak |
60 |
Batas waktu dalam hitungan detik untuk pemanggilan Lambda (1—300). |
Contoh kode berikut menunjukkan cara membuat evaluator berbasis kode menggunakan pendekatan pengembangan yang berbeda.
contoh
Jalankan evaluasi sesuai permintaan dengan evaluator berbasis kode
Setelah dibuat, gunakan evaluator berbasis kode khusus dengan Evaluate API dengan cara yang sama seperti Anda menggunakan evaluator lainnya. Layanan ini menangani pemanggilan Lambda, fan-out paralel, dan pemetaan hasil secara otomatis.
contoh
Menggunakan target evaluasi
Anda dapat menargetkan jejak atau rentang tertentu, seperti halnya dengan LLM-based evaluator:
# 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"]} )
Menggunakan kebenaran dasar dalam evaluator berbasis kode
Ketika input referensi kebenaran dasar dikonfigurasi, fungsi Lambda Anda menerimanya di evaluationReferenceInputs lapangan. Masukan referensi yang disertakan tergantung pada tingkat evaluasi:
| Tingkat evaluasi | Lambda menerima |
|---|---|
|
|
Semua input referensi. |
|
|
Session-level input referensi ditambah input referensi yang cocok dengan traceID target. |
|
|
Session-level input referensi ditambah input referensi yang cocok dengan SpanID target. |
catatan
Untuk informasi lebih lanjut tentang menggunakan evaluasi kebenaran dasar, lihat Evaluasi kebenaran dasar.
Jalankan evaluasi online dengan evaluator berbasis kode
Anda dapat menggunakan evaluator berbasis kode khusus dalam konfigurasi evaluasi online untuk terus memantau lalu lintas langsung agen Anda. Lulus ID evaluator dalam evaluators daftar saat meneleponCreateOnlineEvaluationConfig.
contoh
catatan
Ketika konfigurasi evaluasi online yang merujuk evaluator berbasis kode diaktifkan, evaluator secara otomatis terkunci dan tidak dapat dimodifikasi atau dihapus sampai konfigurasi dinonaktifkan atau dihapus. Untuk membuat perubahan pada evaluator, nonaktifkan konfigurasi evaluasi online terlebih dahulu, atau kloning evaluator dan buat konfigurasi baru.