CrewAI：用 Crews 與 Flows 把多代理實驗推進可控的生產工作流

多代理系統最容易犯的錯，不是模型不夠強，而是把「多個 Agent 一起聊天」誤當成完整架構。當任務開始需要重試、分支、人工審核、狀態保存與可觀測性時，單純的角色提示很快就會變成難以測試的隱性流程。

CrewAI 的價值在於把這個問題拆成兩層：Crews 負責角色化 Agent 之間的自主協作，Flows 負責事件驅動、狀態化且可預期的工作流控制。兩者可以分開使用，也可以把 Crew 當成 Flow 中的一個節點。這不是「多加幾個 Agent」而已，而是把自主性與工程控制放在同一個 Python 框架裡。

先看清楚 Crew 與 Flow 的分工

Crew 是高階抽象。你可以為 Agent 定義 role、goal、backstory、tools 與 LLM，再用 Task 描述要完成的工作，最後交給 Crew 管理協作。這種模式適合研究、分析、內容處理等需要角色分工與動態決策的任務。

Flow 是低階且明確的控制面。它以事件驅動方法組成流程，能保存狀態、控制執行路徑，並把普通 Python 邏輯、單次 LLM 呼叫與 Crew 組合起來。換句話說，Flow 不要求每一步都交給 Agent 決策；你可以把 deterministic code 留在程式裡，只在真正需要推理的位置呼叫模型。

實務上的判斷很簡單：如果你要的是「一組專家自行協作」，先想 Crew；如果你要的是「可預期的輸入、分支、重試與輸出」，先想 Flow。需要兩者時，讓 Flow 負責骨架，讓 Crew 處理其中一段需要自主協作的工作。

從最小 Flow 開始

以下範例展示一個可擴充的研究流程：先接收主題，再產生研究結果，最後把結果整理成報告。重點不是 prompt 內容，而是狀態與步驟邊界清楚可見。

from crewai.flow.flow import Flow, listen, start
from pydantic import BaseModel


class ResearchState(BaseModel):
    topic: str = ""
    notes: str = ""
    report: str = ""


class ResearchFlow(Flow[ResearchState]):
    @start()
    def collect_topic(self):
        self.state.topic = "比較兩種 RAG 評估方法"
        return self.state.topic

    @listen(collect_topic)
    def research(self, topic: str):
        # 真正的專案中，這裡可以呼叫 Crew、工具或單次 LLM。
        self.state.notes = f"針對 {topic} 收集可驗證的資料與限制。"
        return self.state.notes

    @listen(research)
    def write_report(self, notes: str):
        self.state.report = f"研究摘要：{notes}"
        return self.state.report


if __name__ == "__main__":
    result = ResearchFlow().kickoff()
    print(result)

@start() 定義入口，@listen() 把方法接到事件上，而 self.state 是跨步驟共享的資料。這種寫法比把所有工作塞進一個巨大 prompt 更容易測試：每一個節點都有輸入、輸出與責任範圍。

把 Crew 放進 Flow

當研究步驟需要多個角色協作，可以把 research() 改成建立或呼叫 Crew。典型分工是讓一個 Agent 找資料、另一個 Agent 交叉檢查，最後由編輯 Agent 產出結構化結果；但外層仍由 Flow 決定何時開始、何時進入人工審核，以及失敗後要走哪一條路。

from crewai import Agent, Crew, Process, Task

researcher = Agent(
    role="研究員",
    goal="找出可引用且可重現的技術證據",
    backstory="熟悉 AI 系統與開源專案查證。",
    verbose=True,
)

reviewer = Agent(
    role="審稿人",
    goal="指出證據不足、過度推論與版本風險",
    backstory="重視可驗證性與工程細節。",
    verbose=True,
)

research_task = Task(
    description="研究指定主題，列出來源、方法與限制。",
    expected_output="包含來源與限制的研究筆記",
    agent=researcher,
)

review_task = Task(
    description="檢查研究筆記，標記無法驗證的主張。",
    expected_output="可供文章使用的查證清單",
    agent=reviewer,
)

crew = Crew(
    agents=[researcher, reviewer],
    tasks=[research_task, review_task],
    process=Process.sequential,
)

這段配置揭示一個重要設計選擇：Crew 的自主性不是免費的。角色越多，token、延遲與失敗面越大；因此應該先用單次 LLM 或一般 Python 解決確定性工作，再把真正需要協作的步驟交給 Crew。Flow 則可以在外層加上輸入驗證、重試、超時與人工批准。

生產化時真正要補的四件事

1. 讓狀態成為契約

不要把關鍵資訊只放在對話歷史。把 topic、來源、候選答案、審核結果與錯誤原因放進明確的 state model，才能在重跑、觀測與除錯時知道流程目前在哪裡。

2. 把自主性限制在邊界內

Agent 可以負責選擇工具或提出方案，但資料寫入、權限變更、付款與對外發布等副作用應由 Flow 節點控制。必要時在副作用前加入人工審核，而不是只在 system prompt 裡提醒 Agent 小心。

3. 為每個任務定義可驗證輸出

CrewAI 的 Task 支援 expected_output，也可以搭配結構化輸出與 guardrails。輸出格式越明確，後續節點越不需要靠字串猜測，也更容易用測試資料檢查回歸。

4. 觀測成本與失敗路徑

多代理流程要記錄每個 Agent 的輸入輸出、工具呼叫、耗時與 token 成本；同時測試「工具失敗」「資料不足」「模型回傳格式錯誤」等路徑。CrewAI 的開源框架負責組裝 primitives，部署、權限、秘密管理與監控仍要由應用程式補齊；若需要集中式治理，官方另有 AMP Suite，但那不是開源核心本身。

何時不該使用 CrewAI

如果流程只有一個模型呼叫、幾個固定的 Python 函式，直接寫一般程式通常更簡單。如果任務要求嚴格的狀態機、低延遲與完全可重現，也應先以 Flow 或傳統 workflow engine 為主，而不是把每一步都交給自主 Agent。多代理架構適合的是「需要角色分工或動態決策，但仍希望保留工程控制」的中間地帶。

結語：先畫流程，再增加 Agent

CrewAI 最值得借鑑的不是「讓更多 Agent 互相對話」，而是把自主協作與 deterministic workflow 放在不同抽象層。先用 Flow 畫出輸入、狀態、分支與副作用，再把確實需要推理的區段封裝成 Crew，通常比從一個全能 Agent 開始更容易走到可維護的系統。

截至 2026 年 8 月 19 日查證，crewAIInc/crewAI 是活躍維護的 MIT 授權 Python 框架，GitHub 顯示超過 57,000 顆 stars。實作時仍應以官方文件與目前套件版本為準，並為模型輸出、工具權限與外部副作用建立自己的驗證層。

查證來源

GitHub repository：<https://github.com/crewAIInc/crewAI>
官方文件：<https://docs.crewai.com>
CrewAI README（Crew、Flow、安裝與範例）：<https://github.com/crewAIInc/crewAI/blob/main/README.md>
MIT License：<https://github.com/crewAIInc/crewAI/blob/main/LICENSE>