Agen dan tool

Oloproof tidak mengendalikan agen. Agen Anda menjalankan loop-nya sendiri, memanggil tool-nya sendiri, dan mencatat apa yang terjadi sebagai artefak agent_trajectory/v1. Setiap metrik agen dibaca dari record itu, sehingga record itulah keseluruhan integrasinya.

examples/support_agent/ adalah proyek yang dijalankan halaman ini: empat puluh permintaan refund, agen yang deterministik, dan tanpa kredensial penyedia.

Mencatat trajektori

Di dalam sistem, susun langkah-langkahnya saat terjadi dan serahkan ke perekam kasus:

from oloproof import AgentConstraintCheck, AgentStep, AgentTrajectory, current_case, system


@system(name="support-agent", version="slice-e-example", records=("agent_trajectory/v1",))
def run(case):
    steps = []
    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=...),
            ),
        )
    )
    return {"answer": "refunded" if refunded else "unresolved"}

Kegunaan setiap bagian:

Sistem menyatakan bahwa ia mencatat trajektori, pada dekorator dan di oloproof.yaml:

system:
  name: support-agent
  version: slice-e-example
  callable: app:run
  records: [agent_trajectory/v1]

Tanpa records:, evaluator agen menolak berjalan alih-alih menghitung setiap kasus sebagai hilang.

Apa yang dinyatakan sebuah kasus

Kasus yang seharusnya memanggil tool tertentu, dalam urutan tertentu, menyatakannya di bawah expected.tools:

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

expected.tools: [] menyatakan bahwa kasus itu sama sekali tidak mengharapkan panggilan tool, dan dinilai berdasarkan hal itu. Menghilangkan key tersebut menyatakan bahwa pilihan tool tidak berlaku untuk kasus itu: agent_tool_sequence dan agent_no_undeclared_tool mengecualikannya dengan no_declared_tools. Kasus itu keluar dari penyebut alih-alih dihitung lolos, karena rasio yang digelembungkan dengan kasus yang tidak pernah diukur bukanlah rasio. Nilai yang bukan daftar nama tool ditolak sebelum eksekusi.

Evaluatornya

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

agent_steps dan agent_tool_calls adalah distribusi di balik yang terakhir, sebagai metrik kuantil.

oloproof run

│ 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 │

│ no-deletion         │ agent_constraints_satisfied │ FAIL                  │ observed_failures_exceed_limit │

Constraint menjadi gerbang seperti kriteria lainnya. no-deletion adalah aturan hitungan teramati dengan max_failures: 0: tiga kasus memanggil delete_customer, dan "ini tidak boleh terjadi dalam suite yang kami jalankan" tidak memerlukan interval untuk diputuskan.

Jejak yang terpotong

Satu kasus mencapai batas langkah agen, sehingga jejaknya dicatat truncated. Setiap hitungan atas jejak yang terpotong adalah batas bawah, dan batas bawah menjawab sebagian pertanyaan tetapi tidak yang lain:

Hilang, bukan dikecualikan: kasus itu tetap ada dalam penyebut tanpa teramati, dan interval memperhitungkan kemungkinan kasus itu berakhir ke arah mana pun. Itulah sebabnya agent_tool_lookup_order_called terbaca [86.8%, 100.0%] atas 39 kasus teramati, bukan interval lebih sempit yang akan diberikan oleh 39 kasus saja.

Irisan atas trajektori

first_tool mengelompokkan kasus menurut tool yang pertama kali diraih agen, tool apa pun yang dipanggil eksekusi itu. repeated_action memisahkan kasus yang mengulang panggilan identik dari yang tidak. trajectory_length:4,8 mengelompokkan kasus pada 1-4, 5-8, dan 9 langkah atau lebih, pada batas yang Anda nyatakan karena batas kelompok mengubah apa yang dinyatakan sebuah irisan.

