Agent Platform 深度解析（七）— Evaluation & Quality Gates：全維度評測、Regression Prevention 與技能發布免疫系統

🌏 English version

TL;DR

Evaluation System 是 Agent Platform 的**「品質控制層」**，而非事後報表：

• 7 類 Eval：Flow、Step、Skill、Artifact、Evidence、Policy、Regression —— 全生命週期覆蓋
• 三階段執行：Pre-run（binding 驗證）→ In-run（step boundary schema/policy/citation/coverage/budget）→ Post-run（artifact/evidence/trajectory/cost/latency/feedback）
• 10 維 Scorecard：correctness、coverage、citation_quality、schema_validity、policy_compliance、cost_efficiency、latency、tool_selection_accuracy、retry_recovery、human_acceptance
• Skill 發布五關：Trigger Eval → Functional Eval → Policy Eval → Regression Eval → Human Review，任一失敗 = 保持 draft 狀態
• Learning Loop 閉環：Run 完成 → Signal 捕獲 → Proposal 生成 → Human Review → Sandbox Eval → Quality Gate → Publish
• Regression Prevention：真實失敗案例 → EvalCase Proposal → Review → 加入 Regression Suite → 後續版本必跑

為什麼需要系統級 Evaluation？

大多數 agent 框架的 evaluation 是事後想法：

• 跑幾個測試案例、看看輸出「感覺不錯」就發布
• 沒有 regression suite，升級 prompt/model 後舊功能悄悄壞掉
• 沒有把評測整合進發布流程，品質門檻靠人工把關
• Evidence quality、citation coverage 沒有量化指標

Agent Platform 把 Evaluation 做成平台級基礎設施，內建於 runtime：

7 類 Evaluation：全維度覆蓋

三階段執行時機：把關前移

Pre-run：靜態驗證（Run 創建前）

// 檢查項目
PreRunEval.check(flowVersion, preset, skillBindings, providerConfig, policy) {
  // 1. Flow 定義完整性
  validateFlowDefinition(flowVersion);
  
  // 2. Skill bindings 解析
  for (const step of flowVersion.steps) {
    if (step.uses) {
      const skillVersion = skillRegistry.resolveBinding(step.uses);
      // 檢查 skill 狀態、permissions、schemas
    }
  }
  
  // 3. Provider readiness
  for (const requiredRole of flowVersion.requiredProviderRoles) {
    const available = providerRouter.getAvailableProviders(requiredRole, preset.policy);
    if (available.length === 0) throw Error(`No provider for role: ${requiredRole}`);
  }
  
  // 4. Policy 版本存在且 published
  // 5. MCP tool bindings 有效
  
  return { valid: true, warnings: [] };
}

失敗即阻擋 Run 創建，不浪費資源。

In-run：Step Boundary 即時驗證

每個 step 完成時，自動執行：

InRunEval.atStepBoundary(stepRun, policy, skillVersion) {
  const results = [];
  
  // 1. Output Schema 驗證
  if (skillVersion?.metadata.output_schema) {
    results.push(validateSchema(stepRun.output, skillVersion.metadata.output_schema));
  }
  
  // 2. Policy Guards（已在 Policy Engine 執行，這裡記錄結果）
  results.push(...stepRun.guardResults);
  
  // 3. Citation Coverage（若 step 產出 claims）
  if (stepRun.output?.claims && policy.quality.citationRequired) {
    results.push(evaluateCitationCoverage(stepRun.output.claims));
  }
  
  // 4. Budget Check
  results.push(checkBudget(stepRun.runId, policy.budget));
  
  // 5. Evidence Quality（若為 extract_evidence 步驟）
  if (stepRun.stepId === "extract_evidence") {
    results.push(evaluateEvidenceQuality(stepRun.output.evidenceItems));
  }
  
  return results;
}

關鍵：In-run eval 失敗不一定阻擋流程（視 guard mode），但必須記錄，Observability 可見、Learning Loop 可捕獲。

Post-run：全流程品質評估

Run 結束後（succeeded/failed/canceled），執行：

PostRunEval.evaluate(run, flowVersion, preset) {
  const results = {
    artifact: evaluateArtifacts(run.artifactVersions),
    evidence: evaluateEvidenceBundle(run.evidenceBundle),
    trajectory: evaluateTrajectory(run.stepRuns),
    cost: evaluateCostEfficiency(run.costUsd, preset.policy.budget),
    latency: evaluateLatency(run.stepRuns),
    userFeedback: await collectUserFeedback(run.id)
  };
  
  // 計算綜合 Scorecard
  results.scorecard = computeScorecard(results);
  
  return results;
}

核心 Scorecard：10 維度量化品質

