CrewAI デバッグとよくあるエラー：初心者が最も踏みやすい 8 つの地雷
3 min read
正直な話、Agent 開発で一番時間を使うのは実装より デバッグ です。
このページは遠回りを減らすための地雷マップです。
よくある 8 問題
| 現象 | 主な原因 | すぐできる対処 |
|---|---|---|
| 出力形式が毎回違う | expected_output が曖昧 |
形式要件を追加、必要なら output_pydantic |
| 後続 Task がデータを受け取れない | context がない |
tasks.yaml で明示的に接続 |
| Tool が呼ばれない | Task 指示に使用条件がない | 「先に Tool 使用」を必須化 |
| コスト急増 | タスクが長い、重複呼び出し | タスク分割、プロンプト短縮、キャッシュ |
| 幻覚が多い | 出典制約なし | source URL と引用形式を必須化 |
| フローが停止する | 分岐条件が不完全 | router の戻り値と listener 対応確認 |
| 起動直後に失敗 | 環境変数未設定 | .env と API キー確認 |
| 品質が安定しない | テスト入力が固定されていない | 固定入力と受け入れ基準を作成 |
おすすめのデバッグ順
- 設定確認：
agents.yaml、tasks.yaml - 入力確認：
inputsが安定しているか - Tool 確認：引数と返却形式
- 最後にモデル確認：温度、文脈長、コスト
順番を逆にしないこと。モデルのせいに見えて、実は YAML 1 行不足というケースは多いです。
便利な小技
各 Task に「出力サマリ」と「重要項目チェック」を追加します:
- 結論があるか
- 出典があるか
- markdown 構造に沿っているか
これはワークフロー内のミニ単体テストとして機能します。
次へ
最終回では、ここまでの内容を本番運用指針として統合します。
👉 本番運用ベストプラクティス