使用結構化事件和 SQL 評估 AI 代理

代理完成一次執行，不代表它完成了任務。將執行、需要分析的模型和工具呼叫以及評估結果分別記錄為事件。SQL 可以按發布版本比較品質、成本、延遲、重試和轉由人工處理的情況。先用其他證據核對模型產生的評分，再判斷評分是否正確。

Telemetry 是該工作流程中的分析層。它不執行記分器、管理提示版本、管理評估資料集或提供提示和完成重播。將這些工作流程保留在您的應用程式或專用評估系統中，然後傳送聚合分析所需的批准結果欄位。

operation_id 應跨版本保持唯一。

首先定義評估單位

選擇回答“什麼獲得了分數？”的行在選擇指標之前。常見單位包括：

向使用者顯示一個最終答案；
一次已完成的代理執行；
一個已解決的支援案例；
一項工具選擇決策；
針對凍結範例檢索到的答案；
一項業務操作可以包括多次代理嘗試。

為該單元指定一個穩定的識別符號，例如 operation_id。對 run_id、response_id 和 evaluation_id 使用單獨的識別符號。一次重試可以為一項操作建立多次執行，並且一個輸出可以接受多次評估。對每個grain重複使用單個識別符號會產生錯誤的連線和重複計算的成本。

單獨的執行、請求和評估事件

實用的起始合約使用三個或四個事件資料表：

活動	穀物	有用的欄位
`agent_run_completed`	一臺終端代理執行	`operation_id`、`run_id`、`workflow`、`status`、`duration_ms`、`tool_call_count`、`human_handoff`、`prompt_version`、`release`
`llm_request_completed`	一位提供商請求	`operation_id`、`run_id`、`response_id`、`provider`、`model`、`input_tokens`、`output_tokens`、`estimated_cost_usd`、`latency_ms`
`agent_tool_completed`	一種工具嘗試	`run_id`、`tool_call_id`、`tool_name`、`status`、`duration_ms`、`retry_count`、`error_type`
`ai_output_reviewed`	一項評估結果	`operation_id`、`evaluation_id`、`evaluator_type`、`evaluator_version`、`metric_name`、`score`、`passed`、`review_outcome`、`is_final`、`dataset_version`、`release`

不要將所有四粒穀物強行擠成一排。否則，進行五次工具嘗試和兩次評估的執行會增加成本或加入時的成功次數。

使用多種證據

沒有一個評估者足以滿足每個代理工作流程。僅組合與實際決策相對應的訊號：

確定性檢查驗證模式、所需引用、允許的工具選擇、精確計算、策略規則或已知的最終狀態。
人工審查捕獲有界的標題，例如正確、部分正確、不安全或需要升級。記錄標題和審稿人流程，而不是私人審稿人筆記。
基於模型的評分可以以更高的量應用可重複的評分標準。對判斷模型、指令和閾值進行版本控制，並定期將分數與人工審查進行比較。
產品結果記錄使用者是否接受、儲存、更正、重新生成、升級或放棄結果。

LLM評委是一個衡量工具，而不是一個客觀標籤。追蹤分歧、缺失評估以及法官設定的變化。 Langfuse評價理念和 Arize Phoenix 評估文件描述了可以保留在 Telemetry 上游的附加評估工作流程。

發出經過審查的結果事件

此 JavaScript 範例在評分者或人工審查工作流程完成後傳送緊湊的評估器結果：

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

export async function recordAgentEvaluation({
  operationId,
  evaluationId,
  evaluatorType,
  evaluatorVersion,
  metricName,
  score,
  threshold,
  reviewOutcome,
  isFinal,
  datasetVersion,
  promptVersion,
  release,
}) {
  await telemetry.log("ai_output_reviewed", {
    operation_id: operationId,
    evaluation_id: evaluationId,
    evaluator_type: evaluatorType,
    evaluator_version: evaluatorVersion,
    metric_name: metricName,
    score,
    threshold,
    passed: score >= threshold,
    review_outcome: reviewOutcome,
    is_final: isFinal,
    dataset_version: datasetVersion,
    prompt_version: promptVersion,
    release,
  });
}

只有對該操作、指標、評估器版本與產品版本具有最終效力的唯一決定，才將 isFinal 設為 true。代理執行結束不代表審查已定案。

預設情況下，將原始提示、完成、檢索到的文件、工具參數、秘密和自由格式的審閱者註釋保留在事件之外。更喜歡穩定的類別和版本識別符號。如果內容保留獲得批准，請將其儲存在專為該存取和刪除策略設計的系統中，並將其與受限識別符號相關聯。

按版本比較品質

本例要求每個操作、產品版本、指標與評估器版本只有一筆 is_final = true 的最終審查。初步審查應標記為 is_final = false。若需修正最終決定，請使用新的評估器版本或獨立的定案事件。查詢會排除重複的最終審查，且只統計已完成的操作；解讀覆蓋率或通過率之前應先調查重複紀錄。

