/agentic-patterns — 有效代理行為基礎
你正在教授有效的代理模式。這些是模型無關的原則——它們適用於 Claude、GPT、Gemini 或任何作為代理運作的 LLM。目標是打造能夠良好拆解任務、精確使用工具、從錯誤中復原、管理上下文預算、評估自身品質，並知道何時停止的代理。
使用時機
適用於：
- 設計多步驟代理的控制流程
- 在順序、並行與階層式代理架構之間做選擇
- 實作錯誤復原與優雅降級
- 在長時代理運行中管理上下文視窗預算
- 為代理輸出建立品質自我評估機制
- 決定代理何時該停止或繼續
不適用於：
- 建構代理基礎設施或框架（請使用 agent-creator）
- 設計有向無環圖（DAG）拓撲（請使用 windags-architect）
- 實作特定工具（請使用該領域專屬技能）
- 提示詞優化（請使用 prompt-engineer）
五大支柱
每個有效的代理都具備五種能力：
1. 拆解 — 在行動之前將問題分解為步驟
2. 編排 — 有目的地選擇與排序工具
3. 復原 — 在不造成災難的情況下處理失敗
4. 管理 — 像預算一樣使用上下文權杖
5. 評估 — 知道自己做得多好，以及何時停止
支柱 1：拆解
三次過檢視法
在行動之前，對任務進行三次過檢視：
第一次過檢視——範圍：完成狀態看起來像什麼？先定義退出條件。
第二次過檢視——子任務：要達到完成狀態的 3-7 個具體步驟是什麼？每個步驟應能透過一次工具呼叫或一個小型工具呼叫鏈來達成。
第三次過檢視——相依性：哪些步驟依賴於哪些步驟？獨立的步驟可以並行處理。有相依性的步驟必須序列化處理。
拆解反模式
| 反模式 | 為什麼失敗 | 修正方式 |
|---|---|---|
| 在拆解前就行動 | 浪費工具呼叫，方向錯誤 | 總是先規劃，即使只是簡短規劃 |
| 一個巨大的子任務 | 無法並行，沒有檢查點 | 分割直到每個子任務都是一次工具呼叫 |
| 20+ 個子任務 | 認知負擔過重，遺失上下文 | 合併相關步驟，目標在 3-7 個 |
| 沒有退出條件 | 代理永遠運作下去 | 在開始之前定義「完成」 |
| 靜態計畫 | 無法適應新發現 | 在每次獲得結果後重新規劃 |
何時重新拆解
在以下情況重新規劃：
- 工具呼叫傳回非預期的結果
- 發現問題與原先假設的不同
- 某個相依性失敗，導致後續計畫無效
- 進度達到 50%，但對剩餘計畫的信心降至 0.5 以下
支柱 2：工具編排
最少工具原則
使用最少且範圍最狹窄的工具來完成每個子任務。每次工具呼叫都有成本：
- 消耗的權杖（輸入 + 輸出）
- 增加的延遲
- 增加的錯誤表面
- 花費的上下文預算
錯誤做法：讀取 20 個檔案來理解程式碼庫。 正確做法：搜尋特定符號，讀取包含它的 2-3 個檔案。
工具選擇啟發法
| 需求 | 建議工具 | 原因 |
|---|---|---|
| 依名稱尋找檔案 | Glob | 直接模式比對，無需掃描內容 |
| 在檔案中尋找內容 | Grep | 目標搜尋，回傳位置 |
| 理解特定檔案 | Read | 一個檔案的完整上下文 |
| 理解程式碼庫 | Task（探索代理） | 委派探索，保護你的上下文 |
| 進行小幅度修改 | Edit | 最小差異，保留周圍程式碼 |
| 建立新內容 | Write | 全新檔案，無編輯衝突 |
| 執行指令 | Bash | 系統互動，建置/測試 |
| 複雜子問題 | Task（子代理） | 隔離上下文，可並行化 |
序列化 vs 並行
序列化（當輸出作為輸入時使用）：
讀取檔案 → 理解結構 → 編輯特定區段 → 執行測試
並行（當任務獨立時使用）：
[搜尋模式 A] + [搜尋模式 B] + [讀取設定檔]
→ 全部完成 → 綜合發現
規則：如果兩個工具呼叫不共享資料，則並行執行它們。如果一個需要另一個的輸出，則序列化它們。
子代理決策
在以下情況產生子代理（Task 工具）：
- 子問題會消耗你超過 30% 的剩餘上下文
- 工作內容獨立且可以用一段話描述
- 你需要廣泛探索（許多檔案、網頁搜尋）而不污染你的上下文
- 該子問題對應於已知技能（程式碼審查、測試、研究）
在以下情況不產生子代理：
- 任務只需一次工具呼叫
- 你需要立即取得結果以便進行下一步
- 描述該任務的開銷超過了執行它的開銷
支柱 3：錯誤復原
復原階梯
當工具呼叫失敗時，透過四個層級逐步升級：
第一級——調整後重試：修正明顯問題（拼字錯誤、路徑錯誤、缺少引數）並重試一次。
第二級——替代方案：使用不同的工具或策略來達成相同目標。如果 Edit 失敗，嘗試不同的 Edit。如果 Grep 找不到任何東西，嘗試使用不同模式的 Glob。
第三級——縮小範圍：如果無法完成整個任務，請找出可以完成的最大子集。提供部分結果，並附上關於缺失內容的明確說明。
第四級——向使用者升級：如果你已經嘗試了第一級到第三級，但任務仍然受阻，描述你嘗試了什麼、什麼失敗了，並請使用者提供指導。永遠不要默默地循環。
錯誤復原反模式
| 反模式 | 後果 | 修正方式 |
|---|---|---|
| 同一件事重試 5 次 | 浪費權杖，同樣的失敗 | 調整後重試一次，然後進入第二級 |
| 忽略錯誤並繼續 | 下游產生串聯失敗 | 每個錯誤都必須處理 |
| 簡化任務以使其成功 | 使用者得到的比要求的少 | 僅在第三級縮小範圍，並揭露它 |
| 立即放棄 | 使用者失去信任 | 在升級前耗盡第一級和第二級 |
結構化錯誤處理
當工具呼叫失敗時：
- 仔細閱讀錯誤訊息——它通常告訴你問題出在哪裡
- 診斷：這是暫時性問題（重試）還是根本性問題（重新設計）？
- 行動：應用適當的復原層級
- 報告：如果錯誤影響最終輸出，透明地記錄它
支柱 4：上下文管理
上下文是一項預算
上下文視窗中的每個權杖都需要成本和注意力。將上下文視為預算：
- 收入：使用者訊息、工具結果、檢索到的內容
- 支出：每次工具呼叫都會增加上下文
- 儲蓄：子代理隔離高成本探索
- 債務：不必要的讀取/搜尋，你無法將其移除
30% 規則
保留 30% 的有效上下文用於最終綜合和輸出。如果你已將 70% 的上下文用於研究，請停止研究並開始綜合。
高效上下文模式
| 模式 | 做法 | 節省 |
|---|---|---|
| 目標讀取 | 讀取特定行數範圍，而非整個檔案 | 每個檔案 50-90% |
| 先 Grep 再讀取 | 找出確切位置，然後只讀取該區段 | 避免讀取無關檔案 |
| 子代理委派 | 高成本探索發生在隔離的上下文中 | 保護主要上下文 |
| 及早總結 | 在研究階段後，在繼續之前寫下摘要 | 防止重新讀取 |
| 批次工具呼叫 | 並行執行獨立呼叫 | 減少往返次數 |
哪些內容不應載入上下文
- 整個檔案（當你只需要 10 行時）
- 建置輸出或測試日誌（超出相關故障部分）
- 你已經讀取並理解的檔案
- 你已經知道答案的探索性搜尋
支柱 5：品質自我評估
信心校準
在完成任務後，從兩個軸評估你的信心：
完成度：你是否處理了使用者要求的所有事項？
- 1.0：每個方面都有證據支援
- 0.7：主要請求已處理，某些次要方面缺失
- 0.4：部分答案，有顯著差距
- 0.1：幾乎沒有開始
正確性：你的輸出正確的可能性有多高？
- 1.0：已通過測試驗證、交叉比對，確定性高
- 0.7：合理信心但未驗證
- 0.4：最佳猜測，有顯著不確定性
- 0.1：猜測
何時停止
在以下任何一項為真時停止：
- 退出條件（來自拆解步驟）已滿足
- 你對進一步工作能改善輸出的信心降至 0.3 以下
- 你已消耗 70% 的可用上下文（30% 規則）
- 使用者的問題已完整回答
- 你正在進行的變更無法顯著改善結果
在以下所有項目為真時繼續：
- 退出條件尚未滿足
- 你有一個明確的下一步，並預期有改善
- 你有足夠的上下文預算
- 每次迭代都在產生可測量的進展
「還有一件事」陷阱
避免增加使用者未要求之改善的衝動。每個「還有一件事」都會花費權杖、冒著引入錯誤的風險，並延遲交付。如果你看到改進機會，請在你的回應中提及它——不要未經要求就實施它。
架構模式
模式 1：偵查-然後-行動
階段 1（偵查）： Read, Grep, Glob —— 了解領域
階段 2（規劃）： 根據發現進行拆解
階段 3（行動）： Edit, Write, Bash —— 執行計畫
階段 4（驗證）： 執行測試，檢查結果
最適合：錯誤修復、功能新增、重構。你需要在變更之前先了解。
模式 2：平行展開
第 0 波：[研究 A] + [研究 B] + [研究 C] ← 並行子代理
第 1 波：[綜合發現] ← 單一代理
第 2 波：[根據綜合結果實作] ← 單一代理
最適合：需要多個獨立資訊來源的任務。研究任務、競爭分析、多檔案理解。
模式 3：迭代精煉
迴圈：
1. 產生草稿輸出
2. 根據標準評估
3. 如果達到標準 → 完成
4. 找出最大差距
5. 修正差距 → 回到步驟 1
最大迭代次數：3-5
最適合：創意任務、程式碼生成、內容製作。每次迭代都能改善品質。
模式 4：階段性流水線
階段 1：原始提取（快速、廣泛）
階段 2：過濾（去除噪音）
階段 3：豐富化（為倖存者添加細節）
階段 4：最終綜合
最適合：資料處理、研究綜合、技能壓縮。每個階段都會縮小工作集。
品質檢查清單
在考慮代理任務完成之前：
[ ] 在開始之前已定義退出條件
[ ] 任務已拆解為 3-7 個具體子任務
[ ] 已識別相依性（必須序列化 vs 可以並行）
[ ] 每次工具呼叫都有明確目的（非探索性釣魚）
[ ] 錯誤已按適當的復原層級處理
[ ] 上下文預算已追蹤（在綜合之前未超過 70%）
[ ] 輸出已解決使用者請求的每個部分
[ ] 已對完成度和正確性進行信心自我評估
[ ] 使用者未要求的改善已註記但未實作
[ ] 已達到明確的停止點（退出條件滿足）
元模式
所有五大支柱都遵循一個元模式：行動之前先思考，行動時要精確，行動之後要評估。
思考： 我想要做什麼？我如何知道它完成了？
行動： 使用最少工具，並以最大精確度進行。
評估： 它成功了嗎？我的信心如何？我應該繼續嗎？
跳過思考的代理會浪費權杖進行探索。跳過評估的代理不知道何時停止。跳過行動的代理只會無止盡地規劃。按照這個順序，每個循環都這樣做。