crewAIInc/crewAI 角色分工多代理框架實戰教學:Flows 與 Crews 雙模式打造自動化管線

crewAIInc/crewAI 透過直覺的角色、任務與流程編排,讓多個 AI 代理分工完成研究與報告任務,一篇教你區分 Crews 與 Flows 模式並完成實戰範例。

Share
CrewAI官方 GitHub 專案封面圖:CrewAI 教學
CrewAI官方開源專案視覺圖。 圖片來源:官方原文。

許多開發者在剛開始打造自動化 AI 系統時,常會陷入一個迷思:試圖把資料搜尋、事實查核、文案撰寫與格式排版全部塞進同一個龐大的系統提示詞裡。然而這樣做的結果往往是模型顧此失彼,輸出品質極度不穩定。

相反地,當你真的把工作拆成多個代理來協作時,又很容易遇到另一個工程難題:什麼時候該讓代理們自由討論、什麼時候該用確定性的程式邏輯嚴格控制執行順序?因為如果全靠代理自由發揮,整個管線常常會在某個分支迷路,甚至陷入無窮迴圈。

CrewAI 正是為了解決這個兩難而設計的開源多代理框架。它提供了一套非常直覺的「組建團隊」隱喻,並把框架明確拆成兩個互補的核心模式:負責自主協作的 Crews,以及負責精準事件驅動控制的 Flows。

這套雙模式架構讓它成為目前企業自動化與研究管線最熱門的選擇之一。官方社群已有超過十萬名開發者完成認證課程,新版 CLI 更導入了結構化的 JSONC 專案架構,大幅降低了維護成本。

這篇 CrewAI 教學會帶你釐清 Crews 與 Flows 的使用時機、完成最新版本的 uv 環境安裝,並實際跑通一個雙人研究與報告生成的完整管線。

Crews 與 Flows 差在哪?看懂雙模式多代理核心架構

在使用這套多代理框架之前,最重要的一步是搞清楚什麼任務該交給 Crews,什麼邏輯應該寫在 Flows 裡。因為這兩種模式並不是二選一,而是專門用來解決不同層級的控制需求。

Crews 的核心是「角色扮演與自主協作」。你可以想像自己正在招募一個專案小組,為每個代理設定明確的 role 職稱、goal 目標與 backstory 背景故事,並搭配各自專屬的外部工具。

接著定義好任務清單與預期產出,選擇循序執行或階層式指派,代理之間就會自主溝通、交接成果甚至互相委派工作。因此,Crews 最適合需要開放式探索、研究整理與內容生成的階段。

Flows 則是「事件驅動與精準流程控制」。在真實的生產環境裡,我們不可能讓整個商業流程完全交給語言模型臨場決定下一步,因為企業流程往往需要嚴格的合規檢查與錯誤處理。

所以 Flows 允許工程師用標準 Python 事件裝飾器編排執行路徑,安全地管理任務之間的狀態資料,並加入明確的條件分支邏輯。你可以把單次輕量 LLM 呼叫與一個完整的 Crew 團隊都當成 Flows 裡的其中一個步驟節點,兼顧確定性與智慧決策。

簡單來說,用 Flows 搭建確定性的骨架與狀態機,只在真正需要深度推理與團隊分工的節點上掛載 Crews,是目前打造穩定多代理系統的黃金法則。

CrewAI官方 GitHub 專案封面圖:CrewAI 教學
CrewAI官方開源專案視覺圖。 圖片來源:官方原文。
CrewAI官方介紹與實機示範影片,非本站實測。 來源:官方 YouTube。

最新版安裝步驟與環境檢查

根據官方最新安裝文件,這套框架要求使用 Python 3.10 以上且低於 3.14 的版本,並全面採用高速套件管理工具 uv 來建立獨立的 CLI 執行環境。

首先在終端機確認 Python 版本,並安裝 uv:

python3 --version
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows 使用者可以透過 PowerShell 執行官方安裝指令取得 uv。安裝完成並確認環境變數生效後,接著就能安裝全域的 crewai 命令列工具:

uv tool install crewai

如果終端機出現路徑警告,執行 uv tool update-shell 即可修正。如果是 Windows 環境在安裝向量索引依賴套件時遇到缺少 C++ 編譯器的錯誤,則需要補裝 Visual Studio Build Tools 的桌面開發套件。

安裝完畢後,輸入以下指令確認安裝狀態與版本:

uv tool list

畫面上應該會出現 crewai 及其版本號,代表全域 CLI 已經準備就緒。如果日後需要升級全域指令工具,只要加上 --upgrade 參數重新執行即可。

實戰教學:用新版 JSONC 結構打造雙人研究報告團隊

在最新版的命令列工具中,執行 crewai create crew 預設會建立以 JSONC 設定檔為核心的專案結構,讓角色與任務定義更加清晰。當然,如果你習慣舊寫法,也可以加上 --classic 參數切回傳統的 YAML 與 Python 裝飾器範本。

我們來建立一個名為 latest-ai-development 的研究專案:

crewai create crew latest-ai-development
cd latest-ai-development

