AgentLoop:Code Evaluator

Berbeda dengan evaluator Agent dan evaluator LLM yang bergantung pada model inference, evaluator Code tidak memiliki beban reasoning dan tidak mengonsumsi panggilan model. Ketika standar kualitas dapat diekspresikan dalam kode, evaluator Code umumnya lebih tepat digunakan dan sangat cocok untuk pemeriksaan pass-or-fail dalam jaring pengaman regresi.

Kasus penggunaan

Skenario umum untuk evaluator Code:

• Validasi output terstruktur — Penggunaan paling umum. Wajibkan agen mengembalikan JSON valid yang berisi bidang-bidang tertentu, dan beri skor 0 jika ada bidang yang hilang.

• Perbandingan jawaban numerik — Bandingkan jumlah, kuantitas, atau hasil perhitungan. Definisikan rentang toleransi dalam kode alih-alih meminta model menilai apakah suatu nilai cukup dekat.

• Pemindaian denylist — Pindai output untuk mencari kata sensitif dan frasa terlarang.

• Pemeriksaan panjang dan format output — Periksa panjang output, apakah output berisi tabel Markdown, atau apakah output diawali dengan awalan tertentu.

• Verifikasi urutan pemanggilan tool — Verifikasi bahwa tool yang diperlukan dipanggil dalam urutan yang diharapkan.

• Pemeriksaan kelengkapan sitasi — Verifikasi bahwa setiap nomor sitasi dalam jawaban dapat ditemukan di bagian teks yang diambil (retrieved passages).

Jika standar kualitas Anda bergantung pada penilaian subjektif atau semantik yang tidak dapat diekspresikan dalam kode, gunakan evaluator Agent atau evaluator LLM yang mengandalkan model inference.

Prasyarat

Code Evaluator saat ini tersedia di wilayah berikut:

Buat evaluator

1. Masuk ke Konsol AgentLoop.

2. Di panel navigasi sebelah kiri, klik Evaluation.

3. Di bilah navigasi tab di bagian atas halaman, klik tab Evaluator.

4. Di pojok kanan atas, klik Create Evaluator.

Pada formulir pembuatan, isi informasi dasar. Atur Evaluator Type menjadi Code. Nama tampilan, deskripsi, dan tag bersifat opsional. Tag memungkinkan Anda mengambil evaluator berdasarkan dimensi di daftar evaluator, sehingga berikan tag yang konsisten dan mudah difilter untuk evaluator Code Anda.

Setelah mengisi formulir, klik Create Evaluator untuk mengirimkannya. Halaman edit terbuka dengan dua tab: Basic Information dan Evaluation Code. Di tab Basic Information, nama evaluator dan jenis evaluator bersifat read-only, sedangkan bidang lain tetap dapat diedit. Konfigurasi inti dilakukan di tab Evaluation Code.

Tulis kode evaluasi

Di pojok kanan atas tab Evaluation Code, alihkan antara Python dan JavaScript. Kedua bahasa saling eksklusif, dan nama file di editor berubah menjadi code.py atau code.js sesuai pilihan. Klik Reset to Template untuk memuat templat default resmi sebagai titik awal.

Kode evaluasi Anda berjalan dalam sandbox. Batasan berikut berlaku:

• Dependencies — Implementasikan logika evaluasi hanya dengan pustaka standar bahasa pemrograman.

• Determinisme — Pertahankan kode dalam bentuk fungsi murni: input yang sama menghasilkan output yang sama.

• Isolasi — Kode tidak dapat mengakses layanan eksternal atau bergantung pada status lingkungan eksekusi.

Ini merupakan batasan praktis dari sandbox sekaligus prasyarat agar hasil evaluasi dapat direproduksi dan dipercaya.

Kontrak satu-satunya untuk kode Anda adalah sebagai berikut: definisikan fungsi bernama evaluate yang menerima bidang data sebagai parameter input dan mengembalikan objek yang berisi score dan explanation.

Templat default Python adalah sebagai berikut.

def evaluate(input, output, context=None):
    # Evaluasi satu record dan kembalikan skor serta penjelasan.
    return {
        "score": 0,
        "explanation": "Jelaskan mengapa skor ini diberikan",
    }

Templat default JavaScript adalah sebagai berikut.

function evaluate(input, output, context) {
  // Evaluasi satu record dan kembalikan skor serta penjelasan.
  return {
    score: 0,
    explanation: 'Jelaskan mengapa skor ini diberikan',
  }
}
module.exports = evaluate

