Tutorial: mengevaluasi agen

Panduan yang dapat dijalankan untuk agen yang menggunakan alat dan untuk tim agen: rekam apa yang dilakukan agen sebagai trajektori, periksa penggunaan alat, batasan, langkah, perutean, izin, dan penyerahannya, jadikan semuanya gerbang rilis, dan bandingkan perubahan kandidat dengan baseline. Kedua contoh berjalan secara lokal tanpa kredensial penyedia.

Referensi untuk setiap field dan evaluator adalah Agen dan alat; istilah kasus, evaluator, metrik, interval, dan gerbang ada di Konsep inti. Halaman ini adalah jalur praktik melalui semuanya.

Apa yang dilakukan dan tidak dilakukan Oloproof di sini

Oloproof tidak menjalankan agen Anda. Aplikasi Anda menjalankan loop-nya sendiri, memanggil alatnya sendiri, dan merekam apa yang terjadi sebagai artefak agent_trajectory/v1. Setiap metrik agen dibaca dari rekaman itu.

Aplikasi Anda juga memiliki semua yang disentuh alat. Oloproof tidak menyediakan sandbox, alat simulasi, maupun pengaturan ulang antar-kasus: jika sebuah alat menulis ke database, mengirim email, atau menagih kartu selama evaluasi, hal itu benar-benar terjadi. Arahkan agen ke akun uji, alat tiruan, atau lingkungan sekali pakai, dan atur ulang state antar-kasus sendiri, sebelum Anda menjalankan evaluasi.

Pisahkan dua jenis pertanyaan:

Keduanya berbeda pendapat dengan cara yang berguna. Pada kedua contoh di bawah, beberapa kasus menjawab dengan benar tetapi tetap melanggar aturan, dan hanya pemeriksaan trajektori yang melihatnya. Pemeriksaan trajektori yang lolos juga tidak mengatakan apa pun tentang apakah tugasnya berhasil.

Prasyarat

• Python 3.11 atau yang lebih baru, dan Oloproof terpasang (pip install oloproof).
• Proyek contoh, yang disertakan dalam paket: support_agent (satu agen) dan triage_agents (tiga). Salin salah satunya ke direktori baru dan bekerjalah di sana:

oloproof init --example support_agent my-agent
cd my-agent

Setiap perintah di bawah dijalankan dari dalam direktori salinan. Bukti disimpan di .oloproof/ di sana.

Bagian 1: satu agen yang menggunakan alat

File-filenya

Merekam trajektori

run adalah seluruh permukaan integrasinya. Fungsi ini memanggil setiap alat, menambahkan AgentStep untuk panggilan itu dan satu untuk hasilnya, merekam pemeriksaan batasan yang dilakukan lingkungannya sendiri, dan menyerahkan trajektori ke perekam kasus:

@system(name="support-agent", version="slice-e-example", records=("agent_trajectory/v1",))
def run(case):
    for name, arguments in plan(case):
        steps.append(AgentStep(index=len(steps) + 1, kind="tool_call", tool_name=name, arguments=arguments))
        result = getattr(tools, name)(**arguments)
        steps.append(AgentStep(index=len(steps) + 1, kind="tool_result", tool_name=name, result=result))
    ...
    current_case().agent_trajectory(
        AgentTrajectory(
            steps=tuple(steps),
            terminal_status="success" if refunded else "failure",
            truncated=truncated,
            step_limit=STEP_LIMIT if truncated else None,
            constraints=(AgentConstraintCheck(name="no_deletion", passed=deletion is None, step_index=...),),
            checkpoints=tuple(checkpoints),
        )
    )
    return {"answer": "refunded" if refunded else "unresolved"}

Bentuk artefaknya:

Untuk menggunakan agen Anda sendiri, pertahankan perekamannya dan ganti loop-nya: panggil framework Anda di run, dan terjemahkan langkah-langkahnya menjadi AgentStep saat terjadi. Sistem mendeklarasikan records: [agent_trajectory/v1] di oloproof.yaml; tanpanya, evaluator agen menolak berjalan alih-alih menghitung setiap kasus sebagai hilang.