這個指令會自動產生包含 agents/、crew.jsonc、tools/、knowledge/、skills/ 與 .env 的標準目錄。

接下來我們設定兩位分工明確的代理。第一位是資深資料研究員,負責使用搜尋工具蒐集最新趨勢,我們編輯 agents/researcher.jsonc:

{
  "role": "{topic} Senior Data Researcher",
  "goal": "Uncover cutting-edge developments in {topic}",
  "backstory": "You're a seasoned researcher who finds relevant information and presents it clearly.",
  "llm": "openai/gpt-4o",
  "tools": ["SerperDevTool"],
  "settings": {
    "verbose": true
  }
}

第二位是報告分析師,負責把研究員找到的散落資料整理成結構完整的 Markdown 報告,編輯 agents/reporting_analyst.jsonc:

{
  "role": "{topic} Reporting Analyst",
  "goal": "Create detailed reports based on {topic} data analysis and research findings",
  "backstory": "You're a meticulous analyst who turns complex data into clear, concise reports.",
  "llm": "openai/gpt-4o",
  "settings": {
    "verbose": true
  }
}

接著打開根目錄的 crew.jsonc,把這兩位代理串成一條循序執行的任務管線,並設定預設輸入主題 {topic}:

{
  "name": "Latest AI Development",
  "agents": ["researcher", "reporting_analyst"],
  "tasks": [
    {
      "name": "research_task",
      "description": "Conduct thorough research about {topic}. Find recent, relevant information.",
      "expected_output": "A list with 10 bullet points of the most relevant information about {topic}.",
      "agent": "researcher"
    },
    {
      "name": "reporting_task",
      "description": "Review the research and expand each topic into a full section for a report.",
      "expected_output": "A markdown report with the main topics, each with a full section of information.",
      "agent": "reporting_analyst",
      "context": ["research_task"],
      "output_file": "output/report.md",
      "markdown": true
    }
  ],
  "process": "sequential",
  "verbose": true,
  "inputs": {
    "topic": "AI Agents"
  }
}

最後一步是在專案根目錄的 .env 檔案填入你的模型 API 金鑰與搜尋工具金鑰,然後執行安裝依賴與啟動指令:

crewai install
crewai run

系統就會依序喚醒研究員搜尋資料,再把輸出結果透過 context 欄位精準交棒給分析師,最後自動在 output/report.md 產出完整的報告檔案。如果專案有多個動態參數,執行時指令也會貼心提示你補齊預設值之外的輸入欄位。

延伸閱讀:Genpact Onyx 是什麼?整合 30 年流程智慧的企業級 AI 代理營運平台解析

與主流多代理框架定位比較

多代理生態系選擇很多,開發者常在 CrewAI、PydanticAI 與 smolagents 之間猶豫。這三個開源專案其實各自鎖定了完全不同的抽象層級:

比較維度 CrewAI PydanticAI smolagents
核心設計隱喻 團隊角色分工加上事件驅動 Flows 強型別軟體工程加上依賴注入 極簡 Python CodeAgent 直覺執行
設定與開發方式 支援 JSONC、YAML 宣告式設定與 Python API 純 Python 強型別開發,也支援規格檔 極簡 Python 腳本,百行核心容易改寫
流程控制與協作 內建循序、階層式指派與 Flows 狀態機 需搭配 Pydantic Graph 或外部持久化引擎 適合單代理或簡單管理員階層調度
企業監控與商業套件 提供 AMP 商業控制平面可選配 搭配 OpenTelemetry 與 Pydantic Logfire 輕量無綁定,需自行對接遙測工具
上手速度 極高,CLI 範本幾分鐘就能跑通多代理流程 中等,需熟悉現代 Python 型別標註 極高,幾行程式碼即可啟動

導入實務限制與成本風險

在把這套多代理系統放進正式商業流程前,有三項實務風險必須提前規劃,以免上線後帳單或穩定度失控。

第一項風險是「隱性 Token 消耗倍增」。當一個團隊裡面有三到五個代理,如果開啟了代理之間互相委派或頻繁反思的設定,單一任務背後可能會觸發十幾次完整的長上下文模型呼叫。

因此,在開發測試階段務必開啟 verbose 觀察實際對話輪數,並為關鍵角色分配不同等級的模型,例如搜尋整理用平價模型,最終審核才用旗艦模型。

第二項風險是「非預期輸出格式」。雖然角色協作讓代理用自然語言溝通非常直覺,但如果要把代理的輸出直接寫進關聯式資料庫或呼叫下游系統 API,千萬不要只依賴提示詞要求格式,務必搭配結構化輸出驗證或透過 Flows 在交界處做嚴格的資料檢查。

第三項風險是「開源核心與商業套件的邊界」。框架本身採用寬鬆的 MIT 開源授權,可以免費商用與修改;不過官網主打的企業級視覺化監控平台與集中治理功能屬於商業版 AMP 套件。中小團隊如果只需要基礎追蹤,可以先從開源的 OpenTelemetry 工具著手評估。

延伸閱讀:IBM watsonx Orchestrate 擴展 AI 代理管理:跨平台盤點、權限與測試怎麼做?

