Ajanlar ve araçlar

Oloproof bir ajanı yönetmez. Ajanınız kendi döngüsünü çalıştırır, kendi araçlarını çağırır ve olanı bir agent_trajectory/v1 yapıtı (artifact) olarak kaydeder. Her ajan metriği bu kayıttan okunur; dolayısıyla entegrasyonun tamamı bu kayıttır.

examples/support_agent/ bu sayfanın çalıştırdığı projedir: kırk iade talebi, deterministik bir ajan ve hiçbir sağlayıcı kimlik bilgisi yok.

Bir yörüngeyi kaydetmek

Sistemin içinde adımları oldukları anda oluşturun ve vaka kaydedicisine verin:

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

Her parçanın ne işe yaradığı:

Sistem, yörüngeyi kaydettiğini dekoratörde ve oloproof.yaml içinde bildirir:

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

records: olmadan ajan değerlendiricileri, her vakayı eksik saymak yerine çalışmayı reddeder.

Bir vakanın bildirdikleri

Belirli araçları belirli bir sırayla çağırması gereken bir vaka bunu expected.tools altında belirtir:

{"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: [], vakanın hiç araç çağrısı beklemediğini söyler ve vaka buna göre değerlendirilir. Anahtarı hiç yazmamak, araç seçiminin bu vaka için geçerli olmadığını söyler: agent_tool_sequence ve agent_no_undeclared_tool onu no_declared_tools ile hariç tutar. Vaka geçti olarak sayılmak yerine paydadan çıkar, çünkü hiç ölçülmemiş vakalarla şişirilmiş bir oran, oran değildir. Araç adlarından oluşan bir liste olmayan bir değer, çalıştırmadan önce reddedilir.

Değerlendiriciler

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 ve agent_tool_calls, sonuncunun arkasındaki dağılımlardır ve yüzdelik (quantile) metrikleri olarak kullanılır.

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 │

Bir kısıt, diğer her ölçüt gibi kapı olur. no-deletion, max_failures: 0 ile gözlenen sayıya dayalı bir kuraldır: üç vaka delete_customer çağırdı ve "bu, çalıştırdığımız pakette olmamalı" ifadesinin karara bağlanması için güven aralığı gerekmez.

Erken kesilen bir iz

Bir vaka ajanın adım sınırına ulaşır, bu yüzden izi truncated olarak kaydedilir. Kesilmiş bir iz üzerindeki her sayı bir alt sınırdır ve bir alt sınır bazı soruları çözer, bazılarını çözmez:

Hariç tutulan değil, eksik: vaka gözlenmemiş olarak paydada kalır ve güven aralığı onun her iki yöne de gitmiş olabileceğini hesaba katar. agent_tool_lookup_order_called değerinin, yalnızca 39 vakanın vereceği daha dar aralık yerine gözlenen 39 vaka üzerinden [86.8%, 100.0%] göstermesinin nedeni budur.

Yörüngeler üzerindeki dilimler

first_tool, çalıştırma hangi araçları çağırmış olursa olsun, vakaları ajanın ilk başvurduğu araca göre gruplar. repeated_action, özdeş bir çağrıyı tekrarlayan vakaları tekrarlamayanlardan ayırır. trajectory_length:4,8 vakaları 1-4, 5-8 ve 9 ya da daha fazla adım olarak gruplar; sınırları siz bildirirsiniz, çünkü bir grup sınırı bir dilimin söylediğini değiştirir.

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

Bir döngü bir sinyaldir, bir açıklama değil. Çıktıdaki hiçbir şey, bir vakanın tekrarlanan bir çağrı yüzünden başarısız olduğunu söylemez; bunu ancak o çağrıyı kaldıran bir yeniden oynatma söyleyebilirdi.

Birden çok ajan

examples/triage_agents/ üç kişilik bir ekip çalıştırır: triage her talebi billing ya da tech ajanına verir ve billing'in yapamayacağı bir iade bir kişiye devredilir. Birden çok ajanlı bir sistemde her adım onu atan ajanı adlandırır ve kontrolün 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ı adlandıran bir kayıt reddedilir; hiçbirini adlandırmayan bir kayıt ise aşağıdaki her ölçüt için onu geçmek yerine eksik sayılır. Devir adımı isteğe bağlıdır, çünkü bir sonraki adımı başka bir ajan attığında da kontrol el değiştirir. Bir iz, bir kişi gibi hiç adım atmayan bir ajana yapılan devri bu adımla kaydeder.

Bir vaka, içinden geçmesi gereken ajanları expected.route altında bildirir:

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

Rota bir devrin alıcısını içerir; dolayısıyla bir kişiye yükseltmeyle biten bir iz o kişiye yönlenir. expected.route içermeyen bir vaka agent_route tarafından sayılmaz. İzin eşlemesi kapalıdır: listelemediği bir ajan hiçbir aracı çağıramaz.

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

İki talepte tech bir iade yaptı. İkisi de answer_correct ölçütünü geçer ve agent_tool_permissions ölçütünde başarısız olur: müşteri doğru yanıtı, kendi izinlerini çiğneyen bir sistemden aldı. Bir talep, döngünün sınırına kadar billing ile tech arasında gidip gelir. İzi kesilmiştir; bu yüzden öneki zaten karara bağladığı için rotada ve devir sınırında başarısız olur, bağlamadığı için de izinler açısından eksik sayılır.

route, vakaları ajanlarının izlediği rotaya göre gruplar; rota triage>billing biçiminde yazılır. Kesilmiş bir iz hiçbir rota grubuna katılmaz, çünkü rotası, ajanlarının sonra nereye gittiğinin bir önekidir.

Çıktıdaki hiçbir şey hangi ajanın suçlu olduğunu söylemez. Bir rota sapması iki rotanın nerede ayrıldığını söyler. Bir ajanın bir başarısızlığa neden olduğu, o ajan başka türlü davransaydı ne olacağına dair bir iddiadır; bunu yalnızca o ajanın yerine başkasını koyan bir yeniden oynatma gösterebilir ve Oloproof böyle bir şey çalıştırmaz.

Sonraki adımlar

• Bir sistemin ne yaptığını kaydetmek diğer tipli yapıtları anlatır.
• Dilimler dilim desteğini ve dilimlerin neden asla kapı olmadığını anlatır.