Hướng dẫn: đánh giá một agent

Một bài hướng dẫn có thể chạy được cho một agent dùng công cụ và cho một nhóm agent: ghi lại những gì agent đã làm dưới dạng một quỹ đạo, kiểm tra việc dùng công cụ, ràng buộc, số bước, định tuyến, quyền và việc chuyển giao của nó, làm cổng cho một bản phát hành dựa trên chúng, và so sánh một thay đổi ứng viên với đường cơ sở. Cả hai ví dụ đều chạy cục bộ mà không cần thông tin xác thực của nhà cung cấp.

Tài liệu tham chiếu cho mọi trường và bộ đánh giá là Agent và công cụ; các thuật ngữ trường hợp, bộ đánh giá, chỉ số, khoảng và cổng nằm ở Khái niệm cốt lõi. Trang này là lộ trình thực hành đi qua chúng.

Oloproof làm gì và không làm gì ở đây

Oloproof không điều khiển agent của bạn. Ứng dụng của bạn chạy vòng lặp của chính nó, gọi các công cụ của chính nó, và ghi lại những gì đã xảy ra dưới dạng một artifact agent_trajectory/v1. Mọi chỉ số agent đều được đọc ra từ bản ghi đó.

Ứng dụng của bạn cũng sở hữu mọi thứ mà các công cụ chạm tới. Oloproof không cung cấp sandbox, công cụ giả lập hay việc đặt lại giữa các trường hợp: nếu một công cụ ghi vào cơ sở dữ liệu, gửi email hoặc trừ tiền thẻ trong một lần đánh giá, nó thực sự làm vậy. Hãy trỏ agent tới các tài khoản thử nghiệm, công cụ giả hoặc một môi trường dùng một lần, và tự đặt lại trạng thái giữa các trường hợp, trước khi bạn chạy một lần đánh giá.

Hãy giữ hai loại câu hỏi tách biệt:

Chúng bất đồng theo những cách hữu ích. Trong cả hai ví dụ bên dưới, một số trường hợp trả lời đúng nhưng vẫn vi phạm một quy tắc, và chỉ một kiểm tra quỹ đạo thấy được điều đó. Một kiểm tra quỹ đạo đạt cũng không nói gì về việc tác vụ có thành công hay không.

Điều kiện tiên quyết

• Python 3.11 trở lên, và Oloproof đã được cài (pip install oloproof).
• Các dự án ví dụ, đi kèm với gói: support_agent (một agent) và triage_agents (ba agent). Sao chép một dự án vào một thư mục mới và làm việc ở đó:

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

Mọi lệnh bên dưới chạy từ bên trong thư mục đã sao chép. Bằng chứng được lưu trong .oloproof/ ở đó.

Phần 1: một agent dùng công cụ

Các tệp

Ghi lại quỹ đạo

run là toàn bộ bề mặt tích hợp. Nó gọi từng công cụ, nối thêm một AgentStep cho lời gọi và một cho kết quả của nó, ghi lại các kiểm tra ràng buộc mà môi trường của chính nó đã thực hiện, và chuyển quỹ đạo cho bộ ghi của trường hợp:

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

Hình dạng của artifact:

Để dùng agent của chính bạn, hãy giữ phần ghi lại và thay vòng lặp: gọi framework của bạn trong run, và chuyển các bước của nó thành AgentStep khi chúng xảy ra. Hệ thống khai báo records: [agent_trajectory/v1] trong oloproof.yaml; không có nó, các bộ đánh giá agent từ chối chạy thay vì tính mọi trường hợp là bị thiếu.

Một trường hợp khai báo gì