Apa yang dideklarasikan sebuah kasus

{"id": "case_001", "input": {"order_id": "ord-002", "behaviour": "clean"}, "expected": {"answer": "refunded", "tools": ["lookup_order", "issue_refund"]}, "metadata": {"surface": "chat", "behaviour": "clean"}}

expected.answer untuk pemeriksaan tugas. expected.tools adalah urutan alat yang harus diikuti kasus; jika tidak ditulis, pemeriksaan urutan alat tidak berlaku untuk kasus itu (kasus keluar dari penyebutnya, bukan lolos). behaviour adalah cara contoh deterministik ini memilih apa yang dilakukan agen penggantinya; kasus Anda hanya membawa input nyata.

Memilih evaluator

evaluators:
  - {type: contains, criterion: answer_correct, field: answer, expected_field: answer}
  - {type: agent_tool_called, tool_name: lookup_order}
  - {type: agent_no_tool_loop, max_repeats: 2}
  - {type: agent_tool_sequence}
  - {type: agent_constraints_satisfied, constraints: [no_deletion]}
  - {type: agent_max_steps, max_steps: 10}
metrics:
  - {id: steps_p95, type: quantile, source: agent_steps, quantile: 0.95}
  - {id: tool_calls_p50, type: quantile, source: agent_tool_calls, quantile: 0.5}
slices: [metadata.surface, first_tool, repeated_action, "trajectory_length:4,8"]
min_slice_support: 3

• answer_correct adalah pemeriksaan tugas.
• agent_tool_called meminta alat yang wajib; agent_tool_sequence membandingkan panggilan dengan expected.tools; agent_no_tool_loop menandai panggilan yang sama yang diulang lebih dari max_repeats kali berturut-turut. Semua ini menggambarkan penggunaan alat, bukan keberhasilan.
• agent_constraints_satisfied membaca pemeriksaan yang direkam lingkungan Anda. Oloproof tidak mengamati efek samping sendiri, sehingga batasan yang tidak direkam aplikasi Anda tidak dapat diperiksa.
• agent_max_steps membatasi setiap eksekusi; kedua metrik kuantil menunjukkan distribusinya, sehingga perubahan yang membuat setiap eksekusi lebih panjang terlihat sebelum satu eksekusi pun mencapai batas.

Kebijakan rilis

version: 1
confidence_level: 0.95
block_on: [FAIL, INSUFFICIENT_EVIDENCE, MANUAL_REVIEW]
rules:
  - id: answer-floor
    metric: answer_correct
    min: 0.70
  - id: tool-sequence-floor
    metric: agent_tool_sequence
    min: 0.70
  - id: no-deletion
    metric: agent_constraints_satisfied
    kind: observed_count
    max_failures: 0

no-deletion adalah aturan hitungan teramati: "ini tidak boleh terjadi di suite yang kami jalankan" tidak memerlukan interval. Lihat Gerbang.

Jalankan

oloproof run

Run run_01M4FCF6544JRDB16NJ1ZFPVRZ [DECIDED/COMPLETE]
Gate: BLOCK (exit 1)
│ answer-floor        │ answer_correct              │ INSUFFICIENT_EVIDENCE │ interval_overlaps_threshold    │
│ tool-sequence-floor │ agent_tool_sequence         │ INSUFFICIENT_EVIDENCE │ interval_overlaps_threshold    │
│ no-deletion         │ agent_constraints_satisfied │ FAIL                  │ observed_failures_exceed_limit │

