CrewAI 快速上手：10 分鐘建立第一個研究 Crew

學新工具最容易卡在「還沒看到成果就先被設定地雷炸死」。

這篇的目標只有一個：你跟著做完，就能跑出第一份 AI 研究報告。其他進階概念先不談，先讓你看到東西跑起來，有感覺再深入。

建立專案

crewai create crew latest-ai-notes
cd latest-ai-notes

這個指令會幫你建好基本骨架，你不用從空目錄開始手刻：

src/latest_ai_notes/
├── config/
│   ├── agents.yaml    ← 定義角色
│   └── tasks.yaml     ← 定義任務
├── crew.py            ← 組裝 Crew
└── main.py            ← 執行入口

安裝依賴

crewai install

這個指令會自動讀取專案設定、建立虛擬環境、安裝所有套件。不用自己拼一堆 pip install，直接跑就好。

第一次執行會下載模型相關的東西，速度取決於你的網路——端杯咖啡，大約等個 30 秒到 2 分鐘。

設定 Agent

打開 config/agents.yaml，改成這樣：

researcher:
  role: >
    {topic} Researcher
  goal: >
    Find useful and current information about {topic}
  backstory: >
    You are good at collecting reliable information and summarizing key points.
 
reporter:
  role: >
    {topic} Reporter
  goal: >
    Convert research notes into a readable markdown report
  backstory: >
    You explain technical topics with simple language and clear structure.

這裡定義了兩個角色：一個負責找資料，一個負責把資料寫成報告。{topic} 是執行時傳入的變數，後面會看到怎麼用。

設定 Task

打開 config/tasks.yaml，改成這樣：

research_task:
  description: >
    Research {topic}. Focus on trends, tools, and practical examples in 2026.
  expected_output: >
    10 bullet points with short explanations.
    Each bullet must include: title, summary (1-2 sentences), and source URL if available.
  agent: researcher
 
report_task:
  description: >
    Expand the research notes into a complete markdown article for beginners.
  expected_output: >
    A beginner-friendly markdown report with: introduction, 3 main sections, and conclusion.
    Tone: practical and accessible.
  agent: reporter
  context:
    - research_task
  output_file: output/report.md

context: [research_task] 這行很關鍵——它告訴 report_task 要吃 research_task 的輸出結果。少了這行，reporter 會自己憑空猜測，而不是真的用研究員找到的資料。

執行 Crew

crewai run

成功的話，output/report.md 會出現你的第一份 AI 生成報告。

第一次跑如果有延遲很正常——模型呼叫就像貓主子起床，要等一下才會理你。通常 30 秒到 2 分鐘內會完成。

跑出來是什麼感覺？

終端機會顯示每個 Agent 的執行過程，你可以看到研究員在查哪些資料、reporter 怎麼組織報告。verbose=True 預設開啟，這個在除錯時非常有用，先別關掉。

跑完後，output/report.md 裡會有一份結構化的 markdown 報告。第一次看到的感受通常是：「這東西還真的跑起來了。」

常見問題

問題	原因	解法
`API key missing`	環境變數未設定	在 `.env` 加入 `OPENAI_API_KEY=你的key`
`Module not found`	依賴沒裝完整	重新執行 `crewai install`
輸出很飄、格式亂	`expected_output` 描述太模糊	加入明確格式要求（markdown 段落、幾個 bullet、要不要 URL）
第二個任務沒吃到第一個的資料	忘記加 `context`	在 `tasks.yaml` 的 `report_task` 加上 `context: [research_task]`

Q：可以改換其他主題嗎？
可以。在 main.py 找到 inputs 這個 dict，把 topic 的值改成你想研究的任何東西。

Q：需要 OpenAI 以外的模型嗎？
預設用 GPT-4o，但也支援 Anthropic Claude、Gemini、甚至本地跑的 Ollama。第一次先用 OpenAI 測通，後面換模型比想像中容易。

Q：output 目錄不存在會報錯嗎？
會。記得先建立 output/ 目錄，或者在 main.py 加上自動建目錄的邏輯。

下一步

你已經跑完第一個流程了——研究員找資料，reporter 整理成報告，一氣呵成。

接下來要搞清楚最關鍵的設計邏輯：角色和任務怎麼拆，才不會一跑就亂。
👉 Agent 與 Task 入門