प्रति-चरण एरर लोकलाइज़ेशन: ट्रैजेक्टरी मूल्यांकन से पता लगाना कि एजेंट कहाँ विफल होते हैं

समस्या: यह जान लेना काफ़ी नहीं कि एजेंट विफल हुआ

एक ट्रैजेक्टरी एरर टैक्सोनॉमी

आप अपना एजेंट किसी बेंचमार्क पर चलाते हैं। टास्क पूर्णता पर उसे 63% मिलते हैं। अब आगे क्या?

पास/फ़ेल की एक संख्या बस इतना बताती है कि एजेंट 37% टास्क पर विफल रहा, इससे ज़्यादा कुछ नहीं। वह यह नहीं बताती कि ट्रेस में कहाँ गड़बड़ हुई, एजेंट ने किस तरह की ग़लती की, या वह कितनी बुरी थी। क्या यह चरण 2 पर हुई एक विनाशकारी भूल थी, या पंद्रह चरणों तक छोटी-छोटी तर्क-ग़लतियाँ जमा होती गईं? क्या एजेंट ने किसी टूल का ग़लत इस्तेमाल किया, या एक ग़लत आधार-वाक्य से तर्क किया?

प्रति-चरण एरर लोकलाइज़ेशन के बिना आप न विफलता के तरीक़ों की पहचान कर सकते हैं, न तय कर सकते हैं कि पहले क्या ठीक करना है, न प्रोसेस रिवॉर्ड मॉडल के लिए प्रशिक्षण डेटा बना सकते हैं। आप अँधेरे में हाइपरपैरामीटर ट्यून कर रहे होते हैं।

Potato की trajectory_eval एनोटेशन योजना यह ठीक करती है। एनोटेटर ट्रेस के हर चरण से गुज़रते हैं और दर्ज करते हैं:

• शुद्धता: यह चरण सही है या ग़लत?
• एरर प्रकार: आपकी परिभाषित की हुई श्रेणीबद्ध टैक्सोनॉमी में से चुना गया
• गंभीरता स्तर: minor, major या critical, जिनके स्कोर वेट कॉन्फ़िगर किए जा सकते हैं
• कारण: एरर की मुक्त-पाठ व्याख्या (वैकल्पिक)
• रनिंग स्कोर: एक संचयी स्कोर जो गंभीरता के हिसाब से घटता है और आपको प्रति-ट्रेस गुणवत्ता वक्र देता है

यह गाइड पूरा सेटअप कवर करती है: अपनी एरर टैक्सोनॉमी परिभाषित करना, एनोटेशन चलाना, और जुटाए गए डेटा का विश्लेषण करना। योजना के कॉन्फ़िगरेशन संदर्भ के लिए स्रोत दस्तावेज़ देखें।

ट्रैजेक्टरी eval योजना का सार

trajectory_eval योजना बहु-चरणीय एजेंट ट्रेस को क्रम से जाँचने के लिए बनी है। कुल मिलाकर एक गुणवत्ता रेटिंग देने के बजाय यह हर चरण के लिए एक संरचित एरर एनोटेशन बनाती है, जिससे आपके पास इसका विस्तृत नक़्शा आ जाता है कि एजेंट कहाँ और क्यों विफल हुआ।

हर चरण पर एनोटेशन इंटरफ़ेस यह करता है:

1. एनोटेटर मौजूदा चरण की सामग्री देखता है (thought, action, observation, code आदि)
2. वह चरण को correct या incorrect चिह्नित करता है
3. अगर incorrect है, तो श्रेणीबद्ध टैक्सोनॉमी में से एक एरर प्रकार चुनता है
4. एक गंभीरता स्तर देता है (minor, major या critical)
5. चाहे तो एरर समझाते हुए एक कारण लिखता है
6. इंटरफ़ेस के ऊपर दिख रहा रनिंग स्कोर अपने आप अपडेट हो जाता है

एनोटेटर एक बार में एक चरण लेकर ट्रेस में आगे बढ़ता है और पूरी एरर प्रोफ़ाइल खड़ी करता जाता है।

ट्रैजेक्टरी मूल्यांकन इंटरफ़ेस हर चरण को उसके स्कोर के साथ दिखाता है:

हर चरण को शुद्धता रेटिंग, एरर प्रकार और गंभीरता स्तर मिलता है, साथ में एक रनिंग स्कोर जो गंभीरता के हिसाब से घटता है

श्रेणीबद्ध एरर टैक्सोनॉमी बनाना