{"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 dành cho kiểm tra tác vụ. expected.tools là chuỗi công cụ mà trường hợp nên đi theo; bỏ nó đi thì các kiểm tra chuỗi công cụ không áp dụng cho trường hợp đó (nó rời khỏi mẫu số của chúng thay vì đạt). behaviour là cách ví dụ tất định này chọn điều mà agent thay thế của nó làm; các trường hợp của bạn chỉ mang đầu vào thật.

Chọn các bộ đánh giá

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 là kiểm tra tác vụ.
• agent_tool_called yêu cầu một công cụ bắt buộc; agent_tool_sequence so sánh các lời gọi với expected.tools; agent_no_tool_loop đánh dấu cùng một lời gọi lặp lại quá max_repeats lần liên tiếp. Những kiểm tra này mô tả việc dùng công cụ, không phải thành công.
• agent_constraints_satisfied đọc các kiểm tra mà môi trường của bạn đã ghi lại. Oloproof không tự quan sát các tác dụng phụ, nên một ràng buộc mà ứng dụng của bạn không ghi lại thì không thể kiểm tra.
• agent_max_steps giới hạn mỗi lần chạy; hai chỉ số phân vị cho thấy phân phối, nên một thay đổi làm mọi lần chạy dài hơn sẽ hiện ra trước khi bất kỳ lần chạy nào chạm giới hạn.

Chính sách phát hành

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 là một quy tắc đếm quan sát: "điều này không được xảy ra trong bộ kiểm thử mà chúng ta đã chạy" không cần khoảng. Xem Cổng.

Chạy

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

Cách đọc:

• Mã thoát 1: một quy tắc đã FAIL. Ba trường hợp đã gọi delete_customer, và môi trường đã ghi lại ràng buộc là bị vi phạm.
• answer-floor là INSUFFICIENT_EVIDENCE dù 82,5% cao hơn 70%: với 40 trường hợp, khoảng vẫn chạm tới 67,2%.
• 1 missing: một trường hợp chạm giới hạn bước, nên trace của nó bị cắt ngắn. Một trace bị cắt ngắn chứng minh được một số điều (nó đã vượt quá 10 bước) và để ngỏ những điều khác (một công cụ bắt buộc có thể nằm trong phần không được ghi), nên các tiêu chí đó tính nó là bị thiếu, và khoảng cho phép nó đã đi theo hướng nào cũng được.

Xem xét các thất bại

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

Lệnh thứ hai in ra trọn một trường hợp. Đã rút gọn:

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

Khách hàng đã nhận được tiền hoàn (thành công của tác vụ) từ một agent đã xóa một khách hàng trên đường đi (một ràng buộc bị vi phạm). Không kết quả nào kéo theo kết quả kia. Toàn bộ quỹ đạo, mọi bước cùng các đối số và kết quả của nó, nằm trong gói đã xuất (oloproof export RUN_ID) và trong khung xem trường hợp trên workbench. Hành động tiếp theo có ý nghĩa nằm trong ứng dụng: ngăn vòng lặp gọi một công cụ mà nó không bao giờ được gọi.

Thực hiện một thay đổi ứng viên và so sánh

Trong app.py, làm cho vòng lặp từ chối công cụ bị cấm:

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

Viết một chính sách so sánh, 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

Riêng lần chạy ứng viên: no-deletion giờ PASS, agent_constraints_satisfied ghi 40 / 40, và cổng chặn với mã thoát 3 vì hai mức sàn vẫn là INSUFFICIENT_EVIDENCE. Phép so sánh:

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)

Hãy đọc riêng hai nửa. Trên bộ kiểm thử này, thay đổi đã loại bỏ mọi lần xóa được quan sát, điều mà quy tắc đếm quan sát của một lần chạy đơn lẻ đã giải quyết. Việc ứng viên có không tệ hơn đường cơ sở nói chung hay không là một câu hỏi khác, và 40 trường hợp ghép cặp chưa thể xác lập điều đó trong một biên 5 điểm; dòng lập kế hoạch cho biết đại khái cần thêm bao nhiêu. Không câu trả lời nào thay đổi, nên thành công của tác vụ không bị bản sửa ảnh hưởng.

Phần 2: một nhóm agent

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

Các tệp và việc ghi lại

app.py chạy ba agent trong một vòng lặp: triage chuyển mỗi yêu cầu cho billing hoặc tech, mỗi chuyên viên gọi các công cụ của riêng nó, và một khoản hoàn tiền mà billing không được phép phát hành sẽ được chuyển cho một người. Mỗi bước nêu agent đã thực hiện nó, và mỗi lần chuyển quyền điều khiển là một bước 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"))

Một quỹ đạo nêu agent của mọi bước hoặc không bước nào; một quỹ đạo chỉ nêu ở một số bước sẽ bị từ chối. Một trường hợp khai báo lộ trình mà nó nên đi:

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

Bộ đánh giá và chính sách

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 so sánh các agent đã nắm quyền điều khiển (các lần lặp được gộp lại, bên nhận của một lần chuyển giao được tính vào) với expected.route. Một kiểm tra định tuyến, không phải kiểm tra thành công.
• agent_tool_permissions kiểm tra mọi lời gọi so với một bảng ánh xạ đóng: một agent mà bảng không liệt kê thì không được gọi công cụ nào.
• agent_max_handoffs giới hạn số lần quyền điều khiển đổi chủ.

