CrewAI 入門教學:Agent 角色、Task 任務、執行流程(Process)與第一個團隊示例

CrewAI 是主打「擬人化角色分工」的 Python 多智能體開源框架。本文按官方文檔講清安裝要求、Agent(角色/目標/背景)、Task(任務描述與預期輸出)和 Process(順序接力與經理層級模式)的配合邏輯,並給出最小可運行代碼。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

  1. CrewAI 把多智能體抽象成極其直觀的三件套:定崗位(Agent)、下工單(Task)、排班組隊(Crew + Process),而且現在的底層引擎已獨立重寫,不再強依賴全套舊版 LangChain。
  2. 寫好 Task 比堆砌花哨的 Agent 人設更重要:每個 Task 都必須寫清楚可驗收的 expected_output(預期輸出格式與字數結構),否則前一個人交出的半成品會直接帶偏整條流水線。
  3. 新手起步一律先用預設的順序流程(Process.sequential),並且把非主管角色的 allow_delegation 設為 False,防止幾個代理在後台互相轉交任務把 Token 燒光。
  4. 只有當子任務順序無法預先寫死、確實需要中心主管動態派活覆核時,才切到層級流程(Process.hierarchical),且必須顯式傳入強推理能力的 manager_llm。

CrewAI 三大核心原語與兩種流程對比

圖:本站根據 CrewAI 官方文檔 Core Concepts 整理的示意圖

本文根據 CrewAI 官方文檔與 crewAIInc/crewAI 開源倉庫說明整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 CrewAI 官方網站。

適用於誰

  • 搜「crewai 入門」「crewai 教學」「crewai 角色 任務 流程」的人;
  • 覺得手寫狀態圖邊和節點偏底層(如 /guides/langgraph-quickstart-install-first-graph),更喜歡按「市場調研員 → 技術撰稿人 → 審校編輯」這種人類團隊崗位來組織多智能體的開發者;
  • 剛裝好 CrewAI,分不清順序模式(sequential)和層級經理模式(hierarchical)什麼時候該開的人。

一、環境安裝與腳手架說明

CrewAI 要求使用 Python 3.10 及以上兼容版本。官方推薦使用 uv 或虛擬環境安裝核心包(如需內置搜尋文件等現成工具,可一併安裝 crewai-tools):

bash
mkdir crew-demo && cd crew-demo
python -m venv .venv
source .venv/bin/activate   # Windows PowerShell: .venv\Scripts\Activate.ps1

pip install -U crewai

安裝完成後有兩種組織代碼的方式:

  • 工程化項目腳手架:運行 crewai create crew my_project(習慣傳統 agents.yaml 與 tasks.yaml 分離寫法的開發者可按新版 CLI 說明加 --classic 參數),把提示詞文案和 Python 邏輯拆開維護;
  • 單文件 Python 直觀寫法:直接在腳本里實例化 Agent、Task 和 Crew,最適合第一次上手看清數據是怎麼傳遞的。

從零搭建第一個 CrewAI 團隊四步法

圖:本站根據 CrewAI 官方 Quickstart 文檔 整理的示意圖

二、最小可運行示例:雙角色「調研提煉 + 結構化成文」

先在環境變量裏配好你的模型密鑰(例如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY)。新建 first_crew.py,用佔位變量 {topic} 實現一份可複用的雙節點協作腳本:

python
from crewai import Agent, Task, Crew, Process

# 1. 定義兩個專職角色(預設關閉自由轉交 allow_delegation=False 更穩)
analyst = Agent(
    role="技術情報分析員",
    goal="圍繞主題 {topic} 梳理核心技術機制、適用邊界與常見誤區",
    backstory="你擅長從工程落地角度拆解技術概念,只列客觀要點,不寫空洞口號。",
    llm="openai/gpt-4o-mini",
    allow_delegation=False,
    verbose=True,
)

writer = Agent(
    role="開發者文檔編輯",
    goal="把分析員輸出的要點整理成條理清晰的中文入門提綱",
    backstory="你專門為一線程式員寫簡明手冊,段落短、結論先行。",
    llm="openai/gpt-4o-mini",
    allow_delegation=False,
    verbose=True,
)

# 2. 定義兩張前後銜接的任務單,必填 expected_output
research_task = Task(
    description="針對 {topic} 列出 5 條關鍵事實與 3 個新手常見踩坑。",
    expected_output="包含 5 條機制要點和 3 條避坑提醒的 Markdown 無序列表。",
    agent=analyst,
)

write_task = Task(
    description="基於上一階段的分析要點,撰寫一份面向初學者的 {topic} 快速上手小結。",
    expected_output="不少於三節的中文 Markdown 小結,包含結論列表與實操建議。",
    agent=writer,
    context=[research_task],  # 顯式聲明依賴前序任務的輸出結果
)

