Vercel 教你如何測試 Agent 與其使用的軟體
WTF are evals? How to test agents and the software they use
Vercel 說明如何用評測衡量 Agent 是否能正確完成使用者任務,並以咖啡訂單示範端到端評測的設計、執行與分析。
- - 測試層級:依 LLM 呼叫次數分為確定性測試、單輪評測與端到端評測。
- 若要檢查整個任務是否達成,端到端評測會在環境中執行完整流程,再驗證結果。
AI 伴隨問答
針對這篇報導有疑問?可直接點選快捷問題或向 AI 追問背景脈絡與技術細節:
文章以咖啡訂單示範如何設計端到端 Agent 評測,並說明成功率與 Pass^k 回答不同可靠性問題,協助團隊選擇合適指標。
代理程式現在是軟體的使用者,會代表人們執行工作。無論你打造的是代理程式,還是它使用的軟體(API、CLI、MCP 伺服器、SDK),評估都能讓你衡量這些工作完成得有多好。
代理程式大概沒看到你的產品發表影片,也沒看到你在 101 號公路旁的廣告看板,但它們尋找和使用產品的流程,跟人類一樣:探索、選擇、存取和成功。
你可以為這個流程中的任何階段建立評估。這裡我們聚焦在最後一個階段:成功,也就是代理程式是否正確完成使用者的任務。
這比聽起來更難檢查。使用者要的是冰拿鐵,代理程式卻可能成功下單一杯熱拿鐵。訂單確實送出,因此可觀測性堆疊中的記錄看起來都正常。再加上 LLM 每次執行的輸出可能不同,單次手動測試無法告訴你修正是否有效。你需要重複執行相同任務,並在變更前後為結果評分。
評估正是能幫你做到這件事的工具。以下說明我們如何建立評估。
代理程式測試金字塔
如果測試問的是「有沒有成功?」,評估問的則是「成功的頻率有多高?品質有多好?」你交給代理程式一項任務,為結果評分,再彙整多次執行的結果。
我們依照通常需要的 LLM 呼叫次數,將代理程式軟體測試分為三類:確定性測試(0 次)、單回合評估(1 次),以及端對端評估(整項任務共 2 次以上)。實際上,這也很適合作為衡量建置成本、執行時間和執行成本的指標。就像實用測試金字塔所說,便宜又快速的測試應該佔測試套件的大部分。
使用金字塔時,先找出你想捕捉的問題,再挑選能捕捉它的最低層級。針對成功,答案是最頂層。單回合評估會檢查一項決策,例如代理程式首先執行哪個命令。但成功取決於整個步驟序列(例如搜尋咖啡店 → 依使用者條件篩選 → 下單購買拿鐵)。每個步驟單獨看都可能合理,代理程式最後仍可能得到錯誤結果。
端對端評估會讓代理程式在環境中完成整項任務,再檢查最終結果是否符合使用者的要求。你可能已經看過一些端對端評估;多數熱門的程式設計基準測試,例如SWE-bench和Terminal-Bench,都是端對端評估。
範例
假設你經營 SF Beans,這是在舊金山訂購咖啡的 API。透過 CLI 提供服務給代理程式,是其中一種最佳方式,因此你正準備推出 sfbeans。
以下是其中一位客戶常見的請求:
幫我買一杯大杯冰拿鐵,加全脂牛奶,9:00 前可以取餐,含小費在 $8 以下。我在 Mission 區。
以下是 sfbeans 在早上 8:30 掌握的資訊:
Fog City Roasters: 製冰機故障,所以今天沒有冰飲 (溫度)
24th St Beans:拿鐵選單價是 $7.50,但含稅和小費後要 $9.27 (預算)
Dolores Drip:拿鐵要 $5.50,但最早只能在 9:20 取餐 (時間)
Valencia Grind:含稅和小費後是 $7.42,8:50 就能取餐 (三項條件都符合)
以下是在金字塔各層級,針對 sfbeans 可以測試的內容:
如何建立端對端評估
我們會使用Harbor建立咖啡評估。Harbor 是由 Terminal-Bench 的創作者開發的開放原始碼框架,能在容器中執行代理程式、檢查結果並記錄其操作。
以下是本文會用到的術語:
任務:代理程式要解決的一個問題,包含起始環境和確認是否成功的方法
變體:你正在測試的代理程式設定,例如模型、提示、工具、記憶和技能
試驗:某個變體在某項任務上進行的一次嘗試
執行(Harbor 中的 工作):每個變體都在每項任務上嘗試多次
追蹤紀錄(Harbor 中的 軌跡):試驗期間記錄的所有內容,包括訊息、工具呼叫、記錄檔、檔案和最終輸出
步驟 1:設定目標
為所有專案建立端對端評估並不切實際。使用傳統軟體時,你可以力求達到 100% 的測試涵蓋率。但對代理程式來說,你需要涵蓋的範圍是 LLM 可能如何使用你的產品,而要弄清楚範圍的邊界在哪裡也很困難(請參閱鋸齒狀前沿)。
先從一個使用者在意、範圍小到能用少量任務評估的成果著手。通常可以從以下三個地方之一找到這個目標:
可觀測性:哪些代理程式會使用你的產品,以及它們在哪裡失敗
客戶:支援單、意見回饋和客戶流失
產品路線圖:你最需要驗證的產品假設
例如,你的目標可以是:
提高特定任務的成功率
減少完成目標所需的步驟
確認代理程式技能是否有幫助,並取得回饋以改進技能
對提示進行 A/B 測試
探索能力前沿,確認目前的 LLM 是否能完成某個使用情境;若失敗,則找出原因
範例
我們從這三個地方為 sfbeans 尋找線索:
可觀測性: 大多數代理程式流量來自 Claude Code 和 Codex。我們之所以知道,是因為
sfbeans偵測到特定的程式開發工具環境時,會加入 user-agent 標頭。客戶:最常見的支援單是「我的代理程式點錯飲料了」:點成熱拿鐵而非冰拿鐵、取餐時間排在使用者開會之後,或是加上稅金和小費後總額超出預算。
產品路線圖: 目前沒有急迫事項,因此先處理點錯飲料的問題,因為這會導致客戶流失。
因此,我們的目標是:
目標 | 提高正確點出使用者指定飲料的成功率 |
|---|---|
代理程式 | Claude Code 和 Codex,因為我們的流量來自這兩者。 |
範圍內 | 使用今天的 |
範圍外 | 取消、退款和帳戶。之後再評估這些專案。 |
完成條件 | 兩個代理程式在每次試驗中都正確完成訂單,而不是隻在大多數時候成功。 |
步驟 2:定義指標
以下是我們在端對端代理程式評估中最常使用的指標:
成功
效率(只在成功的試驗中測量)
步數:完成任務所需的代理程式回合數
時間:試驗花費的時間
成本:試驗花費的金額,以美元計
範例
我們的目標是在每次試驗中都正確完成訂單。在步驟 3 和 4 建立並執行評估後,Claude Code + Opus 5.5(在 anthropic/claude-opus-5.5 上使用 AI Gateway)針對冰拿鐵訂單進行五次試驗,可能會得到如下結果:
試驗 | 結果 | 發生情況 | 步數 | 時間 | 成本 |
|---|---|---|---|---|---|
1 | 通過 | 比較了 3 間咖啡店的報價,在 Valencia 下單 | 9 | 3:40 | $0.52 |
2 | 失敗:超出預算 | 略過報價,在 24th St 下單:$9.27 | 5 | 1:50 | $0.31 |
3 | 通過 | 比較了 4 間咖啡店的報價,在 Valencia 下單 | 11 | 4:30 | $0.68 |
4 | 失敗:太晚 | 在 Dolores 下單,準備時間為 9:20 | 6 | 2:10 | $0.35 |
5 | 通過 | 略過 Fog City,在 Valencia 下單 | 8 | 3:20 | $0.49 |
這些數字代表什麼:
成功率:5 次試驗中有 3 次通過,也就是 60%。
Pass@5:假設每次試驗彼此獨立,成功率為 60%,1 − 0.4^5 ≈ 99%。讓代理程式試 5 次,幾乎可以確定至少會答對一次。
Pass^5:0.6^5 ≈ 8%。代理程式連續 5 次都把訂單下對的機率。
步驟數:成功的試驗平均為 (9 + 11 + 8) / 3 ≈ 9 步。失敗的試驗步驟較少,因為代理程式跳過了報價等工作,所以效率只計算成功的試驗。
時間:成功的試驗約需 3:50。
費用:每次成功的試驗需 $0.56;但把付費進行的失敗試驗也算進去,每次成功的費用是 $2.35 / 3 = $0.78。
那 Opus 好用嗎?它的 99% pass@5 表示好用。它的 8% pass^5 則表示,使用者每個工作日都下單的話,有 92% 的機率會在某一週至少喝到一杯點錯的咖啡。這兩個數字都沒錯,只是回答不同問題:pass@5 問的是代理程式能不能把訂單下對,pass^5 問的則是代理程式每次都能不能下對。
哪個指標最重要,取決於失敗會讓使用者付出什麼代價。訂早晨咖啡的人沒有機會重試。如果代理程式點了熱拿鐵,或咖啡做好時火車已經開走,使用者就得付錢買錯咖啡,還會一早就心情不好。他們每天早上都需要點對,因此 sfbeans 會以 pass^5 為最佳化目標。
其他產品的容錯空間較大,因為失敗的成本低,而且在造成影響前就會被發現:
產品 | 失敗一次會讓使用者付出什麼代價 | 應優先採用的指標 |
|---|---|---|
幫我訂早晨咖啡 | 付錢買到錯的飲料、上班遲到、失去信任 | Pass^k |
附有測試套件的程式設計代理程式 | 多花時間和模型費用;代理程式會根據測試回饋修改程式碼並重試 | Pass@k |
撰寫一封由使用者審閱的電子郵件草稿 | 按下傳送前快速修改 | 成功率 |
整體平均值可能掩蓋某項任務經常失敗的情況,因此務必檢視各項任務的結果。而且只有 5 次試驗時,100% 代表「目前還沒看到失敗」,不代表「永遠不會失敗」。
步驟 3:設計任務集
在步驟 1 中,我們為評估設定了目標:提高代理程式點到使用者指定飲料的準確率。但代理程式無法直接執行目標,它需要一項任務:一個來自使用者實際需求的具體請求。
挑選難度足以讓你從執行結果中學到東西的任務。一組好的任務應涵蓋常見情況、容易讓代理程式出錯的邊緣情況,以及至少一項正確做法是不採取行動的請求。
每項任務都要定義以下部分:
指令:使用者的請求
環境:代理程式工作的場所,每次試驗的起始狀態都相同
驗證器:檢查最終狀態,最好逐項條件評分
已知可行的解法(選填):展示預期行為並通過驗證器的參考執行結果
你可以依照目標,讓環境的各個部分盡可能虛擬或貼近真實。OpenPipe 團隊寫了一篇很棒的文章,介紹他們如何為電子郵件研究代理程式定義環境。
範例
我們寫了四項任務,每項都是 tasks/ 裡的一個 Harbor 任務資料夾。
常見情況:
iced-latte-mission,也就是前面提到的訂單邊緣情況:
usual-unavailable,使用者常去的咖啡館沒有他要的飲料邊緣情況:
team-order,包含 6 杯飲料、總價 $45,以及一個取貨地點不要採取行動:
impossible-request,沒有任何選項符合條件,因此正確做法是告知使用者
impossible-request 多了一項檢查。它的驗證器會讀取代理程式無法寫入的命令記錄,確認代理程式在放棄前有先搜尋。我們是吃過苦頭後才知道需要這項檢查的(見步驟 5)。
以下是 iced-latte-mission:
指令會提供使用者的要求給代理程式,並指出 sfbeans CLI。在正式環境中,代理程式會透過技能、檔案或 MCP 伺服器找到工具。在這裡直接指定工具,就跳過了探索和選擇,讓評估專注於成功。
我們也指定時間是上午 8:30。只有 sfbeans 使用我們凍結的時鐘;沙箱的系統時鐘仍顯示真即時間:
環境一部分是真實的,一部分是模擬的。代理程式使用真實的 sfbeans CLI,但操作的是預先植入資料的咖啡館,並使用凍結的時鐘,因此每次試驗都從同一個早晨開始:
為了讓示範保持簡單,cafes.json 位於代理程式的環境中。在正式評估中,請保護種子資料和驗證程式碼,並確保代理程式只能透過 CLI 更新訂單記錄。代理程式可能會嘗試獎勵駭取來提高通過率,例如編輯庫存,或直接寫入 orders.json。
在這筆咖啡訂單中,驗證器會依據使用者的要求檢查最終訂單。代理程式完成後,Harbor 會執行 test.sh,並讀取它寫入 /logs/verifier/reward.json 的分數:
實際的檢查程式位於 check_orders.py。它會分別為每項條件評分,然後只有在所有條件都通過時,才將 reward 設為 1。Harbor 會使用 reward 作為試驗的主要分數:
解答是已知可行的答案。在執行任何正式代理程式之前,先執行它以確認任務可正常運作:
最後,task.toml 會串起整個任務。它會設定逾時時間,在代理程式的沙箱中執行驗證器(orders.json 位於其中),並將訂單儲存為產出檔案,方便我們在步驟 5 檢視:
步驟 4:執行評估
如果你也受不了緩慢的 CI,就會討厭等待評估完成。每次試驗都要等待代理程式逐步呼叫 LLM,而每次執行都會對每個變體和任務重複多次。
我們在上游建置的 HarborVercel 整合能大幅加快這個流程。它會在各自獨立的 Vercel Sandbox 中並行執行試驗,並快取已建置的任務環境,因此每次試驗都不必重新建置。透過 AI Gateway 路由模型呼叫,就能在不同模型供應商之間共用一組金鑰和預算。
範例
兩個代理程式,Claude Code 和 Codex,各搭配兩個模型,總共會產生四種變體。
接著安裝 Harbor、連結 Vercel 專案,再執行工作:
這次執行符合 Hobby 方案的限制:Hobby 方案最多支援 10 個並行沙箱,而且每次試驗都遠低於 45 分鐘的工作階段上限。在 Pro 方案中,n_concurrent_trials 可提高到 10,000(沙箱限制)。
為了讓範例保持簡單,我們將 OIDC 權杖作為環境變數傳入各個沙箱,代理程式可以在其中讀取。若要用於示範以外的情境,請使用短效權杖,並透過 Harbor 的 Vercel 整合設定 沙箱防火牆規則,將每次試驗限制為只能連線至所需的主機,例如 AI Gateway。
在內部,我們還會進一步使用憑證代理,將憑證附加至送出的請求,讓 API 金鑰留在代理程式環境之外。
步驟 5:分析追蹤記錄
接下來是最精彩的部分:深入檢視追蹤記錄。分數會告訴你代理程式失敗的頻率;追蹤記錄則能說明原因。請閱讀失敗案例,也看看部分成功案例,因為通過只代表驗證器認可了結果。
範例
步驟 4 的執行會在 jobs/sfbeans-baseline/ 留下 80 個試驗資料夾。每個資料夾都包含試驗結果、代理程式的執行軌跡、驗證器的分數,以及代理程式下的訂單(因為 task.toml 會將它儲存為產出檔案):
執行 harbor view jobs 來瀏覽結果。以下是四種變體可能呈現的報告(數字僅供示意)。
針對每個變體,我們會分別計算各項任務的成功率與 pass^5,再將各指標在四項任務間取平均。每項任務的權重相同。
變體 | 成功率 | Pass^5 | 成功時的平均步數 | 每次成功的成本(包含失敗嘗試) |
|---|---|---|---|---|
Claude Code + Opus 5.5 | 85% | 60% | 9 | $0.61 |
Claude Code + Sonnet 5.5 | 75% | 52% | 11 | $0.27 |
Codex + GPT-6 Astra | 80% | 43% | 8 | $0.48 |
Codex + GPT-6.1 Sol | 65% | 14% | 13 | $0.22 |
這就是我們的基準。在我們於步驟 2 選定的指標 pass^5 上,即使是表現最佳的變體,可靠度也遠遠不夠。但分數沒有告訴我們該修正什麼。要找出問題,就得檢視失敗的嘗試。
以步驟 2 的試驗 2 為例。Claude Code + Opus 5.5 在 24th St Beans 下單,花了 $9.27。驗證器會告訴我們它違反了哪項限制:
飲料正確、準時、超出預算,而儲存的 orders.json 證實總金額是 $9.27。現在來看 agent/trajectory.json。代理程式在 Mission 尋找拿鐵,看到選單上標價 $7.50,就直接前往 order。沒有 quote。它把選單價格當成最終價格。
同一個變體的試驗 1 則列出三家咖啡館的價格,排除 24th St Beans,並在 Valencia Grind 下單,花了 $7.42。由此可見,CLI 能正確下單,但代理程式不一定會在花用使用者的錢之前確認總金額。
接著,我們會檢查其他失敗嘗試,看看是否也有同樣的模式。如果這種情況一再出現,就能找出明確的修正方向:讓總金額更醒目,或新增 --max-total 旗標,讓 order 拒絕任何超出預算的訂單。這比「Opus 得分 85%」更有參考價值。
我們第一次執行這個示範時,追蹤記錄也揭露了評估內容本身的問題:
我們第一次執行時,所有變體的得分都是 0%。代理程式不知道
sfbeans的存在,所以根本沒有嘗試使用它(這很正常)。這表示我們自己的評估中,漏斗的探索階段出了問題。在指示中寫出工具名稱後,問題就解決了;這也提醒我們,產品必須容易被找到。在實際應用中,這是你的 skill、檔案、MCP 伺服器和 AEO 要負責的事。Codex 一直把
sfbeans當成已連線的工具來尋找,從未嘗試在 shell 中執行它。這是存取問題,而非成功問題。Codex 幾乎每次都通過了
impossible-request,但我們檢視追蹤記錄後發現,十次通過中有九次是代理程式什麼都沒查就放棄。驗證器只檢查是否沒有下單,因此我們加強驗證,也確認代理程式是否先搜尋過。若沒有檢視追蹤記錄,我們就會把這些情況都算成成功。
自動化追蹤記錄分析
執行規模較大時,逐一人工檢查每次試驗會很花時間,因此我們將這項工作自動化。
最多可讓 40 個讀取代理程式平行運作,使用 deepseek/deepseek-v4.1-flash 等快速模型閱讀試驗逐字稿並彙整發現。接著,由能力更強的協調代理程式檢視這些摘要,必要時要求讀取代理程式補充背景資訊,並撰寫最終報告。analysis.md 檔案會告訴協調代理程式要留意哪些內容,讓我們能在不同的執行工作中重複使用這套流程。
模型呼叫會透過 AI Gateway 進行。分析期間,試驗產出檔案會儲存在 Vercel Drives,追蹤記錄則會儲存至 Vercel Blob,以供長期儲存。
持續迭代,做到最好
第一次執行評估會提供基準。接下來就採取行動。
根據追蹤記錄指出的問題選擇修正方式,例如 --max-total 旗標,然後重新執行相同工作,並與基準比較。確認修正是否減少了目標失敗情況,且沒有帶來新的問題,再根據結果判斷是否已準備好發布變更。
建立評測後,它就能持續派上用場,協助處理各種工作。每次發布時重新執行,找出回歸問題;上線前測試提示、技能和模型的變更;瞭解代理如何使用你的產品;或以此為基礎建立自動最佳化迴圈。
隨著時間推移,預期需要加入更具挑戰性的任務。模型和產品有所進步後,評測可能會達到飽和,也就是代理開始通過所有任務。這對偵測回歸問題很有幫助,但無法告訴你接下來該改進什麼。
評測是你用來一次又一次改善產品的基礎架構。Vercel 在同一處提供建立評測所需的各項工具:可跨供應商呼叫模型的 AI Gateway、可大規模執行試驗的 Sandbox,以及用來儲存每筆追蹤資料的 Drives 和 Blob。
準備好執行第一個評測了嗎?將這段提示貼到你的程式碼代理中,它就會在 Vercel 上與你一起為產品建立並執行評測: