13. הערכת סוכנים

הבעיה

בניתם סוכן. יש לו לולאה, כלים, תכנון, תת-סוכנים, מיומנויות, ניהול הקשר, משימות, ביצוע ברקע, צוותים, פרוטוקולים, אוטונומיה, ובידוד. אתם יכולים לצפות בו עובד וזה נראה מרשים. אבל האם הוא באמת טוב?

לא ניתן לענות על השאלה הזו על ידי צפייה. סוכנים הם לא דטרמיניסטיים — אותו פרומפט מייצר רצפי קריאות כלים שונים בהרצות שונות. שינוי בפרומפט המערכת שלכם עשוי לשפר יצירת קבצים אבל לשבור בשקט שכתוב קוד. לא תשימו לב עד שמשתמש ישים לב.

בדיקות יחידה מסורתיות לא עוזרות. אי אפשר לבדוק שהסוכן קרא ל-write_file בתור 3, כי מחר הוא עשוי לקרוא ל-bash בתור 2 ולקבל את אותה תוצאה. אתם צריכים בדיקות שבודקות תוצאות, לא צעדים.

הפתרון

רתמת eval. הגדירו תרחישים עם תוצאות ידועות מראש, הריצו את הסוכן בסנדבוקס, בדקו מה הוא ייצר, ודרגו את התוצאות.

הגדרת תרחיש  →  הרצת סוכן בסנדבוקס  →  בדיקת תוצאות  →  ניקוד  →  דוח

בניית רתמת ה-Eval

הליבה היא שני dataclasses ופונקציה אחת.

from dataclasses import dataclass
from typing import Callable
import tempfile, os

@dataclass
class EvalCase:
    name: str
    prompt: str
    check: Callable[[str], "EvalResult"]
    max_turns: int = 20
    max_tokens: int = 50000

@dataclass
class EvalResult:
    passed: bool
    score: float   # 0.0 to 1.0
    details: str

EvalCase הוא הקלט. EvalResult הוא הפלט. כל eval, לא משנה כמה מורכב, עומד בממשק הזה.

הרצה יוצרת סביבת עבודה מבודדת, מריצה את הסוכן, ומעבירה את סביבת העבודה לבודק:

def run_eval(case: EvalCase, agent_fn) -> EvalResult:
    workspace = tempfile.mkdtemp()
    messages = [{"role": "user", "content": case.prompt}]
    turns = 0
    total_tokens = 0

    while turns < case.max_turns:
        response = agent_fn(messages)
        total_tokens += response.usage.input_tokens + response.usage.output_tokens
        if total_tokens > case.max_tokens:
            return EvalResult(False, 0.0, "Token budget exceeded")
        if response.stop_reason != "tool_use":
            break
        execute_tools(response, messages, cwd=workspace)
        turns += 1

    return case.check(workspace)

הפרמטר cwd=workspace הוא קריטי. כל קריאת כלי מתבצעת בתוך התיקייה הזמנית. הסוכן יכול ליצור קבצים, להריץ פקודות ולשנות מצב — הכל מוגבל לסביבת העבודה הזו.

אסטרטגיות ניקוד

לא כל eval הוא עבר/נכשל. שלוש אסטרטגיות, עולות ברזולוציה:

עבר/נכשל בינארי

הפשוט ביותר. האם הקובץ קיים? האם הבדיקה עברה?

def check_file_exists(workspace):
    if os.path.exists(os.path.join(workspace, "output.txt")):
        return EvalResult(True, 1.0, "File created")
    return EvalResult(False, 0.0, "File missing")

ניקוד חלקי

הענקת נקודות עבור כל קריטריון שהתמלא:

def check_refactor(workspace):
    path = os.path.join(workspace, "math_utils.py")
    if not os.path.exists(path):
        return EvalResult(False, 0.0, "File not found")

    content = open(path).read()
    score = 0.0
    details = []

    if "def calculate_average" in content:
        score += 0.25
        details.append("PASS: function exists")

    if "def calculate_average(numbers: list" in content:
        score += 0.25
        details.append("PASS: type hints present")

    if '"""' in content or "'''" in content:
        score += 0.25
        details.append("PASS: docstring present")

    result = subprocess.run(
        ["python", "-c", f"import math_utils; print(math_utils.calculate_average([1,2,3]))"],
        capture_output=True, text=True, cwd=workspace
    )
    if result.returncode == 0 and "2" in result.stdout:
        score += 0.25
        details.append("PASS: correct output")

    return EvalResult(score >= 0.75, score, "; ".join(details))

התובנה המרכזית: קריטריון 4 באמת מריץ את הקוד שנוצר. בדיקת תוכן מחרוזת אומרת לכם שהסוכן כתב משהו שנראה נכון. הרצתו אומרת לכם שהוא נכון.

הרצת Evals בסקלה

from concurrent.futures import ThreadPoolExecutor
import json, time

def run_suite(cases: list[EvalCase], agent_fn, workers: int = 4) -> dict:
    results = {}
    start = time.time()

    with ThreadPoolExecutor(max_workers=workers) as pool:
        futures = {
            pool.submit(run_eval, case, agent_fn): case.name
            for case in cases
        }
        for future in futures:
            name = futures[future]
            try:
                results[name] = future.result(timeout=300)
            except Exception as e:
                results[name] = EvalResult(False, 0.0, f"Error: {e}")

    elapsed = time.time() - start
    passed = sum(1 for r in results.values() if r.passed)
    total_score = sum(r.score for r in results.values()) / len(results)

    return {
        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S"),
        "total": len(cases),
        "passed": passed,
        "avg_score": round(total_score, 3),
        "results": {
            name: {"passed": r.passed, "score": r.score, "details": r.details}
            for name, r in results.items()
        },
    }

מה השתנה מבידוד Worktree ומשימות

נקודה מרכזית

Evals סוגרים את הלולאה. בלעדיהם, כל שינוי בסוכן שלכם הוא ניחוש — אתם מקווים שהשתפר, אתם מניחים ששום דבר לא נשבר. עם רתמת eval, אתם יודעים. הגדירו תרחישים, כתבו בודקים, הריצו את החבילה, וקראו את הציונים. הסוכן טוב רק כמו היכולת שלכם למדוד אותו. עכשיו אתם יכולים למדוד.