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 条评论

登录 后参与评论

还没有评论,来抢沙发~