interface Scorecard {
  correctness: number;           // 0-1: 任務完成正確性（人工/自動評分）
  coverage: number;              // 0-1: 子問題覆蓋率、來源覆蓋率
  citation_quality: number;      // 0-1: 引用完整性、excerpt 相關性、conflict 處理
  schema_validity: number;       // 0-1: 所有 step/artifact 輸出符合 schema 比例
  policy_compliance: number;     // 0-1: Guard pass rate、approval 正確觸發率
  cost_efficiency: number;       // 0-1: 實際成本 / 預算、token 效率
  latency: number;               // 0-1: 總耗時 / maxRuntimeMs、step latency 分布
  tool_selection_accuracy: number; // 0-1: 工具選擇是否最優（對比 oracle）
  retry_recovery: number;        // 0-1: 失敗後 retry 成功率
  human_acceptance: number;      // 0-1: 用戶 approve/reject/regenerate 比例
}

每個維度都有明確計算邏輯，不是主觀打分。Scorecard 寫入 run.evaluation.scorecard，Web UI 可視化趨勢圖。

Skill 發布 Quality Gate：五關斬將

SkillVersion Draft
    ↓
[1] Trigger Eval
    檢查：skill.yaml triggers.phrases/step_types 是否能正確識別適用場景
    輸入：trigger-cases.json (正/負樣本)
    → 失敗：trigger 不準確，阻擋發布
    ↓
[2] Functional Eval
    檢查：golden-cases.json 輸出是否符合預期
    包含：正常輸入、邊界輸入、異常輸入
    → 失敗：功能不正確，阻擋發布
    ↓
[3] Policy Eval
    檢查：permissions 是否合規、tool usage 是否超標、cost/latency 是否在預算
    → 失敗：違規，阻擋發布
    ↓
[4] Regression Eval
    檢查：跑所有 regression cases（來自真實失敗、user correction）
    → 失敗：引入回歸，阻擋發布
    ↓
[5] Human Review
    最後把關：審核 eval 結果、審核變更內容、確認無風險
    → 失敗：人工判定有風險，阻擋發布
    ↓
SkillVersion Published (status: "published")

任何一關失敗 = 保持 draft 狀態，記錄失敗 gate，Web UI 顯示具體失敗原因。

Skill Eval 配置（skill.yaml）

evals:
  trigger_cases: ./evals/trigger-cases.json      # [1] Trigger Eval
  golden_cases: ./evals/golden-cases.json        # [2] Functional Eval
  # [3] Policy Eval: 自動從 skill.yaml permissions + policy 衍生
  # [4] Regression Eval: 自動從平台 regression suite 衍生
  # [5] Human Review: 平台強制步驟

Learning Loop：從 Run 到 Improvement 的閉環

核心原則：Agent can propose learning, but production knowledge requires eval and human approval.

1. Learning Signals（8 類訊號來源）

2. Signal → Proposal 流程

Run Completed
    ↓
Learning Candidate Detector (掃描所有 signals)
    ↓
Trace Summarizer (提取相關 stepRun/toolUsage/evidence/error)
    ↓
Proposal Generator (依 signal 類型產出四類提案之一)
    ↓
Human Review (Web UI: Improve 頁面)
    ↓
Sandbox Eval (用 historical runs 跑 proposal，對比 metric)
    ↓
Quality Gate (通過 output-schema、policy、regression evals)
    ↓
Publish (SkillVersion 升版 / Policy 更新 / EvalCase 入庫 / Memory 寫入)

3. 四類可審核提案

關鍵：所有提案停在「待審核」，不自動生效。

4. EvalCase 從真實 Run 轉化

// 用戶在 Web UI 點擊 "Convert to Eval Case"
createEvalCaseFromRun({ runId, stepRunId, description, expectedBehavior }) {
  // 1. 提取輸入
  const input = run.inputs;
  
  // 2. 提取期望行為（從成功的 retry 或人工修正）
  const expected = stepRun.output;  // 或用戶手動輸入
  
  // 3. 關聯 trace evidence
  const traceEvidence = {
    stepRuns: run.stepRuns.filter(s => s.stepId === stepRunId),
    evidenceItems: run.evidenceItems.filter(e => e.supportsStep === stepRunId),
    guardResults: run.guardResults.filter(g => g.stepRunId === stepRunId)
  };
  
  // 4. 建立 EvalCase Proposal（非直接入庫）
  return {
    type: "EvalCaseProposal",
    input,
    expected,
    traceEvidence,
    description,
    status: "pending_review"
  };
}

審核通過後 → 加入 Regression Suite → 後續所有 Skill/Flow 版本發布必跑。

Eval Suite/Case/Run/Result 資料模型

// Eval Suite：一組相關的 eval cases
interface EvalSuite {
  id: string;
  name: string;              // "deep_research_regression"
  description: string;
  targetType: "flow" | "skill" | "artifact" | "evidence" | "policy";
  targetRef: string;         // "deep_research@v1" 或 "citation-extractor@1.0.0"
  required: boolean;         // true = 發布門檻必跑
  createdAt: string;
}