टैक्सोनॉमी ही वह चीज़ है जिससे ट्रैजेक्टरी मूल्यांकन करने लायक बनता है। वह ठीक हो तो आप कई ट्रेस में एरर जोड़कर व्यवस्थित विफलता-पैटर्न पकड़ सकते हैं; ग़लत हो तो आपके लेबल से कुछ नहीं बनता। मैं जिस टैक्सोनॉमी से शुरू करूँगा वह यह है, चार शीर्ष-स्तरीय श्रेणियों के साथ।

तर्क संबंधी एरर

ये तब होते हैं जब एजेंट का तर्क ख़राब हो, भले ही वह जो देखता और करता है वह बाक़ी ठीक हो।

प्रत्यक्षण संबंधी एरर

ये तब होते हैं जब एजेंट अपने observation में मौजूद जानकारी को ग़लत पढ़ता है, ग़लत समझता है या चूक जाता है।

क्रिया संबंधी एरर

ये तब होते हैं जब एजेंट ग़लत क्रिया करता है, या सही क्रिया ग़लत तरीक़े से करता है।

संवाद संबंधी एरर

ये उपयोगकर्ताओं को दिए गए एजेंट के जवाबों में, या इसमें दिखते हैं कि वह अपने काम का ब्योरा कैसे देता है।

गंभीरता स्तर और स्कोर वेट

हर एरर को एक गंभीरता स्तर मिलता है। डिफ़ॉल्ट वेट ये हैं:

रनिंग स्कोर 100 से शुरू होता है और हर एरर पर गंभीरता वेट के हिसाब से गिरता है। 85 पर ख़त्म होने वाले ट्रेस में कुछ छोटी दिक़्क़तें थीं; 40 पर ख़त्म होने वाले में कई बड़ी विफलताएँ।

इन वेट को आप कॉन्फ़िगरेशन में बदल सकते हैं:

severities:
  - name: minor
    weight: -1
  - name: major
    weight: -5
  - name: critical
    weight: -10

पूरा YAML कॉन्फ़िगरेशन

पूरी टैक्सोनॉमी के साथ ट्रैजेक्टरी मूल्यांकन के लिए एक सम्पूर्ण config.yaml यह रहा:

annotation_task_name: "Agent Trajectory Error Localization"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: "trace_id"
  text_key: "task"
 
instance_display:
  fields:
    - key: "task"
      type: text
      label: "Task"
    - key: "trace"
      type: agent_trace
      label: "Agent trace"
      display_options:
        show_step_numbers: true
        show_timestamps: false
        step_type_colors:
          thought: "#E8F0FE"
          action: "#FFF3E0"
          observation: "#F1F8E9"
          code: "#F3E5F5"
 
annotation_instructions: |
  Walk the trace one step at a time. Mark a step incorrect only when it is
  wrong on the information available at that step, not with hindsight. When
  several categories apply, choose the most specific one.
 
annotation_schemes:
  - annotation_type: trajectory_eval
    name: step_errors
    description: "Mark each step and classify any error"
    steps_key: trace
    step_text_key: content
    correctness_options:
      - correct
      - incorrect
      - partially_correct
    error_types:
      - name: reasoning
        subtypes:
          - logical_error
          - incorrect_assumption
          - over_generalization
          - circular_reasoning
          - incorrect_calculation
      - name: perception
        subtypes:
          - missed_element
          - misidentified_element
          - hallucinated_element
          - outdated_reference
      - name: action
        subtypes:
          - wrong_tool
          - wrong_arguments
          - premature_termination
          - unnecessary_action
          - destructive_action
      - name: communication
        subtypes:
          - unclear_explanation
          - missing_context
          - incorrect_summary
          - overconfident_claim
    severities:
      - name: minor
        weight: -1
      - name: major
        weight: -5
      - name: critical
        weight: -10
    show_score: true
    max_score: 100
 
  - annotation_type: radio
    name: overall_success
    description: "Did the run succeed overall?"
    labels:
      - success
      - partial
      - failure
    sequential_key_binding: true
 
output_annotation_dir: "annotation_output/"
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true

चरण-दर-चरण सेटअप

1. अपने एजेंट ट्रेस तैयार करें

ट्रेस डेटा JSONL फ़ॉर्मैट में जाता है, प्रति पंक्ति एक ट्रेस। हर ट्रेस को एक ID, एक टास्क विवरण और चरणों की सूची चाहिए:

