CrewAI 多Agent協作教學：打造自動化AI團隊

什麼是 CrewAI？為什麼需要多 Agent 協作

如果你已經在用 LLM 做各種自動化任務，你一定會發現一個問題：單一 Agent 能做的事情終究有限。當任務變得複雜，比如說要同時做市場調研、撰寫報告、審核品質，一個 Agent 根本忙不過來，而且容易搞混不同角色的職責。

這就是 CrewAI 要解決的問題。CrewAI 是一個開源的多 Agent 協作框架，讓你可以定義多個具有不同角色、目標和背景知識的 AI Agent，然後把它們組成一個「團隊」（Crew），協同完成複雜任務。說白了，就是把人類團隊協作的模式搬到 AI 世界裡。

跟其他框架相比，CrewAI 的最大優勢在於簡潔直覺的 API 設計。你不需要寫一堆圖結構或狀態機，只要定義好角色和任務，框架會自動處理 Agent 之間的溝通和協調。如果你想了解不同框架的差異，可以參考這篇 AI Agent 框架比較，裡面有更詳細的分析。

CrewAI 核心概念：Agent、Task、Crew

在動手寫程式之前，先搞懂三個核心概念：

Agent（代理人）：具有特定角色、目標和背景故事的 AI 實體。每個 Agent 都有自己的「人設」，這會影響它處理任務的方式。
Task（任務）：要完成的具體工作項目，包含描述、預期輸出格式，以及指定由哪個 Agent 負責執行。
Crew（團隊）：將多個 Agent 和 Task 組合在一起的執行單元，負責管理任務的執行順序和 Agent 之間的互動。

這三者的關係很好理解：Crew 就像一個專案經理，把 Task 分配給對應的 Agent，然後監督整個執行流程。CrewAI 支援兩種執行模式：sequential（依序執行）和 hierarchical（層級式，由 manager agent 統籌分配）。

角色設計：打造專業化的 AI Agent

角色設計是整個工作流的靈魂。我個人的經驗是，角色定義得越具體，產出品質越好。一個好的 Agent 定義應該包含：

from crewai import Agent

researcher = Agent(
    role="資深市場研究分析師",
    goal="深入分析目標市場趨勢，產出有數據支撐的洞察報告",
    backstory="你是一位有 10 年經驗的市場分析師，擅長從公開資料中挖掘有價值的趨勢。你重視數據的準確性，並且會交叉驗證多個來源。",
    verbose=True,
    allow_delegation=False
)

writer = Agent(
    role="內容策略專家",
    goal="將研究報告轉化為引人入勝的部落格文章",
    backstory="你是一位專注於科技領域的內容創作者，擅長將複雜概念用淺顯易懂的方式呈現。你的文章風格務實、不浮誇。",
    verbose=True,
    allow_delegation=False
)

這裡有幾個重點：backstory 不是裝飾品，它會實際影響 Agent 的行為模式。allow_delegation 設為 True 時，Agent 可以把子任務委派給其他 Agent，這在層級式架構中非常有用。

任務委派與工作流編排

定義好 Agent 之後，接下來就是設計 Task 和工作流程。每個 Task 需要明確指定輸入、輸出和負責的 Agent：

from crewai import Task

research_task = Task(
    description="針對 '{topic}' 進行全面的市場調研，包含：市場規模、主要玩家、成長趨勢、技術發展方向。",
    expected_output="一份結構化的市場研究報告，包含至少 5 個數據點和 3 個關鍵趨勢。",
    agent=researcher
)

writing_task = Task(
    description="根據市場研究報告，撰寫一篇 1500 字的部落格文章，目標讀者是技術決策者。",
    expected_output="一篇完整的部落格文章，包含標題、前言、正文和結論。",
    agent=writer,
    context=[research_task]  # 這個任務會拿到 research_task 的輸出作為輸入
)

context 參數是關鍵，它建立了任務之間的依賴關係。writing_task 會等 research_task 完成後，自動拿到它的輸出結果作為參考資料。這讓你可以建立清晰的資料流向。

如果你對更複雜的 Agent 工作流有興趣，比如用圖結構來設計，可以看看 LangGraph Agent 入門這篇教學。

YAML 設定檔實戰