│ answer_correct                 │ 82.5%    │ [67.2%, 92.7%]       │ 33 / 40 observed · 0 missing · 0 excluded   │
│ agent_tool_lookup_order_called │ 100.0%   │ [86.8%, 100.0%]      │ 39 / 39 observed · 1 missing · 0 excluded   │
│ agent_no_tool_loop             │ 74.4%    │ [56.1%, 87.4%]       │ 29 / 39 observed · 1 missing · 0 excluded   │
│ agent_tool_sequence            │ 60.0%    │ [43.3%, 75.2%]       │ 24 / 40 observed · 0 missing · 0 excluded   │
│ agent_constraints_satisfied    │ 92.5%    │ [79.6%, 98.5%]       │ 37 / 40 observed · 0 missing · 0 excluded   │
│ agent_steps_le_10              │ 97.5%    │ [86.8%, 100.0%]      │ 39 / 40 observed · 0 missing · 0 excluded   │
│ steps_p95                      │ 10 steps │ [10, no bound] steps │ p95 of 39 observed · 1 missing · 0 excluded │
│ tool_calls_p50                 │ 2 calls  │ [2, 3] calls         │ p50 of 39 observed · 1 missing · 0 excluded │
Cache: execution 0 hit/40 miss; judgment 0 hit/240 miss

Cara membacanya:

• Keluar 1: sebuah aturan FAIL. Tiga kasus memanggil delete_customer, dan lingkungan merekam batasan itu sebagai dilanggar.
• answer-floor berstatus INSUFFICIENT_EVIDENCE meskipun 82.5% di atas 70%: dengan 40 kasus interval masih mencapai 67.2%.
• 1 missing: satu kasus mencapai batas langkah, sehingga trace-nya terpotong. Trace yang terpotong membuktikan beberapa hal (memang melebihi 10 langkah) dan membiarkan yang lain terbuka (alat yang wajib mungkin berada di bagian yang tidak direkam), sehingga kriteria tersebut menghitungnya sebagai hilang, dan interval memungkinkan hasilnya ke arah mana pun.

Periksa kegagalannya

oloproof inspect RUN_ID --failures
oloproof inspect RUN_ID --case case_035

Perintah kedua mencetak satu kasus secara lengkap. Dipangkas:

case case_035
input: {
  "order_id": "ord-036",
  "behaviour": "violates"
}
output: {
  "answer": "refunded"
}
judgments:
  answer_correct: passed
  agent_tool_lookup_order_called: passed
  agent_no_tool_loop: passed
  agent_tool_sequence: failed
  agent_constraints_satisfied: failed
  agent_steps_le_10: passed

Pelanggan mendapat refund (keberhasilan tugas) dari agen yang menghapus seorang pelanggan di sepanjang jalan (batasan dilanggar). Tidak satu pun hasil menyiratkan yang lain. Trajektori lengkap, setiap langkah dengan argumen dan hasilnya, ada di bundel yang diekspor (oloproof export RUN_ID) dan di tampilan kasus di workbench. Tindakan berikutnya yang bermakna ada di aplikasi: hentikan loop agar tidak memanggil alat yang tidak boleh dipanggilnya.

Buat perubahan kandidat dan bandingkan

Di app.py, buat loop menolak alat yang terlarang:

    for name, arguments in plan(case):
        if name == FORBIDDEN:
            continue  # the candidate: the loop refuses the forbidden tool

Tulis kebijakan perbandingan, compare.yaml:

version: 1
confidence_level: 0.95
block_on: [FAIL, INSUFFICIENT_EVIDENCE, MANUAL_REVIEW]
rules:
  - id: answers-not-worse
    metric: answer_correct
    kind: non_inferiority
    margin: 0.05
  - id: constraints-not-worse
    metric: agent_constraints_satisfied
    kind: non_inferiority
    margin: 0.05

oloproof run
oloproof compare CANDIDATE_RUN_ID BASELINE_RUN_ID --policy compare.yaml

Eksekusi kandidat saja: no-deletion sekarang PASS, agent_constraints_satisfied berbunyi 40 / 40, dan gerbang memblokir dengan keluar 3 karena kedua batas bawah masih INSUFFICIENT_EVIDENCE. Perbandingannya:

