核心概念

程式碼代理（code agent）正越來越多地取代人類直接使用軟體函式庫：它們接收任務描述、選擇函式庫、撰寫呼叫程式碼、執行並除錯錯誤。這引入了一個新的設計命題——函式庫不僅要正確且快速，還要被設計成讓代理能有效驅動。

Hugging Face 工程師（Lysandre、Nathan Habib 等）將這個命題化為可量測問題，開源了 agent-eval 框架，針對自家 transformers 函式庫驗證：「我的函式庫對代理來說夠好用嗎？」

三層評估環境（Tiers）

框架定義了三個資訊暴露程度遞增的測試層：

Tier 說明
bare 僅 pip install，無額外文件
clone 完整原始碼，含 README
skill CLI 文件 + 任務範例的打包說明書

評估指標

除傳統的最終答案正確率（match %），框架還追蹤：

  • 執行時間：中位數速度
  • token 消耗：計算成本
  • 錯誤率：無輸出或執行失敗的比例
  • 標記採用率（Markers）：代理是否真的走了預期的 API 路徑（例如 cli 或 pipeline 模式）

正確率只是入場券，成本和路徑選擇才是真正的健康指標。

關鍵要點

1. Skill tier 對大型模型有益，對小型模型可能有害

固定 transformers 版本、測試不同大小的開源模型後：大型模型在 Skill tier 速度最快，CLI 採用率高達 55.3%。但小型模型會被額外文件壓垮。

最典型案例是 Qwen3-14B：在 clone tier 正確率 100%，引入 Skill tier 後跌至 0%。56 次 Skill 執行中有 39 次，模型把 CLI 文件誤認為可呼叫工具，試圖發出 transformers(command="classify", ...) 的 tool call——但該工具不在可用工具集中，模型因此放棄任務。

2. CLI 帶來速度但增加 token 消耗

引入 CLI 功能後，clone tier 約三分之一的執行會讀取 /cli/ 樹與範例腳本，中位數新 token 從 ~4k 跳至 ~6.4k。速度提升，但首次使用成本更高；多次執行後模型記憶化 CLI 模式才攤銷。

3. 小型模型面對大量新文件會 token 爆炸

Qwen3-4B 在 clone tier 面對大量新程式碼時，中位數新 token 從 ~2.4k 暴增至 ~23k（10 倍），正確率卻毫無提升。新功能文件對小型模型是認知負擔而非使用說明書。

4. 跨模型大小測試是必要前置步驟

同一個 CLI 功能對大型模型是效率提升，對小型模型是歧義來源。任何代理端 API 設計者都需要跨大小模型（4B → 14B → 70B+）驗證，確保新功能不造成回歸。與 MagenticLite：為小型模型優化的代理系統三層架構 的核心發現一致：小型模型需要不同的設計策略。

實務應用

pip install agent-eval
agent-eval run <config>                     # 執行測試套件
agent-eval fan-out models revisions tasks   # 在 HF Jobs 上擴展

每次執行在獨立的 HF Job 上進行，確保硬體公平性；結果存在 HF Bucket，可發布為互動式 Space 報告（含 Agent Traces Viewer 逐步檢視）。

傳統開發思維 Agent-first 思維
測試最終答案 同時測量 token、時間、失敗率
最大模型測試 跨大小模型全面驗證
上線後觀察 PR 提交前先跑 agent-eval

函式庫的「代理友善度」是可量測的，應像測試覆蓋率一樣納入開發流程。

相關評估框架可參考：Open Agent Leaderboard：通用代理系統的開放評估框架、AI Eval 成本危機：評估比訓練更貴、EVA-Bench 2.0：企業語音代理三領域評估基準

延伸觀點

小型模型不是靠「更多文件」學，而是靠「更嚴格的結構」

HuggingFace 的實驗發現小型模型被 Skill tier 的文件壓垮，多篇論文提出了解方：不是減少文件，而是改變呈現格式。透過 guided decoding（引導解碼）、嚴格的 JSON Schema 輸出約束、以及型別安全函數登錄，1-12B 的小型模型在工具呼叫精度上可比肩大型模型，成本卻低 10-100 倍（arXiv 2510.03847）。Qwen3-14B 的失敗案例正說明了這點：它看到文件就試圖呼叫「工具」，若把 CLI 包裝成嚴格 schema 而非自由文本，這個問題很可能不會發生。

工具品質本身是被低估的評估維度

OPENTOOLS（arXiv 2604.00137）指出，絕大多數評估研究只測量「代理用工具的準確率」，卻忽略了「工具本身的正確性」。換句話說，代理把 CLI 呼叫對了，但 CLI 輸出格式有 bug 導致任務失敗，傳統 match % 指標會錯誤地歸咎於代理。OPENTOOLS 在高品質工具上取得了 6-22% 的相對性能提升。Agent-eval 的 Markers 機制（追蹤代理是否走了預期路徑）是往這個方向的正確一步，但評估工具輸出品質本身仍是待補的缺口。

實用策略：SLM 優先、LLM 回退

對函式庫設計者最直接的建議：不要假設代理使用大型模型。先用 4B 模型跑測試套件作為煙霧測試，失敗才升級到大型模型。這個「SLM 預設、LLM 回退」策略既能及早發現小型模型的歧義問題，也能控制評估成本。

反向連結

以下頁面引用了本頁：