指南

教學：評估一個代理

一份針對使用工具的代理和代理團隊的可執行演練：把代理做了什麼記錄為一條軌跡，檢查它的工具使用、約束、步數、路由、權限和交接，依據它們對發布做閘門，並把候選變更與基準進行比較。兩個範例都在本機執行，無需提供者憑據。

每個欄位和評估器的參考見代理與工具；案例、評估器、指標、區間和閘門這些術語在核心概念中。本頁是貫穿它們的動手路線。

Oloproof 在這裡做什麼、不做什麼

Oloproof 不驅動你的代理。你的應用執行它自己的循環，呼叫它自己的工具，並把發生的事情記錄為一個 agent_trajectory/v1 產物。每個代理指標都是從這份記錄中讀出來的。

工具觸及的一切也都由你的應用負責。Oloproof 不提供沙箱、不提供模擬工具，也不在案例之間重置：如果某個工具在評估過程中寫入資料庫、發送郵件或扣款，它就真的會這麼做。在執行評估之前，把代理指向測試帳號、樁工具或一個用後即棄的環境，並自己在案例之間重置狀態。

把兩類問題分開：

問題	由誰檢查	範例
使用者是否得到了正確的結果？（任務成功）	輸出檢查，例如 contains，或評審	answer_correct
代理在過程中的行為是否符合允許的範圍？	軌跡檢查：工具選擇、順序、循環、約束、步數、路由、權限、交接	agent_constraints_satisfied、agent_route

它們會以有用的方式產生分歧。在下面兩個範例中，都有一些案例回答正確卻仍然違反了規則，而只有軌跡檢查能看到這一點。反過來，軌跡檢查通過也說明不了任務是否成功。

前提條件

Python 3.11 或更高版本，並已安裝 Oloproof（pip install oloproof）。
範例專案，它們隨軟體包一起提供：support_agent（一個代理）和 triage_agents（三個）。把其中一個複製到新目錄並在那裡工作：

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

下面的每條命令都在複製出的目錄中執行。證據儲存在那裡的 .oloproof/ 中。

第 1 部分：一個使用工具的代理

檔案

檔案	它是什麼
app.py	代理：Tools，一個代替模型決策的 plan，以及 run(case)，也就是它的循環，它會記錄軌跡
data/refunds.jsonl	40 個退款請求，每個都帶有預期回答，大多數還帶有預期工具
data/orders.jsonl	lookup_order 工具讀取的訂單
oloproof.yaml	套件：資料集、系統、評估器、分佈指標、切片
release.yaml	發布政策

記錄軌跡

run 就是全部的集成面。它呼叫每個工具，為呼叫追加一個 AgentStep，為結果再追加一個，記錄它自己的環境所做的約束檢查，並把軌跡交給案例記錄器：

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

該產物的結構：

欄位	它記錄什麼
steps	每個 AgentStep：index、kind（message、tool_call、tool_result、observation、decision、final 或 handoff）、tool_name、arguments、result，對於團隊還有 agent 和 to_agent
terminal_status	success、failure 或 unknown，即代理自己看到的結果
truncated、step_limit	循環達到了上限，記錄提前截止
constraints	AgentConstraintCheck(name, passed, step_index)：你的環境所做的檢查，例如“沒有刪除任何客戶”
checkpoints	重放可以從中恢復的 AgentCheckpoint（見“侷限”）

要使用你自己的代理，保留記錄部分，替換循環：在 run 中呼叫你的框架，並在步驟發生時把它們轉換為 AgentStep。系統在 oloproof.yaml 中宣告 records: [agent_trajectory/v1]；沒有它時，代理評估器會拒絕執行，而不是把每個案例都計為缺失。

案例宣告瞭什麼