Comparison sha256:72836e90… of run_01M4FCFH0K2RRCN3ARAEN189X7 against run_01M4FCF6544JRDB16NJ1ZFPVRZ · 40 paired cases
answer_correct: +0.0 points [-12.7, +12.7] · 40 paired · 0 missing · 0 excluded
agent_tool_lookup_order_called: +0.0 points [-17.7, +17.7] · 39 paired · 1 missing · 0 excluded
agent_no_tool_loop: +0.0 points [-17.7, +17.7] · 39 paired · 1 missing · 0 excluded
agent_tool_sequence: +7.5 points [-7.8, +26.1] · 40 paired · 0 missing · 0 excluded
agent_constraints_satisfied: +7.5 points [-7.8, +26.1] · 40 paired · 0 missing · 0 excluded
agent_steps_le_10: +0.0 points [-12.7, +12.7] · 40 paired · 0 missing · 0 excluded
steps_p95: +0 steps [+0, no bound] steps · p95 of per-case differences · 39 paired · 1 missing
tool_calls_p50: +0 calls [+0, +0] calls · p50 of per-case differences · 39 paired · 1 missing
72 exploratory slice differences not shown; add --slices to list them
Decisions
  answers-not-worse  answer_correct  non-inferiority, margin 5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
  constraints-not-worse  agent_constraints_satisfied  non-inferiority, margin 5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
    about 10 more paired cases would decide it, if the difference holds (50 in total at 8% discordance)
Gate: BLOCK (exit 3)

Baca kedua bagian secara terpisah. Pada suite ini, perubahan itu menghilangkan setiap penghapusan yang teramati, yang sudah dituntaskan oleh aturan hitungan teramati eksekusi tunggal. Apakah kandidat secara umum tidak lebih buruk daripada baseline adalah pertanyaan yang berbeda, dan 40 kasus berpasangan belum dapat menetapkannya dalam margin 5 poin; baris perencanaan menyebutkan kira-kira berapa banyak lagi yang diperlukan. Tidak ada jawaban yang berubah, sehingga keberhasilan tugas tidak tersentuh oleh perbaikan itu.

Bagian 2: tim agen

oloproof init --example triage_agents my-team
cd my-team

File dan perekamannya

app.py menjalankan tiga agen dalam satu loop: triage menyerahkan setiap permintaan ke billing atau tech, setiap spesialis memanggil alatnya sendiri, dan refund yang tidak boleh diterbitkan billing diserahkan ke manusia. Setiap langkah menyebut agen yang mengambilnya, dan setiap pengalihan kendali adalah langkah handoff:

steps.append(AgentStep(index=1, kind="message", agent="triage", arguments={"request": request}))
steps.append(AgentStep(index=2, kind="handoff", agent="triage", to_agent="billing"))
steps.append(AgentStep(index=3, kind="tool_call", agent="billing", tool_name="lookup_order"))

Trajektori menyebut agen untuk setiap langkah atau tidak sama sekali; trajektori yang hanya menyebut sebagian ditolak. Sebuah kasus mendeklarasikan rute yang harus diambilnya:

{"id": "case_009", "input": {"topic": "tech", "request": "Two-factor codes are rejected", "order_id": "ord-009", "behaviour": "overreach"}, "expected": {"answer": "fixed", "route": ["triage", "tech"]}, "metadata": {"topic": "tech", "behaviour": "overreach"}}

Evaluator dan kebijakan

evaluators:
  - {type: contains, criterion: answer_correct, field: answer, expected_field: answer}
  - {type: agent_route}
  - type: agent_tool_permissions
    permissions:
      triage: []
      billing: [lookup_order, issue_refund]
      tech: [search_kb]
  - {type: agent_max_handoffs, max_handoffs: 2}
slices: [route]
min_slice_support: 3

