2026 年初學者指南：用 CrewAI 打造你的第一個多代理人 AI 系統

CrewAI 是用來建構多代理人 AI 系統的開源 Python 框架，也是開發者入門代理人時最常用的選擇之一。如果你聽了很多「AI 代理人」的說法卻不知從何下手，CrewAI 就是答案——它把協調多個 AI 代理人的複雜性封裝起來，讓你專注在代理人實際要做的事情上。

什麼是多代理人系統？

有別於讓單一 LLM 處理所有事情，多代理人系統將專業角色分配給不同的代理人。一個代理人負責研究，另一個負責寫作，第三個負責審查。它們像一個小型團隊一樣互相傳遞工作成果，最終輸出通常比單一代理人獨自完成的品質更好。

CrewAI 提供一個 Python 框架，讓你定義代理人、給它們工具（搜尋、爬蟲、程式碼執行），並設定它們之間的工作流程。大約 30 行程式碼，你就能讓一個研究代理人和一個寫作代理人協作完成一篇部落格文章。

步驟一：安裝 CrewAI

pip install crewai

你還需要一個 LLM 提供商。CrewAI 支援 OpenAI、Anthropic、Google，以及透過 Ollama 執行的本地模型：

export OPENAI_API_KEY="your-key-here"

步驟二：定義代理人

每個代理人都有角色、目標和背景故事。背景故事不只是裝飾——它會影響代理人處理任務的方式。

from crewai import Agent

researcher = Agent(
    role="研究分析師",
    goal="找出特定主題最相關且最新的資訊",
    backstory="你是一位會交叉比對多個來源的細心研究員。",
    verbose=True
)

writer = Agent(
    role="內容寫手",
    goal="將研究轉化為清晰、引人入勝的文字",
    backstory="你是一位能讓複雜主題變得易於理解的資深科技寫手。",
    verbose=True
)

步驟三：定義任務

任務指定每個代理人該做什麼，以及預期輸出格式。

from crewai import Task

research_task = Task(
    description="研究 2026 年多代理人 AI 系統的最新發展",
    agent=researcher,
    expected_output="包含 5 個關鍵發展及來源的重點摘要"
)

writing_task = Task(
    description="根據研究撰寫一篇 500 字的部落格文章",
    agent=writer,
    expected_output="包含引言、主文和結論的結構完整文章"
)

步驟四：組裝團隊

from crewai import Crew

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    verbose=True
)

result = crew.kickoff()
print(result)

就這樣。代理人會依序執行任務——研究員收集資訊，寫手進行轉化，你拿到最終輸出。

下一步

熟悉雙代理人模式後，試著加入一個審查代理人，在輸出送到你手上之前先批評寫手的成果。或者透過 tools 參數給代理人工具，例如網頁搜尋、檔案讀取或 API 呼叫。

循序與階層兩種流程

上面的範例使用 CrewAI 預設的**循序（sequential）流程：任務依清單順序執行，前一個任務的輸出會成為下一個任務的上下文。CrewAI 也提供階層（hierarchical）**流程，由一個管理者代理人負責規劃、分派與驗收。根據 Processes 文件，階層模式需要指定管理者語言模型（manager_llm）或自訂管理者代理人：

from crewai import Crew, Process

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.hierarchical,
    manager_llm="gpt-4o",
)

循序流程較容易預測與除錯；階層流程適合步驟順序事先無法確定的開放式工作，但會多出不少 LLM 呼叫。

值得了解的代理人設定

Agents 文件列出了幾個實務上很重要的預設值：

• max_iter：代理人必須給出最佳答案前的最大迭代次數（預設 20），調低可避免失控迴圈與成本暴增。
• allow_delegation：是否允許把工作交給其他代理人（預設 False）。
• max_retry_limit：發生錯誤後的重試次數（預設 2）。
• respect_context_window：自動摘要訊息以維持在模型上下文長度內（預設 True）。
• allow_code_execution 與 code_execution_mode：程式碼執行預設關閉，預設模式「safe」會在 Docker 中執行。
• llm：每個代理人可以使用不同模型，簡單角色用便宜模型、需要推理的角色用較強模型。

Crew 與 Flow 的差別

Crew 適合讓代理人在一定自主性下協作。若流程需要精確控制，CrewAI 提供 Flows：以事件驅動的管線串接 Python 程式碼、單次 LLM 呼叫與整個 Crew，並支援共享狀態、條件分支與迴圈（Flows 文件）。常見做法是用 Flow 以確定性的方式處理輸入與驗證，只有開放式的部分才交給 Crew。

開始一個正式專案

超過單一腳本規模時，安裝指南建議使用 CrewAI CLI。它以 uv 管理相依套件，並產生專案骨架，把代理人與任務寫在設定檔中、與 Python 程式碼分開。提示詞放在設定檔裡，不動到程式邏輯也能審閱和修改。

與其他框架比較

• LangGraph：以節點與邊組成明確的圖來描述代理人流程，控制更細，但前期設計工作較多。
• Microsoft AutoGen：著重代理人之間的對話。
• CrewAI：以角色化的代理人與任務為核心，許多初學者覺得最直覺。

選哪一個取決於你需要多少控制、多少便利；很多團隊先用其中一個做原型，合用就繼續用。

正式上線檢查清單

• 設定迭代上限：用 max_iter 避免代理人無限迴圈。
• 追蹤成本：多代理人執行會產生大量 LLM 呼叫，記錄每次執行的 token 用量。
• 限制工具：每個代理人只給它角色需要的工具。
• 保留人工把關：任何面向客戶或不可逆的操作都需要人審核。
• 用固定輸入測試：更換提示詞或模型後，才能比較前後結果。

框架讓第一個 Crew 很容易做出來，但要做出可靠的系統，還需要多幾輪迭代。

參考資料

• CrewAI 文件：Agents
• CrewAI 文件：Processes
• CrewAI 文件：Flows
• CrewAI 文件：Installation
• CrewAI GitHub