{
  "trace_id": "trace_042",
  "task": "Find the bug in the calculate_discount function and fix it",
  "trace": [
    {
      "type": "thought",
      "content": "I need to look at the calculate_discount function to find the bug. Let me search for it."
    },
    {
      "type": "action",
      "content": "search",
      "action_input": "def calculate_discount"
    },
    {
      "type": "observation",
      "content": "Found in pricing.py line 45:\ndef calculate_discount(price, discount_pct):\n    return price * discount_pct / 100"
    },
    {
      "type": "thought",
      "content": "The function calculates the discount amount but doesn't subtract it from the price. It should return price - (price * discount_pct / 100)."
    },
    {
      "type": "action",
      "content": "edit_file",
      "action_input": "pricing.py:45: return price - (price * discount_pct / 100)"
    },
    {
      "type": "observation",
      "content": "File edited successfully."
    },
    {
      "type": "action",
      "content": "finish",
      "action_input": "Fixed the calculate_discount function. It was returning the discount amount instead of the discounted price."
    }
  ]
}

अगर आपके ट्रेस किसी और फ़ॉर्मैट में हैं (OpenAI messages, LangChain runs, Claude conversation logs), तो Potato का ट्रेस कन्वर्टर इस्तेमाल करें:

python -m potato.trace_converter \
  --input raw_traces/ \
  --output data/traces.jsonl \
  --input-format react

2. अपनी टैक्सोनॉमी कॉन्फ़िगर करें

ऊपर दी पूरी टैक्सोनॉमी से शुरू करें, फिर अपने एजेंट के हिसाब से उसे छाँटें या बढ़ाएँ। मिसाल के लिए कोडिंग एजेंट के लिए आप एक code_quality श्रेणी जोड़ सकते हैं:

error_types:
  - name: code_quality
    subtypes:
      - syntax_error
      - runtime_error
      - logic_bug
      - style_violation

कोडिंग एजेंट ट्रेस के लिए मूल्यांकन स्कोरिंग के साथ-साथ diff और टर्मिनल आउटपुट भी दिखाता है:

CodingTraceDisplay ट्रैजेक्टरी मूल्यांकन नियंत्रणों के साथ diff, टर्मिनल ब्लॉक और फ़ाइल रीड दिखाता है

3. एनोटेशन सर्वर चालू करें

potato start config.yaml -p 8000

अपने ब्राउज़र में http://localhost:8000 खोलें। आपको पहला ट्रेस चरण-दर-चरण डिस्प्ले के साथ दिखेगा।

4. एनोटेशन दिशानिर्देश लिखें

एनोटेटरों को साफ़ निर्देश दें। कम से कम इतना दर्ज करें:

• किसी चरण को incorrect कब कहें और correct-पर-कमज़ोर कब
• जब एक से ज़्यादा एरर श्रेणियाँ लागू होती हों तो किसे चुनें (सबसे विशिष्ट वाली)
• हर गंभीरता स्तर कब दें, ठोस उदाहरणों के साथ
• चरणों को उस चरण पर उपलब्ध जानकारी के आधार पर आँका जाए या बाद की समझ के साथ

एनोटेशन का प्रवाह

जब कोई एनोटेटर ट्रेस खोलता है, तो टास्क विवरण सबसे ऊपर रहता है और उसके नीचे पहला चरण। ऊपर दाएँ कोने में रनिंग स्कोर 100 दिखाता है।

हर चरण के लिए एनोटेटर:

1. पिछले चरणों के संदर्भ में चरण की सामग्री पढ़ता है
2. "Correct" या "Incorrect" पर क्लिक करके शुद्धता चिह्नित करता है
3. अगर incorrect है, तो एरर श्रेणी चुनता है (जैसे "Reasoning Error") और फिर विशिष्ट प्रकार (जैसे "Incorrect Assumption")
4. गंभीरता देता है: minor, major या critical
5. कारण लिखता है (अगर चालू हो): "एजेंट बिना जाँचे मान लेता है कि फ़ाइल मौजूदा डायरेक्टरी में है, जबकि खोज के नतीजों में वह src/utils/ में दिखी थी"
6. "Next Step" पर क्लिक करके या दाहिने तीर की कुंजी दबाकर अगले चरण पर बढ़ता है

हर एरर के बाद रनिंग स्कोर अपडेट होता है। चरण 3 को major एरर (-5) चिह्नित करें और स्कोर 100 से गिरकर 95 हो जाता है। चरण 7 को critical (-10) चिह्नित करें और वह 85 पर आ जाता है।

ट्रेस के अंत में एनोटेटर कुल मिलाकर success/partial/failure रेटिंग देता है और सबमिट कर देता है।