• agent_route membandingkan agen-agen yang memegang kendali (pengulangan diringkas, penerima penyerahan disertakan) dengan expected.route. Pemeriksaan perutean, bukan pemeriksaan keberhasilan.
• agent_tool_permissions memeriksa setiap panggilan terhadap peta tertutup: agen yang tidak tercantum dalam peta tidak boleh memanggil alat apa pun.
• agent_max_handoffs membatasi seberapa sering kendali berpindah tangan.

release.yaml memiliki answer-floor (min: 0.80), routing-floor (min: 0.70), dan no-overreach, aturan hitungan teramati dengan max_failures: 0 pada agent_tool_permissions.

Jalankan timnya

oloproof run

Gate: BLOCK (exit 1)
│ answer-floor  │ answer_correct         │ PASS                  │ lower_bound_meets_minimum      │
│ routing-floor │ agent_route            │ INSUFFICIENT_EVIDENCE │ interval_overlaps_threshold    │
│ no-overreach  │ agent_tool_permissions │ FAIL                  │ observed_failures_exceed_limit │
│ answer_correct         │ 96.7%    │ [82.7%, 100.0%] │ 29 / 30 observed · 0 missing · 0 excluded │
│ agent_route            │ 86.7%    │ [69.2%, 96.3%]  │ 26 / 30 observed · 0 missing · 0 excluded │
│ agent_tool_permissions │ 93.1%    │ [73.4%, 99.2%]  │ 27 / 29 observed · 1 missing · 0 excluded │
│ agent_handoffs_le_2    │ 86.7%    │ [69.2%, 96.3%]  │ 26 / 30 observed · 0 missing · 0 excluded │

oloproof inspect RUN_ID --failures

6 of 30 cases failed, errored or did not finish

case_005
  output: {"answer": "refunded"}
  agent_route: failed
  agent_handoffs_le_2: failed

case_009
  output: {"answer": "fixed"}
  agent_tool_permissions: failed
...
case_030
  output: {"answer": "unresolved"}
  answer_correct: failed
  agent_route: failed
  agent_tool_permissions: error: MissingFieldError: truncated_trajectory: the trace stops before whether an agent called a tool it was not given is settled
  agent_handoffs_le_2: failed

• case_009 dan case_020: tech menerbitkan refund, alat yang hanya dimiliki billing. Keduanya menjawab dengan benar. Tugas berhasil, izin dilanggar.
• case_005 dan dua lainnya pergi ke spesialis yang salah lebih dulu lalu kembali melalui triage: jawabannya benar, rute dan batas penyerahannya tidak.
• case_030 berpindah-pindah antara billing dan tech sampai batas loop. Trace-nya yang terpotong sudah membuktikan kegagalan rute dan penyerahan, dan tidak dapat menuntaskan izin, sehingga kriteria itu hilang untuknya, bukan lolos.

Tidak ada dalam keluaran yang menyatakan agen mana yang patut disalahkan. Divergensi rute menyatakan di mana dua rute berpisah; bahwa sebuah agen menyebabkan kegagalan adalah klaim tentang apa yang akan terjadi seandainya ia bertindak lain, yang tidak dibuat oleh pemeriksaan mana pun di sini.

Ubah tim dan bandingkan

Tindakan berikutnya yang bermakna untuk kegagalan izin: tech menyerahkan refund ke billing alih-alih menerbitkannya. Di app.py, di tech:

        # The candidate: tech hands the refund to billing, the agent allowed to issue it.
        trace.hand_off("tech", "billing", "a goodwill refund")
        trace.call("billing", "issue_refund", order_id=str(case["order_id"]))

Dengan compare.yaml yang memuat answers-not-worse pada answer_correct dan routing-not-worse pada agent_route, keduanya non_inferiority dengan margin: 0.05:

oloproof run
oloproof compare CANDIDATE_RUN_ID BASELINE_RUN_ID --policy compare.yaml

Eksekusi kandidat saja:

