Eğitim: bir ajanı değerlendirme

Araç kullanan bir ajan ve bir ajan ekibi için çalıştırılabilir bir anlatım: ajanın yaptığını bir yörünge olarak kaydedin, araç kullanımını, kısıtlarını, adımlarını, yönlendirmesini, izinlerini ve devirlerini denetleyin, bir sürümü bunlara göre kapıdan geçirin ve bir aday değişikliği temelle karşılaştırın. İki örnek de sağlayıcı kimlik bilgisi olmadan yerelde çalışır.

Her alanın ve değerlendiricinin başvurusu Ajanlar ve araçlar sayfasıdır; vaka, değerlendirici, metrik, aralık ve kapı terimleri Temel kavramlar sayfasındadır. Bu sayfa onların içinden geçen uygulamalı yoldur.

Oloproof burada neyi yapar, neyi yapmaz

Oloproof ajanınızı sürmez. Uygulamanız kendi döngüsünü çalıştırır, kendi araçlarını çağırır ve olanları bir agent_trajectory/v1 yapıtı olarak kaydeder. Her ajan metriği bu kayıttan okunur.

Araçların dokunduğu her şeyin sahibi de uygulamanızdır. Oloproof yalıtılmış ortam, benzetilmiş araç ya da vakalar arasında sıfırlama sağlamaz: bir değerlendirme sırasında bir araç bir veritabanına yazar, bir e-posta gönderir ya da bir karttan ödeme alırsa, bunu gerçekten yapar. Bir değerlendirme çalıştırmadan önce ajanı test hesaplarına, taklit araçlara ya da atılabilir bir ortama yöneltin ve vakalar arasında durumu kendiniz sıfırlayın.

İki tür soruyu ayrı tutun:

Yararlı biçimlerde ayrışırlar. Aşağıdaki iki örnekte de bazı vakalar doğru yanıt verir ama yine de bir kuralı çiğner ve bunu yalnızca bir yörünge denetimi görür. Geçen bir yörünge denetimi de görevin başarılı olup olmadığı hakkında hiçbir şey söylemez.

Ön koşullar

• Python 3.11 veya üstü ve kurulu Oloproof (pip install oloproof).
• Paketle birlikte gelen örnek projeler: support_agent (tek ajan) ve triage_agents (üç ajan). Birini yeni bir dizine kopyalayın ve orada çalışın:

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

Aşağıdaki her komut kopyalanan dizinin içinden çalışır. Kanıt orada .oloproof/ içinde saklanır.

Bölüm 1: araç kullanan tek bir ajan

Dosyalar

Yörüngeyi kaydetme

run entegrasyon yüzeyinin tamamıdır. Her aracı çağırır, çağrı için bir AgentStep ve sonucu için bir tane ekler, kendi ortamının yaptığı kısıt denetimlerini kaydeder ve yörüngeyi vaka kaydedicisine verir:

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

Yapıtın biçimi:

Kendi ajanınızı kullanmak için kaydı tutun ve döngüyü değiştirin: run içinde çatınızı çağırın ve adımlarını oldukları anda AgentStep biçimine çevirin. Sistem oloproof.yaml içinde records: [agent_trajectory/v1] bildirir; bu olmadan ajan değerlendiricileri her vakayı eksik saymak yerine çalışmayı reddeder.

Bir vaka neyi bildirir