release.yaml có answer-floor (min: 0.80), routing-floor (min: 0.70) và no-overreach, một quy tắc đếm quan sát với max_failures: 0 trên agent_tool_permissions.

Chạy nhóm

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 và case_020: tech đã phát hành một khoản hoàn tiền, một công cụ chỉ billing nắm giữ. Cả hai đều trả lời đúng. Tác vụ thành công, quyền bị vi phạm.
• case_005 và hai trường hợp khác đi tới sai chuyên viên trước rồi quay lại qua triage: câu trả lời đúng, lộ trình và giới hạn chuyển giao thì không.
• case_030 bị đẩy qua lại giữa billing và tech cho tới giới hạn của vòng lặp. Trace bị cắt ngắn của nó đã chứng minh các thất bại về lộ trình và chuyển giao, và không thể giải quyết vấn đề quyền, nên tiêu chí đó bị thiếu với nó thay vì đạt.

Không có gì trong đầu ra nói agent nào có lỗi. Một sự phân kỳ lộ trình cho biết hai lộ trình tách nhau ở đâu; việc một agent gây ra một thất bại là một khẳng định về điều sẽ xảy ra nếu nó hành động khác đi, điều mà không kiểm tra nào ở đây đưa ra.

Thay đổi nhóm và so sánh

Hành động tiếp theo có ý nghĩa cho các thất bại về quyền: tech chuyển một khoản hoàn tiền cho billing thay vì tự phát hành. Trong app.py, trong 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"]))

Với một compare.yaml chứa answers-not-worse trên answer_correct và routing-not-worse trên agent_route, cả hai đều là non_inferiority với margin: 0.05:

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

Riêng lần chạy ứng viên:

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 │

và phép so sánh:

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)

Ba điều cần rút ra:

• Không lời gọi nào được quan sát vi phạm quyền, nhưng no-overreach giờ là INSUFFICIENT_EVIDENCE thay vì PASS: case_030 bị cắt ngắn có thể che giấu một vi phạm trong phần không được ghi (missing_could_change_outcome). Sửa vòng lặp đó, chứ không phải bảng quyền, mới là điều giải quyết được quy tắc.
• Bản sửa đã đổi lộ trình của hai trường hợp thành triage > tech > billing, điều mà expected.route của chúng không khai báo, nên agent_route và agent_handoffs_le_2 giảm. Lộ trình đó giờ có đúng hay không là một quyết định sản phẩm: nếu đúng, hãy cập nhật expected.route của các trường hợp; một kiểm tra định tuyến đo sự tuân thủ những gì bạn đã khai báo, không phải chất lượng.
• Dòng lập kế hoạch nói thêm trường hợp sẽ đẩy routing-not-worse về phía FAIL, không phải PASS. Phép so sánh đang cho bạn biết rằng ứng viên, như được viết, đánh đổi định tuyến lấy quyền.

Khắc phục sự cố

Giới hạn

• Oloproof không điều khiển, cô lập hay đặt lại một agent. Tác dụng phụ của công cụ, phiên, trạng thái và việc đặt lại chúng thuộc về ứng dụng của bạn.
• Mọi kiểm tra đều đọc quỹ đạo đã ghi. Những gì ứng dụng không ghi lại thì không thể đo, và một trace bị cắt ngắn được tính là bị thiếu ở bất cứ đâu mà phần đầu của nó không giải quyết được câu hỏi.
• Các kiểm tra quỹ đạo là các quy tắc tất định. Không có kiểm tra chất lượng quỹ đạo do LLM chấm.
• Không đầu ra nào quy một thất bại cho một bước hay một agent. Phát lại agent, thứ chạy lại một trường hợp từ một checkpoint đã ghi với một bước bị bỏ để gán nhãn nó là cần thiết hay không cần thiết, chỉ có trong Python SDK (replay_case), cho một hệ thống hiện thực việc phát lại từ các checkpoint của nó; không có lệnh CLI nào cho việc đó, và không gì ở trên dùng nó.
• Hội thoại nhiều lượt là một bề mặt khác (chỉ SDK); xem Những gì hoạt động hôm nay.
• Các trường plan và behaviour của các ví dụ đứng thay cho các quyết định của một mô hình để các lần chạy có thể tái lập. Một mô hình thật trong vòng lặp của bạn sẽ gọi một nhà cung cấp, cần thông tin xác thực và tốn tiền cho mỗi trường hợp.