實戰進階技巧:知識庫掛載、記憶機制與 Flows 狀態管理

當基礎的雙人研究團隊跑通之後,如果想把這套系統推進到真正的團隊生產環境,還有三個核心功能能讓輸出品質產生質的飛躍。

首先是「專案知識庫 knowledge/ 目錄的運用」。在 CLI 建立的專案資料夾裡,預設就包含了一個知識庫目錄,開發者可以把公司的產品規格書、技術白皮書或 FAQ 文件放進去。

這樣一來,代理在執行任務時就能直接檢索內部私有資料,不需要每次都靠網路搜尋或把整份文件硬塞進系統提示詞裡,回答的準確度與專業度會明顯提升。

其次是「自訂工具與技能模組化」。除了內建的網頁搜尋與檔案讀寫工具,團隊可以把內部資料庫查詢、Slack 通知發送或 Jira 工單建立封裝成獨立的 Python 工具放在 tools/ 目錄下,並在設定檔裡用 "custom:<工具名稱>" 的格式指定給特定角色使用。

同時,新版架構也提供了 skills/ 目錄用來存放標準化的任務操作指南,讓不同專案之間可以輕鬆複用同一套專業技能定義。

第三是「用 Flows 管理企業級狀態與分支」。在實際商業流程裡,研究完資料後往往需要判斷分數是否達標,或是根據不同客戶類型走不同審核路徑。

透過 Flows 提供的 @start 與 @listen 事件裝飾器,工程師可以用乾淨的 Python 程式碼定義明確的條件跳轉與共用狀態類別,確保在進入下一個 Crew 團隊協作之前,所有前置資料都已經經過驗證且格式完全正確。

最後建議在正式上線前,把各個角色的提示詞變數抽離到 crew.jsonc 的 inputs 區塊統一管理,這樣即使非工程背景的業務團隊想微調輸入參數,也不必直接修改核心程式碼。

此外,針對需要長期累積經驗的團隊任務,記得規劃好記憶與快取策略,避免每次執行都重複搜尋相同的公開資料。團隊在評估導入效益時,可以先挑選一個固定週期產出的內部報告或資料彙整流程作為試點,例如每週競品動態摘要或客服工單分類,觀察兩週的準確率與 Token 成本曲線。

當你確認角色分工的邊界足夠清晰、每個任務的預期產出格式也都有明確的檢查機制後,再逐步串接企業內部資料庫或自動化通知系統,這樣就能把多代理失控的風險降到最低。如果團隊同時需要多個環境的部署與權限管理,也可以評估透過事件掛鉤把執行日誌同步送到既有的企業監控平台,確保每一次代理決策都具備完整的可追溯性與稽核紀錄,並且在模型版本升級或提示詞調整時能快速比對前後產出差異與整體延遲表現,讓多代理自動化系統真正穩定落地並創造長期商業價值。

常見問題

這篇 CrewAI 教學介紹的框架只能搭配 OpenAI 模型嗎?

不是。它支援透過 LiteLLM 或對應設定連接數十種模型供應商,包含 Anthropic Claude、Google Gemini、Azure OpenAI,以及本機部署的 Ollama 端點。只要在代理設定檔更改 llm 欄位並配置對應的環境變數金鑰即可切換。

我應該先學 Crews 還是先學 Flows?

建議先從 Crews 入手,花半小時透過 CLI 範本體驗「角色、任務、工具」三者的分工邏輯。等到需要處理條件分支、資料庫狀態保存,或是要把多個獨立團隊串成大型自動化管線時,再把 Flows 加進來當作外層骨架。

新版的 JSONC 專案架構跟舊版 YAML 架構差在哪?

新版 crewai create crew 預設建立 agents/*.jsonc 與 crew.jsonc,讓設定檔自帶註解支援且結構更統一,執行 crewai run 時直接讀取設定。如果舊專案已經寫好大量 crew.py 與 YAML 檔案,只要加上 --classic 參數就能繼續沿用舊格式。

如果代理在執行過程中無限循環或花費過高怎麼辦?

實務上一定要在代理設定裡限制最大迭代次數 max_iter 與每分鐘請求頻率上限 max_rpm。同時在測試階段先使用較低單價的模型驗證工具呼叫順序是否正確,確認管線邏輯收斂後再切換到目標主力模型。

結語

CrewAI 用非常容易理解的「組織分工」概念降低了多代理系統的設計門檻,同時藉由 Flows 補齊了企業在確定性流程與狀態控制上的關鍵拼圖。

適合誰:需要快速建構研究分析、內容生產、競品追蹤等「多角色協作管線」,並且希望透過清晰設定檔與 CLI 工具標準化開發流程的團隊與工程師。

不適合誰:只需要單一代理執行極簡 API 呼叫的輕量應用,或是追求極致細微、每一步都要嚴格編譯期型別檢查的底層後端系統開發者。

想掌握更多開源 AI 多代理架構對比、實戰範本與最新工具評測,歡迎立即免費訂閱 AI 郵報,每週精選最落地的工程師實戰內容。

資料來源