{"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 görev denetimi içindir. expected.tools vakanın izlemesi gereken araç dizisidir; onu çıkarırsanız araç dizisi denetimleri vakaya uygulanmaz (vaka geçmek yerine paydalarından çıkar). behaviour, bu deterministik örneğin yedek ajanının ne yapacağını seçme yoludur; sizin vakalarınız yalnızca gerçek girdiler taşır.

Değerlendiricileri seçme

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 görev denetimidir.
• agent_tool_called gerekli bir aracı ister; agent_tool_sequence çağrıları expected.tools ile karşılaştırır; agent_no_tool_loop aynı çağrının art arda max_repeats defadan fazla tekrarlanmasını işaretler. Bunlar başarıyı değil araç kullanımını tarif eder.
• agent_constraints_satisfied ortamınızın kaydettiği denetimleri okur. Oloproof yan etkileri kendisi gözlemlemez, bu yüzden uygulamanızın kaydetmediği bir kısıt denetlenemez.
• agent_max_steps her çalıştırmayı sınırlar; iki çeyreklik metriği dağılımı gösterir, böylece her çalıştırmayı uzatan bir değişiklik, herhangi bir çalıştırma sınıra ulaşmadan önce görünür olur.

Sürüm politikası

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 bir gözlenen sayı kuralıdır: "çalıştırdığımız pakette bu olmamalı" bir aralık gerektirmez. Bkz. Kapı denetimi.

Çalıştırın

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

Nasıl okunur:

• 1 çıkışı: bir kural FAIL oldu. Üç vaka delete_customer çağırdı ve ortam kısıtı çiğnenmiş olarak kaydetti.
• answer-floor, %82,5 %70'in üzerinde olsa da INSUFFICIENT_EVIDENCE olur: 40 vakayla aralık hâlâ %67,2'ye uzanır.
• 1 missing: bir vaka adım sınırına ulaştı, bu yüzden izi kesiktir. Kesik bir iz bazı şeyleri kanıtlar (10 adımı aştı) ve bazılarını açık bırakır (gerekli bir araç kaydedilmeyen kısımda olabilir), bu yüzden o kriterler onu eksik sayar ve aralık onun iki yöne de gitmiş olmasına izin verir.

Başarısızlıkları inceleyin

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

İkincisi bir vakayı tam olarak yazdırır. Kısaltılmış:

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

Müşteri iadeyi (görev başarısı), yol boyunca bir müşteriyi silen bir ajandan (çiğnenmiş bir kısıt) aldı. İki sonuçtan hiçbiri diğerini gerektirmez. Tam yörünge, argümanları ve sonucuyla her adım, dışa aktarılan pakette (oloproof export RUN_ID) ve çalışma tezgâhındaki vaka görünümündedir. Anlamlı sonraki eylem uygulamadadır: döngünün asla çağırmaması gereken bir aracı çağırmasını durdurun.

Bir aday değişiklik yapın ve karşılaştırın

app.py içinde döngünün yasak aracı reddetmesini sağlayın:

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

Bir karşılaştırma politikası yazın, 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

Yalnızca aday çalıştırma: no-deletion artık PASS olur, agent_constraints_satisfied 40 / 40 gösterir ve iki taban hâlâ INSUFFICIENT_EVIDENCE olduğu için kapı 3 çıkışıyla engeller. Karşılaştırma:

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)

İki yarıyı ayrı okuyun. Bu pakette değişiklik gözlenen her silmeyi kaldırdı; bunu tek çalıştırmalık gözlenen sayı kuralı zaten karara bağlar. Adayın genel olarak temelden kötü olmadığı ise ayrı bir sorudur ve 40 eşleştirilmiş vaka bunu henüz 5 puanlık bir marj içinde ortaya koyamaz; planlama satırı kabaca kaç tane daha gerektiğini söyler. Hiçbir yanıt değişmedi, bu yüzden düzeltme görev başarısına dokunmadı.

Bölüm 2: bir ajan ekibi

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

Dosyalar ve kayıt

app.py üç ajanı tek bir döngüde çalıştırır: triage her talebi billing ya da tech ajanına verir, her uzman kendi araçlarını çağırır ve billing'in yapamayacağı bir iade bir kişiye devredilir. Her adım onu atan ajanı adlandırır ve kontrolün her devri bir handoff adımıdır:

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

Bir yörünge ya her adımın ajanını adlandırır ya da hiçbirininkini; yalnızca bazılarınınkini adlandıran bir yörünge reddedilir. Bir vaka izlemesi gereken rotayı bildirir:

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

Değerlendiriciler ve politika

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, kontrolü elinde tutan ajanları (tekrarlar birleştirilmiş, bir devrin alıcısı dahil) expected.route ile karşılaştırır. Bir başarı denetimi değil, bir yönlendirme denetimidir.
• agent_tool_permissions her çağrıyı kapalı bir haritaya karşı denetler: haritanın listelemediği bir ajan hiçbir aracı çağıramaz.
• agent_max_handoffs kontrolün ne sıklıkla el değiştirdiğini sınırlar.

release.yaml içinde answer-floor (min: 0.80), routing-floor (min: 0.70) ve agent_tool_permissions üzerinde max_failures: 0 olan bir gözlenen sayı kuralı no-overreach vardır.

