How to Design a Production-Grade CAMEL Multi-Agent System with Planning, Tool Use, Self-Consistency, and Critique-Driven Refinement
五代理自洽採樣加 8.5 分停止門檻：CAMEL 多代理框架生產級管線實作教學
- 五個代理按確定性需求設溫度（0.0-0.3），Pydantic 2.x Schema 在每步邊界驗證 LLM 輸出
- Self-Consistency 雙草稿加零溫 Chooser 選優，系統性對沖 LLM 輸出隨機性
- 8.5 分或輪次上限二選一停止精煉迴圈，避免代理無限改稿的工程陷阱
一套多代理系統裡，第六個 AI 代理被臨時召喚來挑選最佳草稿、然後消失——只有當 Critic 給出 8.5/10 的評分，整個管線才停止輸出。本文的 CAMEL 教學把這個邏輯壓進不到 300 行 Python，示範如何搭建一套兼具網路搜尋工具、自洽採樣和批評驅動精煉的生產級多代理管線。
CAMEL 框架的五代理架構：Planner 到 Critic 各司其職
CAMEL（Communicative Agents for Mind Exploration of Large Language Model Society）是一個開源多代理編排框架，讓多個 LLM（大型語言模型）代理以結構化方式協作完成複雜任務。本教學的系統設計圍繞五個專責代理展開，每個代理有明確的角色邊界、溫度設定和輸出格式。
Planner（規劃師）：溫度 0.1，接近確定性，負責把模糊目標分解成帶有 ID、標題、目標、交付物、工具提示和風險清單的結構化計畫，輸出必須符合 Plan / PlanTask Pydantic 模型。Researcher（研究員）：溫度 0.2，配備 DuckDuckGo 網路搜尋工具，每個任務最多執行 2 次搜尋，優先查詢官方文件和 GitHub，輸出 EvidenceItem JSON。Writer（撰寫員）：溫度 0.3（允許較高創意），接收計畫與研究結果，輸出純文字技術文件，明確禁止捏造引用。Critic（批評者）：溫度 0.0（完全確定性），輸出含有 0-10 分評分、優點清單、問題清單和修復計畫的 Critique JSON。Rewriter（改稿者）：溫度 0.25，依據批評意見修改草稿並保持事實準確性。
溫度設定遵循清晰原則：需要確定性的角色（Planner 規劃、Critic 評分）溫度趨近於零；需要創意輸出的角色（Writer 撰稿）溫度略高。這種設計讓每個代理在確定性和創意彈性之間各自找到平衡點。
| 代理 | 溫度 | 輸出格式 | 特殊配備 |
|---|---|---|---|
| Planner（規劃師） | 0.1 | Plan / PlanTask JSON | — |
| Researcher（研究員） | 0.2 | EvidenceItem JSON | DuckDuckGo 搜尋工具 |
| Writer（撰寫員） | 0.3 | 純文字草稿 | — |
| Critic（批評者） | 0.0 | Critique JSON（評分 0-10） | — |
| Rewriter（改稿者） | 0.25 | 純文字改稿 | — |
| Chooser（臨時選優器） | 0.0 | 返回最佳草稿原文 | — |
溫度設定遵循「任務確定性越高，溫度越低」原則；Chooser 為臨時第六代理，僅在自洽採樣時召喚
Pydantic 2.x Schema 驗證：LLM 自由輸出變可信資料
多代理系統最難解決的工程問題之一，是讓 LLM 的自由文字輸出穩定進入下游資料結構。本系統使用 Pydantic 2.7+ 定義了五種核心 Schema：Plan、PlanTask、EvidenceItem、Critique 和 RunConfig，每個 Schema 附有 Field 層級的約束（min_length=1、ge=0、le=10 等）自動驗證。
針對 LLM 的常見格式問題（在 JSON 外包 markdown 代碼圍欄、輸出多餘文字），系統提供兩個工具函數：strip_code_fences() 移除圍欄，extract_first_json_object() 從混合文字中提取第一個完整 JSON 物件。解析流程採用雙層容錯：先嘗試 model_validate_json() 直接解析，失敗則降級為 json.loads() + model_validate()。
這種「先結構化、再容錯降級」的設計確保管線在 LLM 輸出格式抖動時仍能持續執行，而非因格式偏差整條崩潰。對生產部署而言，Schema 驗證讓代理間的通訊協議像函數型別簽名一樣可審計——任何格式偏差都在邊界上被攔截，而非默默傳播成難以追蹤的邏輯錯誤。
Self-Consistency 雙草稿抽樣與第六代理選優
Self-Consistency（自洽採樣）是改善 LLM 輸出品質的常見技巧：對同一輸入生成多個獨立回應，再選出最佳版本，以對沖模型的隨機性。本系統預設 self_consistency_samples=2，由 Writer 代理獨立生成兩份草稿，再交給一個臨時的 Chooser（選擇器）代理評估。
Chooser 是系統中唯一的臨時代理——僅在自洽採樣完成後被召喚，完成評選後即消失。它使用溫度 0.0，從正確性、清晰度和可操作性三個維度評估所有候選草稿，直接返回最優者的完整文字，不做任何改寫。當 samples=1 時，系統自動跳過 Chooser，避免多餘的 API 呼叫。提高 self_consistency_samples 可進一步提升輸出穩定性，但 Token 消耗成倍增加，需根據成本預算權衡。
這個設計把「集成推理（ensemble reasoning）」的思路引入文字生成：單一高溫採樣有隨機風險，多樣本加零溫評判能有效對沖，且評判本身不引入新的隨機性。
8.5 分停止門檻與 Critic-Rewriter 迴圈設計
Critic 代理以 0.0 溫度運行，確保每次評分結果具備確定性和可重複性。迴圈的停止條件設計為二選一：若 score_0_to_10 >= 8.5 或已達到 max_revision_rounds（預設 1）上限，則跳出迴圈直接輸出；否則 Rewriter 依據 fix_plan 清單改稿後進入下一輪評估。
這個設計刻意避免了「讓代理自行判斷何時滿意」的陷阱。沒有外部停止條件時，LLM 代理可能無限迭代或過早停止；數值門檻加輪次上限的二選一終止，是一種工程上務實的選擇，適合預算受限的生產環境。評分時，Critic 的 strengths、issues 和 fix_plan 三個欄位都透過 rich 庫渲染成帶顏色的面板，讓每一輪的改善路徑一目了然，大幅降低調試成本。
完整的 run() 函數把所有步驟線性串聯：plan_goal() → research_task() × N → draft_with_self_consistency() → critique_text() + revise() 迴圈 → 最終輸出。整個流程從目標字串輸入到最終文字輸出，除了必要的 API 呼叫之外，沒有任何人工介入點。
模組化架構設計：DuckDuckGo 整合與 RunConfig 統一管理
本系統的模組化優勢在於：每個代理透過 ChatAgent 介面封裝，替換任何代理（包括底層 LLM、溫度設定、系統提示）不影響其他代理的運行。所有代理均使用 GPT-4o，透過 CAMEL 的 ModelFactory 以 ModelPlatformType.OPENAI + ModelType.GPT_4O 統一配置，理論上只需修改 ModelPlatformType 即可替換為其他 LLM 提供者。
工具呼叫（tool use）的整合也保持同等模組化：DuckDuckGo 搜尋以 SearchToolkit().search_duckduckgo 形式作為參數傳遞給 Researcher 的 tools，代理自動決定何時呼叫工具，搜尋次數受 max_searches_per_task 上限控制。RunConfig Pydantic 模型統一管理所有執行參數（max_tasks=5、max_searches_per_task=2、max_revision_rounds=1、self_consistency_samples=2），讓系統行為完全可配置，不需修改管線邏輯本身。
配置與邏輯分離、Schema 強制通訊協議、溫度按角色確定性設定——這三個設計原則貫穿整個系統，展示了從「Prompt 工程」向「代理架構工程」演進的具體實踐方式。
結構化 Schema + 量化停止門檻，才是讓多代理管線在生產環境真正可信的工程解法。