CrewAI 除錯指南：新手最常爆的 8 個雷與最快排查路徑
真相時間：Agent 開發不是最難的部分，除錯才是。
你會花不少時間盯著輸出想「為什麼這次格式又不一樣」、「明明有工具但 Agent 沒用它」、「第二個 Task 怎麼什麼都不知道」。這篇幫你把最常踩的雷整理成一張地圖，讓你少繞一些彎路。
8 個最常見問題快速對照
| 現象 | 常見原因 | 快速解法 |
|---|---|---|
| 輸出格式每次不同 | expected_output 太模糊 |
加入明確格式規範，或改用 output_pydantic |
| 後續 Task 拿不到前面資料 | 缺 context |
在 tasks.yaml 或 Task 物件明確加入 context |
| Tool 完全沒被呼叫 | Task 描述沒提到工具使用條件 | 在 description 裡加「Use the X tool first」 |
| 成本暴增 | Task 太長、重複呼叫模型 | 任務拆小、縮短 prompt、加快取機制 |
| 回答幻覺嚴重 | 缺來源約束 | 要求 expected_output 包含 source URL |
| 流程卡在某個步驟 | router 回傳值沒有對應的 listener | 檢查所有可能的 router 回傳值，確認都有 listener |
| 啟動就報錯 | 環境變數未設定 | 檢查 .env 裡的 API Key，確認 crewai install 跑完 |
| 表現忽好忽壞 | 測試輸入每次不固定 | 建立固定測試輸入與驗收規則，用同一份輸入做比較 |
除錯要按順序，別一出問題就怪模型
很多人碰到問題，第一反應是「是不是模型不夠聰明」或者「要不要換 GPT-4o」——這個直覺大多數時候是錯的。
按這個順序查，命中率最高：
第一步：查配置
先看 agents.yaml 和 tasks.yaml。角色設定是不是有意義？Task 描述是不是清楚？expected_output 有沒有格式要求？context 有沒有串好？80% 的問題在這裡。
第二步：查輸入
inputs 的資料是不是穩定的？如果你用動態資料做測試，你根本沒辦法判斷輸出是否變好或變差。先用固定輸入，確認行為可重現。
第三步：查工具
Tool 有沒有被呼叫（看 verbose 輸出）？參數對不對？回傳格式有沒有模型能解析的結構？
第四步：才考慮模型
確認前三步都沒問題了，再考慮是否要調模型的溫度、上下文長度，或換一個模型試試。
順序不要反過來。大部分的「模型問題」，查下去都是 YAML 少一行或者 Task 描述太模糊。
一個被低估的除錯技巧
每個 Task 加一個「輸出自我檢查」的要求，像這樣：
research_task:
expected_output: >
A markdown bullet list with 8-10 items.
Each item MUST include: title, summary (2 sentences), and source URL.
At the end, add a one-line self-check: "✅ All items have title, summary, and source."讓模型在完成任務之後自己確認輸出是否符合格式，是一種低成本的「流程內單元測試」。不是 100% 可靠，但可以抓到很多格式不符的情況。
另一個有效的做法是加「負面要求」——明確告訴模型什麼不要做：
description: >
Research {topic}. Use the search tool to find current information.
Do NOT include information published before 2025.
Do NOT make up sources — if you don't have a URL, write "source not found".這兩種寫法比「加長 expected_output 到 200 字」效果好很多。
verbose 模式：開著，永遠開著
開發期間 verbose=True 一定要開——它會讓你在終端看到每個 Agent 的思考過程、工具呼叫記錄、和每個 Task 的輸出。沒有這個，你只能看到最終結果，完全不知道哪一步出了問題。
生產環境可以關掉，開發和測試期間這個開關值那個 API 費的。
常見問題
Q：expected_output 寫很詳細了，輸出還是會飄，怎麼辦？
試試 output_pydantic——把格式從「文字描述」變成「強制 schema 驗證」。如果連 Pydantic 也過不了，才要考慮是不是任務本身太複雜需要拆分。
Q：Tool 有被呼叫，但回傳的資料 Agent 沒有用到，怎麼辦？
可能是 Tool 回傳的格式太難解析。把 Tool 的回傳改成清楚的結構化字串，並在 Task description 裡說明「根據工具回傳的 X 欄位來...」。
Q：流程有時候會突然超出 context window，怎麼辦？
把任務拆小，每個 Task 只做一件事，不要讓單一任務的輸出太長。有些情況也可以加 max_iter（最大迭代次數）來限制模型的回答長度。
Q：同一個流程，今天跑和明天跑結果差很多，怎麼辦？
兩個方向：一是固定測試輸入，確認是輸入造成的差異還是模型本身的隨機性；二是調低模型溫度（temperature），降低輸出的隨機程度。
下一步
雷大概都知道在哪了。最後一篇把前面全部串起來，看看一個可以真正上線的 CrewAI 系統長什麼樣：
👉 上線最佳實踐