// Eval Case：單一測試案例
interface EvalCase {
  id: string;
  suiteId: string;
  name: string;
  input: any;                // 輸入參數
  expected: any;             // 期望輸出/行為
  traceEvidence?: TraceRef;  // 來源 run/step 追溯
  tags: string[];            // "regression", "edge_case", "golden"
  status: "draft" | "active" | "archived";
  createdAt: string;
}

// Eval Run：一次評測執行
interface EvalRun {
  id: string;
  suiteId: string;
  targetVersion: string;     // 被測版本
  caseResults: EvalCaseResult[];
  aggregateMetrics: Scorecard;
  status: "running" | "completed" | "failed";
  startedAt: string;
  endedAt: string;
}

// Eval Case Result：單案例結果
interface EvalCaseResult {
  caseId: string;
  status: "passed" | "failed" | "error";
  actualOutput: any;
  metrics: { correctness, coverage, citation_quality, ... };
  error?: ErrorInfo;
  durationMs: number;
}

Sandbox Eval：隔離環境驗證 Proposal

async function runSandboxEval(proposal, historicalRuns) {
  // 1. 建立沙箱環境（隔離的 runtime、臨時 skill/policy/memory）
  const sandbox = createSandbox({
    skillVersions: proposal.skillChanges,
    policyVersion: proposal.policyChanges,
    memoryItems: proposal.memoryChanges
  });
  
  // 2. 對 historical runs 重放（相同 inputs）
  const results = [];
  for (const run of historicalRuns) {
    const sandboxRun = await sandbox.executeFlow(run.flowId, run.presetId, run.inputs);
    results.push(compareRuns(run, sandboxRun));
  }
  
  // 3. 聚合對比指標
  return {
    scorecardDelta: aggregateScorecards(results),
    regressionCheck: checkNoRegressions(results),
    improvementCheck: checkImprovements(results),
    costDelta: aggregateCostDelta(results),
    latencyDelta: aggregateLatencyDelta(results)
  };
}

Sandbox 特性：

• 隔離 runtime，不影響生產數據
• 用歷史 runs 做 A/B 對比（舊版 vs 應用 proposal 後）
• 產出詳細對比報告，Human Review 時參考

Regression Prevention：免疫系統運作

真實 Run 失敗
    ↓
用戶修正（retry-step / 修改輸入 / 人工干預）
    ↓
Run 最終成功
    ↓
Learning Loop 捕獲 "run_failed_then_succeeded" signal
    ↓
產生 EvalCase Proposal（含失敗→成功的關鍵差異）
    ↓
Human Review 確認：這是真實 bug 修復，不是運氣
    ↓
加入 Regression Suite（標記 required: true）
    ↓
後續所有 SkillVersion/FlowVersion 發布前
    → 必跑此 Regression Case
    → 失敗 = 阻擋發布

效果：同類 bug 永遠不會再次發布到生產。

Web UI：Evaluation & Improve 介面

常見陷阱與最佳實踐

總結：Evaluation System 核心契約

Eval Suite (versioned, target: flow/skill/artifact/evidence/policy/regression)
    → Eval Cases (input, expected, traceEvidence, tags)
    
Pre-run Eval:   Flow/skill/policy/provider binding 驗證 → 阻擋無效 run
In-run Eval:    Step boundary: schema/policy/citation/coverage/budget → 記錄 GuardResult
Post-run Eval:  Artifact/Evidence/Trajectory/Cost/Latency/Feedback → Scorecard

Scorecard (10 dims): correctness, coverage, citation_quality, schema_validity,
                     policy_compliance, cost_efficiency, latency, tool_selection_accuracy,
                     retry_recovery, human_acceptance

Skill Publish Gate (5 stages, any fail = block):
    Trigger Eval → Functional Eval → Policy Eval → Regression Eval → Human Review
    
Learning Loop:
    Run → Signals (8 types) → Trace Summarizer → Proposals (4 types)
    → Human Review → Sandbox Eval (A/B vs historical) → Quality Gate → Publish
    
Regression Prevention:
    Real failure → User correction → Success → EvalCase Proposal
    → Review → Regression Suite (required) → All future publishes must pass

三大不變量：

1. Eval 內建於執行流程 —— Pre/In/Post 三階段，不是事後補充
2. Quality Gate 強制阻擋 —— Skill draft 失敗即不可發布，零例外
3. 學習不自動生效 —— 所有改進經過 Human Review + Sandbox Eval + Quality Gate

參考資料

• Agent Platform: Evaluation Learning Loop Spec
• Agent Gateway Plan - Evaluation System
• Agent Gateway Plan - Learning Loop
• Agent Gateway Plan - Skill System (Skill 發布 gate)
• OpenSpec Specs — 7 大能力規格完整定義