Contoh kode

def evaluate(input, output, context=None):
    import json

    text = output if isinstance(output, str) else json.dumps(output, ensure_ascii=False)

    try:
        data = json.loads(text)
    except Exception as e:
        return {"score": 0, "explanation": "Output bukan JSON valid: %s" % e}

    if not isinstance(data, dict):
        return {"score": 0, "explanation": "Level teratas JSON output bukan objek"}

    missing = [k for k in ("title", "items") if k not in data]
    if missing:
        return {"score": 0, "explanation": "Bidang wajib tidak ditemukan: %s" % ", ".join(missing)}

    if not isinstance(data["items"], list) or len(data["items"]) == 0:
        return {"score": 0, "explanation": "items bukan array, atau merupakan array kosong"}

    return {"score": 1, "explanation": "JSON valid dan berisi title serta %d item" % len(data["items"])}

def evaluate(output, expected, tolerance=0.001):
    import re

    def to_number(v):
        if isinstance(v, (int, float)):
            return float(v)
        m = re.search(r"-?\d+(?:\.\d+)?", str(v).replace(",", ""))
        return float(m.group()) if m else None

    got, want = to_number(output), to_number(expected)

    if want is None:
        return {"score": 0, "explanation": "Tidak ditemukan angka di ground truth"}
    if got is None:
        return {"score": 0, "explanation": "Tidak ditemukan angka di output model"}

    denominator = abs(want) if want != 0 else 1.0
    diff = abs(got - want) / denominator

    if diff <= tolerance:
        return {"score": 1, "explanation": "Angka cocok: diharapkan %g, aktual %g" % (want, got)}
    return {"score": 0, "explanation": "Deviasi melebihi batas: diharapkan %g, aktual %g, kesalahan relatif %.2f%%" % (want, got, diff * 100)}

def evaluate(output, context=None, required_tools="search,summarize"):
    import json

    expected = [t.strip() for t in str(required_tools).split(",") if t.strip()]
    if not expected:
        return {"score": 1, "explanation": "Tidak ada tool wajib yang dideklarasikan, sehingga record lolos secara default"}

    raw = context if isinstance(context, str) else json.dumps(context or {}, ensure_ascii=False)

    called = set()
    for name in expected:
        if name in raw:
            called.add(name)

    missing = [t for t in expected if t not in called]
    hit_rate = len(called) / len(expected)

    if not missing:
        return {"score": 1, "explanation": "Semua tool wajib telah dipanggil: %s" % ", ".join(expected)}
    return {
        "score": round(hit_rate, 2),
        "explanation": "Pemanggilan tool tidak ditemukan: %s (%d dari %d cocok)" % (", ".join(missing), len(called), len(expected)),
    }

function evaluate(input, output, context = null) {
  const text = typeof output === 'string' ? output : JSON.stringify(output)
  const banned = ['guaranteed profit', 'guaranteed returns', 'one hundred percent', 'absolutely safe']

  let score = 100
  const reasons = []

  const hits = banned.filter((w) => text.includes(w))
  if (hits.length > 0) {
    score -= 40 * hits.length
    reasons.push(`Frasa terlarang ditemukan: ${hits.join(', ')}`)
  }

  if (text.trim().length < 20) {
    score -= 30
    reasons.push(`Respons terlalu pendek: hanya ${text.trim().length} karakter`)
  }

  if (!/risk disclaimer|for reference only/.test(text)) {
    score -= 20
    reasons.push('Disclaimer risiko tidak ditemukan')
  }

  score = Math.max(0, score)

  return {
    score,
    explanation: reasons.length === 0 ? 'Lolos semua pemeriksaan kualitas' : reasons.join('; '),
  }
}
module.exports = evaluate

Gunakan evaluator dalam tugas evaluasi

Setelah menyimpan evaluator, terapkan ke data nyata melalui tugas evaluasi. Di tab Evaluation Task modul Evaluation, klik Create Task. Alur ini terdiri dari dua langkah.

Langkah 1: Konfigurasi Data

Masukkan nama dan deskripsi tugas, lalu pilih sumber data. Sumber data yang didukung adalah jejak (traces), lintasan agen (agent trajectories), log, dan set data. Jika Anda memilih jejak, tentukan juga granularitas evaluasi: percakapan single-turn atau percakapan multi-putaran. Pilih apakah akan menyertakan input dan output dari giliran sebelumnya, serta persempit cakupan evaluasi menggunakan daftar drop-down Agent dan ekspresi filter data.