Ekibi çalıştırın

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 ve case_020: tech bir iade yaptı; bu yalnızca billing ajanının sahip olduğu bir araçtır. İkisi de doğru yanıt verdi. Görev başarısı, çiğnenmiş izin.
• case_005 ve iki vaka daha önce yanlış uzmana gitti ve triage üzerinden geri döndü: yanıt doğru, rota ve devir sınırı değil.
• case_030, döngünün sınırına kadar billing ile tech arasında gidip geldi. Kesik izi rota ve devir başarısızlıklarını zaten kanıtlar ve izinleri karara bağlayamaz, bu yüzden o kriter onun için geçmiş değil eksiktir.

Çıktıdaki hiçbir şey hangi ajanın suçlu olduğunu söylemez. Bir rota ayrışması iki rotanın nerede ayrıldığını söyler; bir ajanın bir başarısızlığa neden olduğu ise, farklı davransaydı ne olacağı hakkında bir iddiadır ve buradaki hiçbir denetim böyle bir iddiada bulunmaz.

Ekibi değiştirin ve karşılaştırın

İzin başarısızlıkları için anlamlı sonraki eylem: tech bir iadeyi yapmak yerine onu billing ajanına devreder. app.py içinde, tech içinde:

        # 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"]))

answer_correct üzerinde answers-not-worse ve agent_route üzerinde routing-not-worse içeren, ikisi de margin: 0.05 ile non_inferiority olan bir compare.yaml ile:

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

Yalnızca aday çalıştırma:

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 │

ve karşılaştırma:

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)

Buradan çıkarılacak üç şey:

• Gözlenen hiçbir çağrı bir izni çiğnemedi, ama no-overreach artık PASS değil INSUFFICIENT_EVIDENCE: kesik case_030, kaydedilmeyen kısımda bir ihlali gizliyor olabilir (missing_could_change_outcome). Kuralı karara bağlayacak olan izin haritasını değil o döngüyü düzeltmektir.
• Düzeltme iki vakanın rotasını, onların expected.route değerinin bildirmediği triage > tech > billing olarak değiştirdi, bu yüzden agent_route ve agent_handoffs_le_2 düştü. Bu rotanın artık doğru olup olmadığı bir ürün kararıdır: doğruysa vakaların expected.route değerini güncelleyin; bir yönlendirme denetimi kaliteyi değil, bildirdiğinize uygunluğu ölçer.
• Planlama satırı, daha fazla vakanın routing-not-worse kuralını PASS'e değil FAIL'e doğru iteceğini söyler. Karşılaştırma size, yazıldığı haliyle adayın izinler karşılığında yönlendirmeden ödün verdiğini söylüyor.

Sorun giderme

Sınırlamalar

• Oloproof bir ajanı sürmez, yalıtmaz ya da sıfırlamaz. Araç yan etkileri, oturumlar, durum ve bunların sıfırlanması uygulamanıza aittir.
• Her denetim kaydedilen yörüngeyi okur. Uygulamanın kaydetmediği ölçülemez ve kesik bir iz, başlangıç kısmının soruyu karara bağlamadığı her yerde eksik sayılır.
• Yörünge denetimleri deterministik kurallardır. LLM ile değerlendirilen bir yörünge kalitesi denetimi yoktur.
• Hiçbir çıktı bir başarısızlığı bir adıma ya da bir ajana yüklemez. Bir vakayı, bir adım çıkarılmış olarak kaydedilmiş bir kontrol noktasından yeniden çalıştırıp o adımı gerekli ya da gereksiz olarak etiketleyen ajan yeniden oynatma, yalnızca Python SDK'da (replay_case), kontrol noktalarından yeniden oynatmayı uygulayan bir sistem için vardır; bunun için bir CLI komutu yoktur ve yukarıdaki hiçbir şey onu kullanmaz.
• Çok turlu konuşmalar farklı bir yüzeydir (yalnızca SDK); bkz. Bugün neler çalışıyor.
• Örneklerin plan ve behaviour alanları, çalıştırmalar yeniden üretilebilir olsun diye bir modelin kararlarının yerine geçer. Döngünüzdeki canlı bir model bir sağlayıcıyı çağırır, kimlik bilgisi gerektirir ve vaka başına para tutar.