{"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 用於任務檢查。expected.tools 是該案例應遵循的工具序列；省略它，工具序列檢查就不適用於該案例（它離開這些檢查的分母，而不是被計為通過）。behaviour 是這個確定性範例用來選擇其替身代理行為的方式；你的案例只攜帶真實的輸入。

選擇評估器

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 是任務檢查。
agent_tool_called 要求呼叫某個必需的工具；agent_tool_sequence 把呼叫與 expected.tools 進行比較；agent_no_tool_loop 標記連續重複超過 max_repeats 次的同一呼叫。這些描述的是工具使用，而不是成功。
agent_constraints_satisfied 讀取你的環境記錄下來的檢查。Oloproof 自己不觀測副作用，所以你的應用沒有記錄的約束是無法檢查的。
agent_max_steps 為每次執行設定上限；兩個分位數指標展示分佈，所以一個讓每次執行都變長的變更，在任何一次執行觸及上限之前就能被看到。

發布政策

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 是一條觀測計數規則：“在我們執行的套件中這絕不能發生”不需要區間。見閘門。

執行

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

如何閱讀：

結束代碼 1：有一條規則 FAIL 了。有三個案例呼叫了 delete_customer，環境把該約束記錄為被違反。
answer-floor 是 INSUFFICIENT_EVIDENCE，儘管 82.5% 高於 70%：只有 40 個案例時，區間仍然延伸到 67.2%。
1 missing：有一個案例觸及了步數上限，所以它的軌跡被截斷了。被截斷的軌跡能證明一些事情（它確實超過了 10 步），卻讓另一些事情懸而未決（必需的工具可能出現在未被記錄的部分中），所以那些判據把它計為缺失，區間則允許它朝任一方向變化。

檢視失敗項

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

第二條命令完整印出一個案例。有刪節：

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

客戶拿到了退款（任務成功），而代理在此過程中刪除了一個客戶（違反了約束）。兩個結果互不蘊含。完整的軌跡，即每一步及其參數和結果，在導出的包中（oloproof export RUN_ID），也在工作臺的案例視圖中。有意義的下一步在應用裡：阻止循環呼叫一個它絕不能呼叫的工具。

做一次候選變更並比較

在 app.py 中，讓循環拒絕被禁止的工具：

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

編寫一份比較政策 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

單看候選執行：no-deletion 現在 PASS，agent_constraints_satisfied 顯示 40 / 40，而閘門以結束代碼 3 阻止，因為兩個下限仍是 INSUFFICIENT_EVIDENCE。比較結果：

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)

把兩半分開來讀。在這個套件上，這次變更消除了每一次觀測到的刪除，而單次執行的觀測計數規則已經確定了這一點。候選在總體上是否不比基準差，是另一個問題，40 個配對案例還無法在 5 個百分點的邊際內確立它；規劃行大致說明了還需要多少。沒有任何回答發生變化，所以這次修復沒有影響任務成功。

第 2 部分：一個代理團隊

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

檔案與記錄

app.py 在一個循環中執行三個代理：triage 把每個請求交給 billing 或 tech，每個專員呼叫自己的工具，而 billing 無權發放的退款會被轉交給人。每個步驟都註明執行它的代理，每次控制權的轉移都是一個 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"))

一條軌跡要麼為每個步驟都註明代理，要麼一個都不註明；只註明部分步驟的軌跡會被拒絕。案例宣告它應走的路由：

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

評估器與政策

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 把掌握過控制權的代理（合併重複項，包括交接的接收方）與 expected.route 進行比較。這是路由檢查，而不是成功檢查。
agent_tool_permissions 對照一張封閉的映射表檢查每次呼叫：映射表中沒有列出的代理不能呼叫任何工具。
agent_max_handoffs 限制控制權易手的次數。

release.yaml 包含 answer-floor（min: 0.80）、routing-floor（min: 0.70）和 no-overreach，後者是作用於 agent_tool_permissions、帶 max_failures: 0 的觀測計數規則。