# 3. 組建團隊,採用順序接力流程啟動
tech_crew = Crew(
    agents=[analyst, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    verbose=True,
)

if __name__ == "__main__":
    result = tech_crew.kickoff(inputs={"topic": "Git Worktree 多分支並行開發"})
    print(result.raw)

運行腳本後,tech_crew.kickoff(inputs={...}) 會把 "Git Worktree 多分支並行開發" 自動填入所有帶 {topic} 的角色目標和任務描述裏,先跑完 analyst,再把產出作為上下文餵給 writer。

三、兩種執行流程(Process)到底怎麼選

這正好對應我們在 /guides/multi-agent-orchestration-patterns 裏拆解過的兩類拓撲:

  1. 順序流程(Process.sequential):嚴格按照 Crew(tasks=[...]) 數組裏的先後順序一個接一個往下走。你可以用 Task(context=[task_a, task_b]) 精確指定當前步驟只讀取前面哪幾個任務的產出,而不是把所有歷史堆成一鍋粥。九成內容生成、報告整理、固定流水線任務用它最穩最省錢;
  2. 層級流程(Process.hierarchical):切換成該模式時,你必須額外指定一個經理模型(如 manager_llm="anthropic/claude-sonnet-4-5")或自定義 manager_agent。經理會根據總目標自己決定先叫誰幹活、審閱結果不合格時打回重做。但要注意經理每輪分派與覆核都會額外產生多輪大模型調用(成本放大規律見 /guides/multi-agent-token-cost-why-high-how-to-control)。

四、和 LangGraph 比該怎麼取捨

如果你已經看過 /guides/multi-agent-what-is-when-to-use,可以用一句話區分兩者的甜點區:當你的業務天然長成「幾個不同工種的人分工寫方案、做調研、出報告」時,CrewAI 的 YAML 崗位模板寫起來最快;當你的業務充滿精確的條件分支跳轉、循環重試計數與數據庫事務狀態機時,LangGraph 的顯式狀態圖(或 CrewAI 後續補充的 Flows 事件流機制)更可控。日常藉助官方 Claude 或 ChatGPT 網頁端先行打磨各角色的 backstory 與驗收標準時,個人訂閱說明也可參考 /chongzhi/claude-pro。

常見問題

Q:為什麼我沒開層級模式,兩個 Agent 還是在控制檯裏來回互相提問停不下來?

檢查你定義的 Agent 有沒有顯式寫 allow_delegation=False。一旦開啟允許委派,當某個角色覺得問題超出自己能力時,就會把子問題拋給團隊裏的其他角色協助,沒有設好 max_iter(單角色最大迭代次數,建議設 5 到 10)時很容易來回拉扯。

Q:想換用 Claude、Gemini 或本地 Ollama 模型怎麼填 llm 字段?

CrewAI 底層集成了統一模型路由格式,只需按 "提供商前綴/模型名" 填寫字符串即可,例如 "anthropic/claude-sonnet-4-5" 或 "ollama/qwen2.5:14b"(連接本地服務時配合傳入本地 base_url)。

相關教學

參考資料

  • CrewAI 官方文檔 — https://docs.crewai.com/
  • crewAIInc/crewAI 官方開源倉庫 — https://github.com/crewAIInc/crewAI

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  5. 05

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  6. 06

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  4. 04

    A2A 協議是什麼、怎麼用:Agent2Agent 智能體互聯規範、名片發現與 Python 接入流程

    A2A(Agent2Agent)是由 Google 發起並移交 Linux 基金會託管的開放智能體通信協議,用來讓不同團隊、不同框架開發的獨立智能體跨網絡互相派單協作。本文按官方規範講清 Agent Card、Task 狀態機與 Python SDK 接入步驟。

    Gemini其他 AI 工具0
  5. 05

    AutoGen 現在怎麼樣了?微軟官方演進路線與 Microsoft Agent Framework 入門

    搜 AutoGen 新教學常被 0.2、0.4、社區分支和 Semantic Kernel 繞暈。按微軟官方文檔,微軟已將 AutoGen 與 Semantic Kernel 兩支團隊合併推出統一的開源框架 Microsoft Agent Framework。本文講清現狀與 Python 快速上手。

    ChatGPT其他 AI 工具0
  6. 06

    CrewAI 多輪對話與記憶怎麼配:memory=True 三層記憶、人工介入與 Flows 狀態持久化

    剛用上 CrewAI 的人常疑惑 kickoff 跑完就結束,怎麼做多輪連續對話與跨次記憶。本文按官方文檔拆解 memory=True 的短期/長期/實體三層記憶、嵌入模型配置,以及用 Flows 狀態流和 @persist 搭建多輪會話的實戰寫法。

    其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~