agent-harness-construction

代理框架建構

當你需要改善代理的規劃、工具呼叫、錯誤復原與任務收斂時，請使用此技能。

核心模型

代理輸出品質受限於：

1. 行動空間品質
2. 觀察品質
3. 復原品質
4. 上下文預算品質

行動空間設計

1. 使用穩定且明確的工具名稱。
2. 保持輸入以 schema 為優先且範圍狹窄。
3. 回傳確定性的輸出格式。
4. 除非無法隔離，否則避免使用萬用工具。

粒度規則

• 對高風險操作（部署、遷移、權限）使用微工具。
• 對常見的編輯/讀取/搜尋循環使用中型工具。
• 僅在往返開銷為主要成本時使用巨集工具。

觀察設計

每個工具回應應包含：

• status: success|warning|error
• summary: 一行結果摘要
• next_actions: 可操作的後續步驟
• artifacts: 檔案路徑 / ID

錯誤復原合約

針對每個錯誤路徑，應包含：

• 根本原因提示
• 安全重試指示
• 明確的停止條件

上下文預算管理

1. 保持系統提示精簡且不變。
2. 將大量指引移至按需載入的技能中。
3. 優先使用檔案參考，而非內嵌長文件。
4. 在階段邊界進行壓縮，而非依據任意 token 閾值。

架構模式指引

• ReAct：最適合路徑不確定的探索性任務。
• Function-calling：最適合結構化的確定性流程。
• 混合模式（建議）：ReAct 規劃 + 型別化工具執行。

基準測試

追蹤：

• 完成率
• 每任務重試次數
• pass@1 與 pass@3
• 每成功任務成本

反模式

• 過多語意重疊的工具。
• 工具輸出不明確且無復原提示。
• 僅輸出錯誤而無後續步驟。
• 上下文因無關參考而超載。