7. CrewAI：角色化多智能体协作

这是什么：CrewAI = 用「角色扮演」思路组织多智能体协作的框架：给每个 Agent 一个岗位和目标，再把任务按流程派下去。

为什么用：上一章的 AutoGen 像个圆桌会议——大家都有发言权，组长决定谁来说。CrewAI 换了个思路：像组一个项目小组，每个人有岗位、有 KPI，任务按流程派下去。

如何用：本章用 Agent / Task / Crew / Process 四个概念搭出第一个小队，再把顺序流程、层级流程、上下文传递和检查点一次讲透。

基线：CrewAI 1.15.28（PyPI 包名 crewai）· crewai-tools 1.15.28 · Python ≥3.10 且 <3.14 · 模型经 LiteLLM 1.106.x 接入

7.1 CrewAI 是什么

CrewAI 的四个核心概念，一句话各一个：

概念	是什么	类比
Agent	有角色、目标、背景故事的执行者	团队成员
Task	一件具体要干的活，有明确产出	任务单
Crew	一组 Agent + 一组 Task + 协作方式	项目小组
Process	任务怎么串起来	工作流程

最不一样的一点：CrewAI 的 Agent 靠 role / goal / backstory 三件套来定义——尤其是 backstory（背景故事）。它不是装饰，而是提示词的一部分：给模型一个「我是谁」的人设，输出风格会明显不同。

7.2 安装与第一个小队

pip install crewai crewai-tools

import os
from crewai import Agent, Crew, Process, Task

# 模型走 LiteLLM，兼容服务也能接
MODEL = os.environ.get("CHAT_MODEL", "gpt-4o-mini")

researcher = Agent(
    role="资深资料员",
    goal="把 {topic} 的关键事实查清楚",
    backstory="你干了十年的资料员，习惯先核实再开口，从不编造。",
    verbose=True,
)

writer = Agent(
    role="技术作者",
    goal="把资料写成一篇读得懂的文章",
    backstory="你写技术博客十年，讨厌堆术语，擅长用大白话讲清楚。",
    verbose=True,
)

task_research = Task(
    description="调研 {topic}，列出 3~5 条关键事实，每条都要有出处。",
    expected_output="一份带出处的要点清单。",
    agent=researcher,
)