Langkah 2: Pilih Evaluator

Ini adalah langkah kritis. Area Preview Data di bagian atas halaman menampilkan semua bidang yang tersedia dari satu sampel nyata. Klik Switch Sample untuk memuat sampel lain dan memastikan bentuk data Anda. Di daftar evaluator di sebelah kiri, alihkan ke tab Custom dan pilih evaluator Code yang baru saja Anda buat. Area Field Mapping di sebelah kanan mencantumkan semua variabel evaluator tersebut. Pilih bidang data yang sesuai untuk setiap variabel.

Bidang yang tersedia untuk pemetaan bergantung pada sumber data. Untuk sumber data jejak, bidang berikut tersedia untuk pemetaan.

Setelah memetakan semua variabel wajib, kartu evaluator akan menampilkan tag Ready.

Jalankan uji pratinjau dan lihat hasilnya

Jalankan uji pratinjau sebelum menjalankan secara formal. Klik Run Test di bagian bawah halaman. Panel drawer terbuka di sebelah kanan dan menampilkan nilai bidang dari sampel saat ini. Klik Run Test di dalam drawer untuk menjalankan uji coba evaluator yang dipilih secara batch. Setelah eksekusi selesai, area Evaluation Results menampilkan status, skor, dan alasan evaluasi setiap evaluator. Langkah ini mengungkap sebagian besar masalah sebelum eksekusi formal menghabiskan kuota, seperti pemetaan bidang yang salah, kode yang melempar exception pada bentuk data nyata, atau skor yang tidak sesuai dengan konvensi yang Anda inginkan.

Setelah memastikan hasilnya, klik Create and Run untuk mengirimkan tugas. Halaman detail tugas memiliki tiga tab: Overview, Run Records, dan Evaluation Results.

• Run Records — Menampilkan jumlah total, tingkat penyelesaian, jumlah berhasil dan gagal, durasi, serta skor rata-rata setiap eksekusi.

• Evaluation Results — Menyediakan tampilan detail dan tampilan item data. Tampilan detail mencantumkan informasi berikut record per record: konten item data, skor, rentang skor, skor ternormalisasi, status, evaluator, durasi evaluasi, dan waktu pembuatan. Anda dapat memfilter hasil berdasarkan status, evaluator, rentang skor, dan jendela waktu.

Durasi eksekusi satu record evaluator Code biasanya sedikit lebih dari sepuluh detik. Record dalam satu tugas dieksekusi secara konkuren, sehingga tugas dengan sekitar 100 record membutuhkan waktu total sekitar satu menit.

Rekomendasi penulisan

Terapkan praktik berikut pada kode evaluasi Anda:

• Normalisasi tipe output sebelum pencocokan — Tipe aktual dari output tidak selalu string. trace.output dalam data jejak bisa berupa list atau dictionary. Normalisasi tipe sebelum menjalankan ekspresi reguler atau pencocokan substring. Di Python, gunakan json.dumps(output, ensure_ascii=False) if not isinstance(output, str) else output. Di JavaScript, gunakan typeof output === 'string' ? output : JSON.stringify(output).

• Ubah exception menjadi skor rendah eksplisit — Tangkap setiap operasi yang dapat memicu exception dan ubah menjadi skor rendah eksplisit disertai penjelasan, alih-alih membiarkan fungsi crash. Kegagalan parsing JSON, kegagalan konversi tipe, dan indeks di luar jangkauan adalah hal normal dalam data nyata. Mengungkapkannya sebagai skor nol disertai alasan jauh lebih bernilai daripada satu record kegagalan eksekusi.

• Eksternalisasi ambang batas sebagai parameter opsional — Ambang batas penilaian seperti tolerance, daftar tool yang diperlukan, dan panjang minimum menjadi variabel opsional saat Anda menuliskannya sebagai parameter fungsi dengan nilai default. Anda kemudian dapat mengganti nilainya per tugas, dan satu potongan kode dapat melayani beberapa tugas evaluasi. Tidak perlu membuat evaluator baru setiap kali Anda menyesuaikan parameter.

Langkah berikutnya

Gunakan nama evaluator untuk mereferensikan evaluator ini dalam panggilan API.