執行團隊

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 和 case_020：tech 發放了退款，而這個工具只有 billing 擁有。兩者都回答正確。任務成功，權限被違反。
case_005 和另外兩個案例先去了錯誤的專員那裡，再經由 triage 回來：回答是對的，路由和交接上限卻不對。
case_030 在 billing 和 tech 之間來回彈跳，直到觸及循環的上限。它被截斷的軌跡已經證明了路由和交接的失敗，卻無法確定權限，所以對它來說該判據是缺失，而不是通過。

輸出中沒有任何內容說明該歸咎於哪個代理。路由分歧說明兩條路由在哪裡分開；而說某個代理導致了失敗，是在斷言如果它換一種做法會發生什麼，這裡沒有任何檢查作出這種斷言。

修改團隊並比較

針對權限失敗的有意義的下一步：tech 把退款交給 billing，而不是自己發放。在 app.py 中，在 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"]))

使用一個 compare.yaml，其中包含針對 answer_correct 的 answers-not-worse 和針對 agent_route 的 routing-not-worse，兩者都是帶 margin: 0.05 的 non_inferiority：

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

單看候選執行：

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 │

以及比較結果：

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)

從中可以得出三點：

沒有任何觀測到的呼叫違反權限，但 no-overreach 現在是 INSUFFICIENT_EVIDENCE 而不是 PASS：被截斷的 case_030 可能在未被記錄的部分隱藏著一次違規（missing_could_change_outcome）。能確定這條規則的，是修復那個循環，而不是修改權限映射表。
這次修復把那兩個案例的路由變成了 triage > tech > billing，而它們的 expected.route 並沒有宣告這條路由，所以 agent_route 和 agent_handoffs_le_2 下降了。這條路由現在是否正確，是一個產品決策：如果正確，就更新這些案例的 expected.route；路由檢查量測的是與你所宣告內容的一致性，而不是品質。
規劃行表明，更多案例會把 routing-not-worse 推向 FAIL，而不是 PASS。比較在告訴你：按現在的寫法，候選是用路由換來了權限。

故障排除

症狀	原因	修復
代理評估器拒絕執行	系統上缺少 records: [agent_trajectory/v1]	在 oloproof.yaml 和 @system 上宣告它
一條軌跡被拒絕	有些步驟註明了 agent，另一些沒有	為每個步驟都註明代理，或一個都不註明
某個判據上有很多案例 missing	軌跡被截斷：循環觸及了上限	提高上限，或修復循環；缺失的案例會加寬區間，而不是被計為通過
agent_tool_sequence 的分母很小	案例沒有 expected.tools	在重要的地方宣告序列；[] 表示“不期望呼叫任何工具”
某個約束指標從不失敗	應用沒有記錄那項檢查	在你的環境觀測到它的地方記錄一個 AgentConstraintCheck
同一版本的多次執行結果不同	工具讀取或寫入共享狀態	在你的應用中，於每個案例之前重置該狀態；Oloproof 不會這麼做
新加入團隊的代理立即在權限上失敗	權限映射表是封閉的	宣告新代理可以呼叫什麼

侷限

Oloproof 不驅動、不隔離也不重置代理。工具副作用、會話、狀態及其重置都屬於你的應用。
每項檢查讀取的都是記錄下來的軌跡。應用沒有記錄的內容無法被量測，而被截斷的軌跡，凡是其前綴無法確定問題之處，都計為缺失。
軌跡檢查是確定性規則。沒有由 LLM 評判的軌跡品質檢查。
沒有任何輸出把失敗歸因於某個步驟或某個代理。代理重放會從記錄下來的檢查點重新執行一個案例並去掉某一步，以把該步標記為必要或不必要；它只存在於 Python SDK 中（replay_case），適用於實作了從其檢查點重放的系統；它沒有 CLI 命令，上面也沒有任何內容使用它。
多輪對話是另一個界面（僅限 SDK）；見目前可用的功能。
範例中的 plan 和 behaviour 欄位代替了模型的決策，使執行可以復現。你的循環中的真實模型會呼叫提供者，需要憑據，並且每個案例都要花錢。