task_write = Task(
    description="根据调研要点写一篇 300 字的短文。",
    expected_output="一篇结构清晰、只讲事实的短文。",
    agent=writer,
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[task_research, task_write],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff(inputs={"topic": "RAG 是什么"})
print(result.raw)

你会看到（示意）：

[2026-10-21 10:00:00] INFO Crew: Executing task 1/2...
[2026-10-21 10:00:12] INFO Crew: Task completed successfully.
[2026-10-21 10:00:15] INFO Crew: Executing task 2/2...
[2026-10-21 10:00:30] INFO Crew: Task completed successfully.
RAG 是「检索增强生成」：先从你的资料库里把相关片段捞出来，再让大模型照着这些片段回答……

注意 kickoff(inputs=...)：任务描述里的 {topic} 就是从这里填进去的。

7.3 两种流程

Process	怎么跑	什么时候用
`Process.sequential`	任务按顺序一个个来，后一个能看到前面的产出	流程固定，写作→审核这类
`Process.hierarchical`	多一个经理 Agent 派活、验收	任务顺序不固定，需要临场分工

crew = Crew(
    agents=[researcher, writer],
    tasks=[task_research, task_write],
    process=Process.hierarchical,
    manager_llm=model,          # 层级流程必须给经理配模型
    verbose=True,
)

⚠️ 用 Process.hierarchical 一定要给 manager_llm 或 manager_agent，否则报错。

7.4 任务之间怎么传递上下文

顺序流程里，后一个任务默认看不到前一个任务的输出。要传，得显式声明 context：

task_write = Task(
    description="根据调研要点写一篇 300 字的短文。",
    expected_output="一篇结构清晰、只讲事实的短文。",
    agent=writer,
    context=[task_research],     # ← 明确说「参考上一个任务的产出」
)

这是 CrewAI 里最容易漏的一步：不写 context，第二个 Agent 就两眼一黑开始瞎编。

7.5 给 Agent 装工具

from crewai_tools import SerperDevTool       # 需要 SERPER_API_KEY

researcher = Agent(
    role="资深资料员",
    goal="把 {topic} 的关键事实查清楚",
    backstory="你干了十年的资料员，从不编造。",
    tools=[SerperDevTool()],
    verbose=True,
)

工具装在 Agent 上（不是 Task 上）——这个 Agent 干活时就能用。装完记得 pip install crewai-tools。

7.6 输出、记忆与检查点

跑完的 result 是个 CrewOutput：

print(result.raw)            # 最终文本
print(result.json_dict)      # 结构化输出（任务指定了 output_json 时有）
print(result.tasks_output)   # 每个任务的产出
print(result.token_usage)    # token 消耗

三个能明显提升体验的开关：

crew = Crew(
    agents=[researcher, writer],
    tasks=[task_research, task_write],
    process=Process.sequential,
    memory=True,              # 跨任务记忆
    cache=True,               # 工具结果缓存，同样的查询不再重复调
    checkpoint=True,          # 每完成一个任务存一次快照
    verbose=True,
)

断点续跑：

crew = Crew.from_checkpoint(".checkpoints/latest.json")
crew.kickoff()

7.7 AutoGen vs CrewAI 怎么选

维度	AutoGen	CrewAI
协作模型	圆桌：Agent 轮流/由组长挑人发言	小组：任务按流程派给指定的人
谁的产出	一段对话	每个任务一份产出，可分别取用
上手成本	要理解 Team、终止条件	三个字段（role/goal/backstory）就能跑
适合	讨论型、需要多轮碰撞的任务	流程明确的多步骤产出型任务

一句话：要「开会讨论出答案」用 AutoGen，要「分工协作交产出」用 CrewAI。

7.8 命令行脚手架

不想手写配置，CrewAI 提供了 CLI：

crewai create crew my_crew        # 新式：生成 crew.jsonc + agents/*.jsonc
crewai create crew my_crew --classic   # 老式：crew.py + YAML + 装饰器
crewai install                    # 装依赖
crewai run                        # 跑

⚠️ 安全提示：JSON 配置里支持 custom:<name> 工具和 {"python": "module.attribute"} 引用，加载时会执行本地 Python 代码——只运行自己信任来源的 crew 项目。

7.9 常见翻车现场

报错 / 现象	原因	修法
`Process.hierarchical` 报错	没给 `manager_llm`	补上经理模型
第二个任务在瞎编	没传 `context`	`context=[上一个任务]`
提示词里的 `{topic}` 没替换	`kickoff()` 没传 inputs	`kickoff(inputs={"topic": "..."})`
装不上	CrewAI 要求 Python < 3.14	用 Python 3.12 / 3.13 建环境
模型调用报错	LiteLLM 的 base_url 格式	用 `LLM(model=..., base_url=..., api_key=...)` 显式指定
反复调同一个工具	没开缓存	`cache=True`

7.10 动手改

把 7.2 的例子改成 Process.hierarchical，配一个 manager_llm，观察派活顺序
给 task_write 加上 context=[task_research]，对比加与不加时写出来的内容
开 cache=True，重复跑两次，看看工具调用次数和 token 消耗的变化

7.11 小结

CrewAI 的四个概念：Agent（role/goal/backstory）、Task（描述 + 期望产出）、Crew（组合）、Process（流程）
backstory 是提示词的一部分，用来定人设
顺序流程用 context=[...] 传递任务产出，不传就断链
层级流程必须配 manager_llm
memory / cache / checkpoint 三个开关，分别解决记忆、重复调用、断点续跑
和 AutoGen 的区别：AutoGen 是开会，CrewAI 是分工

下一章：给 Agent 装上手，工具描述写得好，Agent 才用得对 🐸