WITH completed AS (
  SELECT release, operation_id
  FROM agent_run_completed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
    AND status = 'success'
  GROUP BY release, operation_id
),
final_reviews AS (
  SELECT release, operation_id, MAX(score) AS score,
    MAX(CASE WHEN passed THEN 1 ELSE 0 END) AS passed
  FROM ai_output_reviewed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
    AND metric_name = 'task_quality'
    AND evaluator_version = 'quality-rubric-v3'
    AND is_final = true
  GROUP BY release, operation_id
  HAVING COUNT(*) = 1
)
SELECT
  c.release,
  COUNT(*) AS completed_operations,
  COUNT(f.operation_id) AS evaluated_operations,
  ROUND(
    100.0 * COUNT(f.operation_id)
    / NULLIF(COUNT(*), 0),
    1
  ) AS evaluation_coverage_pct,
  ROUND(
    100.0 * SUM(CASE WHEN f.passed = 1 THEN 1 ELSE 0 END)
    / NULLIF(COUNT(f.operation_id), 0),
    1
  ) AS evaluated_pass_rate_pct,
  ROUND(AVG(f.score), 3) AS average_final_score
FROM completed c
LEFT JOIN final_reviews f
  ON f.release = c.release AND f.operation_id = c.operation_id
GROUP BY c.release
ORDER BY c.release;

使用結果決定是否發布版本之前，請檢查查詢排除的重複最終審查：

SELECT release, operation_id, COUNT(*) AS conflicting_final_reviews
FROM ai_output_reviewed
WHERE timestamp_utc >= now() - INTERVAL '30 days'
  AND metric_name = 'task_quality'
  AND evaluator_version = 'quality-rubric-v3'
  AND is_final = true
GROUP BY release, operation_id
HAVING COUNT(*) > 1
ORDER BY release, operation_id;

不要在不分離這些維度的情況下比較使用不同標準的版本、判斷模型、閾值、資料集版本或取樣規則。評估者變更後的分數變化並不是產品迴歸的證據。

計算每個可接受結果的成本

先依操作彙總成本，再與唯一的最終決定關聯。本例的 operation_id 跨版本皆為全域唯一；若你的系統並非如此，請在兩邊的關聯鍵加入 release。重複的最終決定會被排除，且需要調查。

WITH operation_cost AS (
  SELECT
    operation_id,
    SUM(estimated_cost_usd) AS total_cost_usd
  FROM llm_request_completed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
  GROUP BY operation_id
),
terminal_outcome AS (
  SELECT
    operation_id,
    MAX(CASE WHEN review_outcome = 'accepted' THEN 1 ELSE 0 END) AS accepted
  FROM ai_output_reviewed
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
    AND metric_name = 'task_quality'
    AND evaluator_version = 'quality-rubric-v3'
    AND is_final = true
  GROUP BY operation_id
  HAVING COUNT(*) = 1
)
SELECT
  COUNT(*) AS evaluated_operations,
  SUM(accepted) AS accepted_operations,
  ROUND(SUM(total_cost_usd), 4) AS evaluated_cost_usd,
  ROUND(
    SUM(total_cost_usd) / NULLIF(SUM(accepted), 0),
    4
  ) AS cost_per_accepted_operation_usd
FROM operation_cost c
JOIN terminal_outcome o ON o.operation_id = c.operation_id;

只有當“接受”有穩定的定義時，這個指標才有意義。複製的答案、使用者可見的答案、無需重新開啟即可解決的案例以及人工評分通行證是不同的結果。

建置迴歸門

對於每個提議的版本：

使用相同的評估器設定執行相同的凍結資料集。
記錄候選release、prompt_version、dataset_version和evaluator_version。
將透過率、嚴重失敗率、切換率、p95 持續時間以及每個接受操作的成本與批准的基線進行比較。
檢查源評估系統中的失敗範例。
使用執行前選擇的閾值批准或拒絕發布。
單獨監控生產結果，因為凍結資料集無法代表每個即時輸入。

當決策需要時，包括最小樣本量和置信區間。避免對分母很小的百分比發出警示。還追蹤評估覆蓋範圍：20 次審查執行的及格分數並不代表 10,000 次未經審查的執行。

何時保留專用評估平臺

當團隊需要提示和完成檢查、資料集管理、註釋佇列、提示管理、實驗執行、追蹤重放或內建評估器時，請使用專業平臺。 Telemetry 可以收到 SQL 分析的版本化分數和結果；它不是功能對功能的替代。

接下來，使用 AI品質回歸秘訣、代理任務成功和移交秘訣和每美元配方可接受的產出。對於更廣泛的實現邊界，請參閱 AI代理監控。

讓程式設計代理使用這篇文件