Evaluating Agent Decisions

{
  "query": "I want a refund for order ORD-12345, the item was damaged",
  "expected_tools": ["check_order_status", "process_refund"],
  "forbidden_tools": ["escalate_to_human"],
  "should_escalate": false,
  "query_category": "refund",
  "expected_outcome": "Refund initiated successfully"
}

// Evaluator for escalation accuracy
function handler(input, output, expectedOutput) {
    const shouldEscalate = expectedOutput?.should_escalate || false;

    // Check if the agent escalated
    const outputLower = output.toLowerCase();
    const didEscalate = outputLower.includes("escalate") ||
                        outputLower.includes("human operator") ||
                        outputLower.includes("specialist will contact") ||
                        outputLower.includes("transferring");

    // Score based on correct escalation decision
    if (shouldEscalate === didEscalate) {
        return 1; // Correct decision
    } else if (shouldEscalate && !didEscalate) {
        return 0; // False negative - missed escalation (severe)
    } else {
        return 0.5; // False positive - over-escalation (less severe)
    }
}

// Evaluator for workflow completion
function handler(input, output, expectedOutput) {
    const requiredSteps = expectedOutput?.required_steps || [];

    if (requiredSteps.length === 0) {
        return 1; // No specific steps required
    }

    const outputLower = output.toLowerCase();
    let completedSteps = 0;

    for (const step of requiredSteps) {
        // Check if evidence of step completion exists in output
        if (outputLower.includes(step.toLowerCase())) {
            completedSteps++;
        }
    }

    return completedSteps / requiredSteps.length;
}

// Evaluator for query category handling
function handler(input, output, expectedOutput) {
    const category = expectedOutput?.query_category;
    const outputLower = output.toLowerCase();

    const categorySignals = {
        "refund": ["refund", "credited", "processed"],
        "order_status": ["status", "tracking", "delivered", "shipped"],
        "policy": ["policy", "days", "return", "terms"],
        "escalation": ["escalate", "specialist", "human", "contact you"],
    };

    const signals = categorySignals[category] || [];

    if (signals.length === 0) {
        return 1; // Unknown category, pass by default
    }

    // Check if any category signals appear in output
    const hasSignal = signals.some(signal => outputLower.includes(signal));

    return hasSignal ? 1 : 0;
}

# Before: Vague escalation guidance
system_prompt = """
Escalate complex issues to human operators.
"""

# After: Specific escalation criteria from evaluation failures
system_prompt = """
Escalate to human operators when ANY of these conditions are met:
- User expresses frustration (words like "ridiculous", "unacceptable", "furious")
- User has been waiting more than 2 weeks
- User explicitly asks to speak to a human
- The issue involves policy exceptions
- You cannot resolve the issue after 2 tool calls

Do NOT escalate for:
- Simple FAQ questions
- Routine order status checks
- Standard refund requests within policy
"""

# Before: Generic description
@tool
def search_kb(query: str) -> str:
    """Search the knowledge base."""
    ...

# After: Specific, actionable description
@tool
def search_kb(query: str) -> str:
    """Search the knowledge base for policy, procedure, or FAQ information.

    Use this tool when:
    - User asks about return/refund policies
    - User asks about shipping times or costs
    - User asks general "how to" questions

    Do NOT use for:
    - Order-specific questions (use check_order_status)
    - Ticket lookups (use lookup_ticket)
    """
    ...