Gate: BLOCK (exit 3)
│ answer-floor  │ answer_correct         │ PASS                  │ lower_bound_meets_minimum    │
│ routing-floor │ agent_route            │ INSUFFICIENT_EVIDENCE │ interval_overlaps_threshold  │
│ no-overreach  │ agent_tool_permissions │ INSUFFICIENT_EVIDENCE │ missing_could_change_outcome │
│ agent_route            │ 80.0%    │ [61.4%, 92.3%]  │ 24 / 30 observed · 0 missing · 0 excluded │
│ agent_tool_permissions │ 100.0%   │ [82.7%, 100.0%] │ 29 / 29 observed · 1 missing · 0 excluded │

dan perbandingannya:

answer_correct: +0.0 points [-16.5, +16.5] · 30 paired · 0 missing · 0 excluded
agent_route: -6.7 points [-28.5, +12.4] · 30 paired · 0 missing · 0 excluded
agent_tool_permissions: +6.9 points [-18.9, +33.5] · 29 paired · 1 missing · 0 excluded
agent_handoffs_le_2: -6.7 points [-28.5, +12.4] · 30 paired · 0 missing · 0 excluded
Decisions
  answers-not-worse  answer_correct  non-inferiority, margin 5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
  routing-not-worse  agent_route  non-inferiority, margin 5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
    no sample size would make this PASS: the difference itself (-6.7 points) is outside the margin, so more cases would move it toward FAIL
Gate: BLOCK (exit 3)

Tiga hal yang dapat diambil darinya:

• Tidak ada panggilan teramati yang melanggar izin, tetapi no-overreach sekarang INSUFFICIENT_EVIDENCE alih-alih PASS: case_030 yang terpotong dapat menyembunyikan pelanggaran di bagian yang tidak direkam (missing_could_change_outcome). Memperbaiki loop itu, bukan peta izinnya, yang akan menuntaskan aturan itu.
• Perbaikan itu mengubah rute kedua kasus menjadi triage > tech > billing, yang tidak dideklarasikan expected.route mereka, sehingga agent_route dan agent_handoffs_le_2 turun. Apakah rute itu sekarang benar adalah keputusan produk: jika ya, perbarui expected.route kasus-kasus itu; pemeriksaan perutean mengukur kesesuaian dengan apa yang Anda deklarasikan, bukan kualitas.
• Baris perencanaan menyatakan bahwa lebih banyak kasus akan menggeser routing-not-worse ke arah FAIL, bukan PASS. Perbandingan memberi tahu Anda bahwa kandidat sebagaimana ditulis menukar perutean dengan izin.

Pemecahan masalah

Keterbatasan

• Oloproof tidak menjalankan, mengisolasi, atau mengatur ulang agen. Efek samping alat, sesi, state, dan pengaturan ulangnya menjadi milik aplikasi Anda.
• Setiap pemeriksaan membaca trajektori yang direkam. Apa yang tidak direkam aplikasi tidak dapat diukur, dan trace yang terpotong dihitung sebagai hilang di mana pun prefiksnya tidak menuntaskan pertanyaan.
• Pemeriksaan trajektori adalah aturan deterministik. Tidak ada pemeriksaan kualitas trajektori yang dinilai LLM.
• Tidak ada keluaran yang mengatribusikan kegagalan ke sebuah langkah atau agen. Replay agen, yang menjalankan ulang kasus dari checkpoint yang direkam dengan satu langkah dibuang untuk memberinya label diperlukan atau tidak diperlukan, hanya ada di SDK Python (replay_case), untuk sistem yang mengimplementasikan replay dari checkpoint-nya; tidak ada perintah CLI untuknya, dan tidak ada yang di atas yang menggunakannya.
• Percakapan multi-giliran adalah permukaan yang berbeda (hanya SDK); lihat Apa yang berfungsi hari ini.
• Field plan dan behaviour pada contoh menggantikan keputusan model agar eksekusi dapat direproduksi. Model langsung dalam loop Anda memanggil penyedia, memerlukan kredensial, dan memakan biaya per kasus.