CrewAI 從 v0.30+ 開始推薦用 YAML 設定檔來管理 Agent 和 Task 的定義，這樣做的好處是把「配置」和「程式邏輯」分開，維護起來更方便。

建立 config/agents.yaml：

researcher:
  role: "資深市場研究分析師"
  goal: "深入分析目標市場趨勢，產出有數據支撐的洞察報告"
  backstory: |
    你是一位有 10 年經驗的市場分析師，
    擅長從公開資料中挖掘有價值的趨勢。
  tools:
    - search_tool
    - scrape_tool

writer:
  role: "內容策略專家"
  goal: "將研究報告轉化為引人入勝的部落格文章"
  backstory: |
    你是一位專注於科技領域的內容創作者。
  tools:
    - file_writer_tool

對應的 config/tasks.yaml：

research_task:
  description: "針對 {topic} 進行全面的市場調研"
  expected_output: "結構化的市場研究報告"
  agent: researcher

writing_task:
  description: "根據研究報告撰寫部落格文章"
  expected_output: "一篇完整的部落格文章"
  agent: writer
  context:
    - research_task

然後在程式碼中用 @CrewBase 裝飾器載入：

from crewai import CrewBase, Crew, agent, task, crew

@CrewBase
class ContentCrew:
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,
            verbose=True
        )

YAML 設定檔讓整個專案更好管理，特別是當你有十幾個 Agent 和幾十個 Task 的時候，直接改 YAML 比改 Python 程式碼安全多了。

工具整合與 MCP Server 串接

Agent 如果不能使用外部工具，能做的事就很有限。CrewAI 支援多種工具整合方式：

內建工具：搜尋、網頁抓取、檔案讀寫等
自訂工具：用 @tool 裝飾器包裝任何 Python 函式
MCP Server 整合：透過 Model Context Protocol 連接外部服務

from crewai.tools import MCPServerAdapter

# 連接 MCP Server 提供的工具
async with MCPServerAdapter(
    server_params={"url": "http://localhost:3001/mcp"}
) as mcp_tools:
    agent = Agent(
        role="數據分析師",
        goal="從資料庫提取並分析數據",
        tools=mcp_tools.tools
    )

MCP 整合特別強大，因為它讓 Agent 可以存取資料庫、API、甚至本地檔案系統。不過要注意工具數量不要太多，根據我的測試，單一 Agent 配 3-5 個工具是最佳平衡點，太多反而會讓 LLM 選錯工具。關於更進階的工具調度策略，推薦閱讀 Agent 多工具調度這篇文章。

完整專案實作：自動化內容產出團隊

讓我們用一個實際案例把所有概念串起來。假設我們要建立一個自動化內容產出流程，需要三個角色：研究員、寫手、編輯。

from crewai import Crew, Process

# 定義 Crew
content_crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, review_task],
    process=Process.sequential,
    memory=True,          # 啟用記憶功能
    max_rpm=10,           # API 請求速率限制
    share_crew=False
)

# 執行
result = content_crew.kickoff(
    inputs={"topic": "2026 年 AI Agent 發展趨勢"}
)
print(result.raw)

這裡有幾個進階設定值得注意：

memory=True：啟用短期和長期記憶，Agent 可以記住之前的互動內容
max_rpm：控制 API 呼叫頻率，避免被限流
Process.hierarchical：如果任務之間需要更靈活的分配，可以改用層級模式，CrewAI 會自動建立一個 Manager Agent 來統籌

在實際運作中，sequential 模式適合線性流程（A 做完換 B），hierarchical 適合需要動態決策的場景（Manager 根據中間結果決定下一步）。

效能優化與常見問題排解

跑了幾個專案後，我整理出幾個常見的坑：

Token 消耗爆炸：多 Agent 對話會快速消耗 token。解法是精簡 backstory、限制 context 傳遞的內容量，以及善用 max_iter 參數限制 Agent 的思考迭代次數。
Agent 互相甩鍋：當 allow_delegation=True 時，Agent 可能會把任務推來推去。建議在 Task 描述中明確寫「你必須自己完成這個任務」。
輸出格式不穩定：在 expected_output 中盡量寫明確的格式要求，甚至可以給範例。搭配 output_json 或 output_pydantic 可以強制結構化輸出。
除錯困難：設定 verbose=True 並搭配 output_log_file 參數，把完整的執行日誌存下來方便後續分析。