नतीजों का विश्लेषण

एनोटेशन डेटा लोड करना

import json
import pandas as pd
from collections import Counter
from pathlib import Path
 
# Load all annotation files
annotations = []
output_dir = Path("output/")
for f in output_dir.glob("*.jsonl"):
    with open(f) as fh:
        for line in fh:
            annotations.append(json.loads(line))
 
print(f"Loaded {len(annotations)} annotated traces")

एरर वितरण का विश्लेषण

# Extract all errors across all traces
errors = []
for ann in annotations:
    for step_ann in ann.get("error_localization", []):
        if step_ann["correctness"] == "incorrect":
            errors.append({
                "trace_id": ann["trace_id"],
                "step_index": step_ann["step_index"],
                "category": step_ann["error_category"],
                "error_type": step_ann["error_type"],
                "severity": step_ann["severity"],
                "rationale": step_ann.get("rationale", ""),
            })
 
error_df = pd.DataFrame(errors)
print(f"Total errors found: {len(error_df)}")
print()
 
# Error distribution by category
print("Errors by category:")
print(error_df["category"].value_counts())
print()
 
# Most common specific error types
print("Top 10 error types:")
print(error_df["error_type"].value_counts().head(10))
print()
 
# Severity distribution
print("Severity distribution:")
print(error_df["severity"].value_counts())

एरर की स्थिति का विश्लेषण

ट्रेस में एरर आम तौर पर कहाँ पड़ते हैं, यह देखने से अक्सर व्यवस्थित पैटर्न सामने आ जाते हैं:

import matplotlib.pyplot as plt
import numpy as np
 
# Normalize step positions to [0, 1] range
for ann in annotations:
    trace_length = len(ann.get("error_localization", []))
    for step_ann in ann["error_localization"]:
        if step_ann["correctness"] == "incorrect":
            step_ann["normalized_position"] = step_ann["step_index"] / max(trace_length - 1, 1)
 
# Collect normalized positions
positions = [
    step_ann["normalized_position"]
    for ann in annotations
    for step_ann in ann.get("error_localization", [])
    if step_ann["correctness"] == "incorrect"
    and "normalized_position" in step_ann
]
 
plt.figure(figsize=(10, 4))
plt.hist(positions, bins=20, edgecolor="black", alpha=0.7)
plt.xlabel("Normalized Position in Trace (0 = start, 1 = end)")
plt.ylabel("Error Count")
plt.title("Where Do Agent Errors Occur?")
plt.tight_layout()
plt.savefig("error_position_distribution.png", dpi=150)
print("Saved error_position_distribution.png")

रनिंग स्कोर के वितरण

# Extract final running scores
final_scores = []
for ann in annotations:
    score = 100
    severity_weights = {"minor": -1, "major": -5, "critical": -10}
    for step_ann in ann.get("error_localization", []):
        if step_ann["correctness"] == "incorrect":
            score += severity_weights.get(step_ann["severity"], 0)
    score = max(score, 0)
    final_scores.append({
        "trace_id": ann["trace_id"],
        "final_score": score,
        "overall_success": ann.get("overall_success", "unknown"),
    })
 
score_df = pd.DataFrame(final_scores)
 
print("Score statistics:")
print(score_df["final_score"].describe())
print()
 
# Score distribution by overall success
for label in ["success", "partial", "failure"]:
    subset = score_df[score_df["overall_success"] == label]
    if len(subset) > 0:
        print(f"{label}: mean={subset['final_score'].mean():.1f}, "
              f"median={subset['final_score'].median():.1f}, "
              f"n={len(subset)}")

सबसे आम विफलता के तरीक़े

# Group errors by category + type for a failure mode analysis
failure_modes = (
    error_df.groupby(["category", "error_type"])
    .agg(
        count=("severity", "size"),
        avg_severity_weight=("severity", lambda x: x.map(
            {"minor": 1, "major": 5, "critical": 10}
        ).mean()),
    )
    .sort_values("count", ascending=False)
)
 
print("Top failure modes (by frequency):")
print(failure_modes.head(15).to_string())
print()
 
# Impact-weighted failure modes (frequency x average severity)
failure_modes["impact"] = failure_modes["count"] * failure_modes["avg_severity_weight"]
print("Top failure modes (by impact):")
print(failure_modes.sort_values("impact", ascending=False).head(10).to_string())

शोध का संदर्भ

प्रति-चरण एरर लोकलाइज़ेशन एजेंट मूल्यांकन की कुछ हालिया धाराओं से मेल खाता है:

