# Practices for Embedding AI Agents in Software # Eval Harness 🎯 The Hook Changed a prompt and quality silently dropped. The provider updated the model and accuracy drifted. You found out from user complaints. An eval harness catches these before deployment. 🔥 The Problem AI agents are probabilistic -- deterministic unit tests don't apply. Hallucinations can't be caught by spot-checking individual outputs. LLM drift (quality shifts from provider-side model updates) happens even when your team changes nothing. Without an eval harness, quality degradation surfaces only as production incidents and user complaints. 💡 The Pattern Build an evaluation pipeline combining golden datasets (input + expected output pairs) with automated eval functions (exact match, LLM-as-Judge, custom metrics). Run regression detection in CI on every prompt, model, or code change. Schedule periodic runs (daily to weekly) even without changes to catch LLM drift. Evaluation operates at three layers: offline (pre-deploy batch), online (production sampling), and shadow (A/B comparison). Regression gate thresholds are category-specific, with zero-tolerance for safety category degradation. ✅ When to Use Use when: - The agent handles production traffic with ongoing prompt, model, or code changes - Quantitative quality evidence is required (SLA compliance, regulatory reporting) - Domain experts can create and maintain golden datasets Don't use when: - Prototype stage where prompts change drastically daily - Output is creative generation (fiction, poetry) where "correct" is hard to define - Downstream deterministic validation already auto-corrects errors ⚠️ Pitfalls - Golden data rots. When product specs change, outdated expected outputs flag correct results as regressions. Assign owners and last-updated dates, and schedule regular reviews - LLM-as-Judge is also probabilistic. Even at temperature 0, scores can vary. For critical cases, use majority vote across 3 runs - Define when baseline scores are updated (e.g., after successful deploy). Without explicit update triggers, degradation becomes invisible 🔧 Implementation Approach - Structure golden datasets with category, eval function name, and expected keywords per case, enabling category-level aggregation and regression detection - Operate the eval pipeline at three layers: offline (pre-deploy batch in CI), online (production sampling), and shadow (A/B comparison of old vs. new) - Set regression gates as relative comparisons against baseline scores -- zero tolerance for safety categories, roughly 2% degradation threshold for general categories - In shadow mode, dry-run any side-effecting tool calls; in canary deploys, use sticky sessions to keep users on the same version - Assign owners and last-updated dates to golden data to prevent rot from spec changes, with scheduled periodic reviews #AIAgents# #SoftwareArchitecture#