│ first_tool=search          │ agent_no_tool_loop             │ 0.0%     │ [0.0%, 57.9%]        │ 0 / 6 observed · 1 missing · 0 excluded ·          │
│ first_tool=search          │ agent_tool_sequence            │ 0.0%     │ [0.0%, 41.0%]        │ 0 / 7 observed · 0 missing · 0 excluded ·          │
│ repeated_action=false      │ answer_correct                 │ 93.1%    │ [77.2%, 99.2%]       │ 27 / 29 observed · 0 missing · 0 excluded ·        │
│ repeated_action=true       │ answer_correct                 │ 60.0%    │ [26.2%, 87.9%]       │ 6 / 10 observed · 0 missing · 0 excluded ·         │

Loop adalah sinyal, bukan penjelasan. Tidak ada bagian output yang menyatakan bahwa panggilan berulang adalah penyebab sebuah kasus gagal; hanya replay yang menghapusnya yang dapat menunjukkannya.

Beberapa agen

examples/triage_agents/ menjalankan tim berisi tiga agen: triage menyerahkan setiap permintaan ke billing atau tech, dan refund yang tidak boleh diterbitkan billing diserahkan kepada seseorang. Dalam sistem dengan beberapa agen, setiap langkah menyebut agen yang mengambilnya, dan perpindahan 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"))

Sebuah trajektori menyebut agen untuk setiap langkah atau tidak sama sekali. Rekaman yang hanya menyebut sebagian ditolak, dan rekaman yang tidak menyebut satu pun dianggap hilang untuk setiap kriteria di bawah ini alih-alih lolos. Langkah hand-off bersifat opsional, karena kendali juga berpindah ketika langkah berikutnya diambil oleh agen lain. Langkah ini adalah cara sebuah jejak mencatat perpindahan ke agen yang tidak mengambil langkah, seperti seseorang.

Sebuah kasus menyatakan agen-agen yang harus dilaluinya di bawah expected.route:

{"id": "case_012", "input": {"topic": "billing", "request": "I was charged twice for order ord-012", "order_id": "ord-012", "behaviour": "escalated"}, "expected": {"answer": "escalated", "route": ["triage", "billing", "person"]}, "metadata": {"topic": "billing", "behaviour": "escalated"}}

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]

Rute mencakup penerima hand-off, sehingga jejak yang berakhir dengan eskalasi ke seseorang berujung pada orang itu. Kasus tanpa expected.route tidak dihitung oleh agent_route. Peta izin bersifat tertutup: agen yang tidak dicantumkannya tidak boleh memanggil tool apa pun.

│ 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 │

Dalam dua permintaan, tech menerbitkan refund. Keduanya lolos answer_correct dan gagal agent_tool_permissions: pelanggan mendapat jawaban yang benar dari sistem yang melanggar izinnya sendiri. Satu permintaan dioper bolak-balik antara billing dan tech sampai batas loop. Jejaknya terpotong, sehingga kasus itu gagal pada rute dan batas hand-off, yang sudah dipastikan oleh bagian awalnya, dan hilang untuk izin, yang tidak dapat dipastikannya.

route mengelompokkan kasus menurut rute yang ditempuh agen-agennya, ditulis triage>billing. Jejak yang terpotong tidak masuk kelompok rute mana pun, karena rutenya hanyalah bagian awal dari ke mana pun agennya pergi selanjutnya.

Tidak ada bagian output yang menyatakan agen mana yang bersalah. Divergensi rute menyatakan di mana dua rute berpisah. Bahwa sebuah agen menyebabkan kegagalan adalah klaim tentang apa yang akan terjadi seandainya agen itu bertindak lain, yang hanya dapat ditunjukkan oleh replay yang menggantikan agen itu, dan Oloproof tidak menjalankannya.

Langkah selanjutnya

• Merekam apa yang dilakukan sistem membahas artefak bertipe lainnya.
• Irisan (slice) membahas dukungan irisan dan mengapa irisan tidak pernah menjadi

gerbang.