TRAIL (Patronus AI, 2025) ने GAIA और SWE-bench Lite से ली गई 148 एजेंट ट्रेस को 20 से ज़्यादा त्रुटि-प्रकारों की एक टैक्सोनॉमी पर लेबल किया, कुल 841 त्रुटियाँ। ध्यान देने लायक नतीजा यह है कि त्रुटि की जगह बताना कितना कठिन निकला: उनके परखे सबसे अच्छे लॉन्ग-कॉन्टेक्स्ट रीज़निंग मॉडल ने श्रेणी और स्थान दोनों पर मिलाकर 11% सटीकता पाई। यही काम trajectory_eval इंसानी एनोटेटर को सौंपता है, और इसीलिए ये लेबल अपनी क़ीमत वसूल करते हैं।

AgentRewardBench (McGill NLP, 2025) ने इसके बजाय जजों को परखा। इसमें पाँच बेंचमार्क से 1,302 वेब-एजेंट ट्रैजेक्टरी जुटाई गईं, हर एक की समीक्षा एक विशेषज्ञ ने सफलता, साइड-इफ़ेक्ट और दोहराव के लिहाज़ से की, और फिर उन समीक्षाओं के सामने बारह LLM जजों को आँका गया। कोई भी जज हर बेंचमार्क पर आगे नहीं रहा, और बेंचमार्क के साथ आने वाले नियम-आधारित मूल्यांकन एजेंटों की सफलता को कम करके आँकते रहे। अगर आप इस टैक्सोनॉमी का कोई हिस्सा मॉडल से स्वचालित करने की सोच रहे हैं, तो जाँच का यही रूप चाहिए।

trajectory_eval से मिलने वाले चरण-स्तरीय शुद्धता और गंभीरता लेबल सीधे प्रोसेस रिवॉर्ड मॉडल की ट्रेनिंग में भी जाते हैं: हर एनोटेट किया चरण एक ट्रेनिंग उदाहरण है, जिसके साथ ग्राउंड-ट्रुथ गुणवत्ता संकेत जुड़ा है।

Anthropic का Demystifying evals for AI agents इसी तर्क का व्यावहारिक रूप रखता है। सिर्फ़ नतीजे को नहीं, पूरे ट्रांसक्रिप्ट को आँकिए, और एजेंट ने tool कैसे बुलाए और उपयोगकर्ता से कैसे बात की, इसके लिए स्पष्ट रूब्रिक वाले मॉडल-आधारित ग्रेडर इस्तेमाल कीजिए। यह इस बात से भी आगाह करता है कि पहले से तय चरण-क्रम के हिसाब से अंक न दें, क्योंकि एजेंट लगातार ऐसे वैध रास्ते खोज लेते हैं जिनका अंदाज़ा eval बनाने वाले को नहीं था। इस टैक्सोनॉमी को लागू करते समय यह बात याद रखिए: कोई चरण इसलिए त्रुटि है कि वह ग़लत था, इसलिए नहीं कि वह अप्रत्याशित था।

गंभीरता-भारित रनिंग स्कोर RLHF में इस्तेमाल होने वाले रिवॉर्ड संकेतों से भी मेल खाता है। 20-चरणीय ट्रेस के चरण 5 पर तेज़ी से गिरने वाला स्कोर वक्र आपको ठीक-ठीक बता देता है कि एजेंट को कहाँ काम चाहिए, और यह ट्रेस के अंत में मिले एक अकेले रिवॉर्ड से कहीं ज़्यादा काम की बात है।

सारांश

trajectory_eval योजना एजेंट मूल्यांकन को पास/फ़ेल जाँच से एक निदान में बदल देती है। श्रेणीबद्ध टैक्सोनॉमी, गंभीरता स्कोरिंग और रनिंग स्कोर के साथ आप देख सकते हैं कि कौन-सा चरण ग़लत गया, वह किस तरह की ग़लती थी, कितनी बुरी थी, और कई ट्रेस में एरर कहाँ इकट्ठा होते हैं। चरण-स्तरीय लेबल प्रोसेस रिवॉर्ड मॉडल के प्रशिक्षण डेटा के रूप में इस्तेमाल के लिए भी तैयार हैं।

इस गाइड की पूरी टैक्सोनॉमी से शुरू करें, फिर अपने एजेंट और असल में दिखने वाले एरर पैटर्न के हिसाब से उसे सुधारें। सबसे अच्छी टैक्सोनॉमी वही है जो ऐसे फ़िक्स की ओर इशारा करे जो आप कर सकते हैं।