CrewAI 实战：构建多智能体协作工作流

CrewAI 把多智能体系统建模成一家小公司：你定义员工（Agent），给他们分派任务，再把他们编成一支执行某种流程的团队（Crew）。这个比喻正是框架真正的强项——它让你无需手写执行图就能表达一套角色化工作流。但它同时也是框架最大的风险：因为「多招几个 Agent」感觉很有生产力，哪怕单个 Agent 花零头的成本就能把活干完。本文讲清 CrewAI 擅长什么、给出一个可运行的示例，并交代那些真正决定「一支团队是否对得起其成本」的生产考量。内容最后一次技术核验时间为 2026 年 7 月 16 日。

核心要点

• CrewAI 的抽象——Agent、Task、Crew、Process——让角色化工作流很快就能表达出来。
• 只有当角色需要不同的工具、当独立的工作能真正并行、或当不同的人各自负责不同步骤时，一支团队才比单个 Agent 更值得。
• sequential 按声明顺序执行任务；hierarchical 增加一个负责委派的管理者 Agent。二者都不是天然并行的。
• backstory 塑造语气和行为，但它不强制权限——真正约束能力的是工具。
• 把搜索结果和任何工具返回值都当作不可信输入，而不是可以照抄的事实。
• 设置 max_iter，并让底层执行者不具备委派能力，以避免委派死循环。

为什么（以及何时）使用 CrewAI

一个草率的多智能体方案，常见的失败并不是模型不够聪明，而是几个角色模糊的 Agent 各说各话、陷入循环或跑题。CrewAI 通过强制结构来应对这一点：

• 角色与背景故事给每个 Agent 一个狭窄的职责范围，从而减少跑题输出。
• 带类型的任务通过显式的 expected_output 让交付物可校验。
• 一种流程（sequential 或 hierarchical）把控制流写明，而不是任其涌现。
• 工具生态接入更广的 LangChain 工具库。

这种结构确实有用。但请诚实看待替代方案：如果你的工作流是一条固定序列——先调研、再撰写——那么用同样的指令和工具的单个 Agent 往往能以更低成本产出同样的结果，而一条确定性流水线还要更可靠。正如本系列的多智能体系统指南所主张的，一支团队之所以值得付出协调成本，是因为角色需要不同的权限边界、工作能真正并行、或不同的人各自负责并评估不同步骤——而不是仅仅因为任务分了好几个阶段。

四个核心概念

• Agent（智能体）——一个工作者，拥有 role（职位）、goal（目标）、backstory（背景）和一组 tools（工具）。背景故事塑造行为；工具决定 Agent 实际能做什么。
• Task（任务）——一个工作单元，包含 description（描述），以及至关重要的 expected_output（明确「做完」长什么样）。
• Crew（团队）——统筹 Agent 与任务、并选择流程的容器。
• Process（流程）——执行模型。Process.sequential 按声明顺序执行任务，把每一步的输出向后传作上下文；Process.hierarchical 引入一个负责规划与委派的管理者 Agent。委派是动态路由，不是并行执行。

一个可运行的市场调研团队

我们来构建一支两个 Agent 的团队：一个调研主题，一个撰写报告。示例刻意做得很小，好让机制看得清楚。

环境准备

pip install crewai langchain-openai duckduckgo-search

把 API key 设在环境变量里而不是写进代码，并从环境变量读取模型名——因为模型标识符属于易腐信息：

export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="gpt-4o"

定义 Agent

backstory 设定每个 Agent 的语气和优先级。注意它不能做什么：它既不授予也不限制能力。研究员之所以能搜索，是因为它拿到了 search_tool；写作者不能，是因为它没有。

import os
from crewai import Agent, Task, Crew, Process
from langchain_openai import ChatOpenAI
from langchain_community.tools import DuckDuckGoSearchRun

llm = ChatOpenAI(model=os.environ.get("OPENAI_MODEL", "gpt-4o"), temperature=0.3)
search_tool = DuckDuckGoSearchRun()

researcher = Agent(
    role="资深 AI 行业分析师",
    goal="发现并分析 AI 编码助手当前的市场动态",
    backstory=(
        "你擅长从碎片化的来源中提取核心数据与竞争结构，"
        "并会记录每一条论断的出处。"
    ),
    verbose=True,
    allow_delegation=False,  # 叶子执行者不应委派
    tools=[search_tool],
    llm=llm,
)

writer = Agent(
    role="首席科技专栏作家",
    goal="把调研结果转化为清晰、结构良好的报告",
    backstory=(
        "你行文平实，绝不陈述调研没有支撑的事实。"
    ),
    verbose=True,
    allow_delegation=True,  # 写作者可向研究员索要更多材料
    llm=llm,
)

定义任务

任务的价值在于它的 expected_output。含糊的交付物只会产出含糊的结果；具体的交付物则给 Agent——也给你——一个可校验的目标。

research_task = Task(
    description=(
        "调查 AI 编码助手当前的竞争格局。对每个产品，记录它的差异化"
        "论断，以及该论断的出处。"
    ),
    expected_output=(
        "至少三个产品的对比，每个都列出其宣称的优势、劣势和来源链接，"
        "并标注无法核实的论断。"
    ),
    agent=researcher,
)

write_task = Task(
    description=(
        "仅根据调研输出，撰写一份分析报告，包含引言、市场格局、产品对比，"
        "以及一个明确标注的展望部分。"
    ),
    expected_output=(
        "一份结构良好的 Markdown 报告，不复述任何被调研标为无法核实的论断。"
    ),
    agent=writer,
)

组建并运行

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,  # 每个任务的输出喂给下一个
    verbose=True,
)

result = crew.kickoff()
print(result)

在串行团队里，研究员的输出会自动成为写作者的上下文。这里值得把话挑明：调研→撰写是一条固定流水线，因此这支团队是学习 CrewAI 的好方式，但相比给单个 Agent 同样两段提示词，它带来的额外收益很少。只有当写作者必须回头委派以补充缺失证据、当步骤会依据结果分叉、或当管理者动态路由工作时，它才成为一个真正的多智能体案例。

串行流程 vs 层级流程

要让管理者 Agent 规划并委派，切换流程并提供 manager_llm：

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.hierarchical,
    manager_llm=ChatOpenAI(model=os.environ.get("OPENAI_MODEL", "gpt-4o")),
)

层级模式更灵活，但也更贵、更难调试：管理者会增加模型调用，委派也可能循环。当任务如何拆解事先并不清楚时，它才划算。当步骤固定时，sequential 更便宜、也更容易推理。

安全地集成工具

CrewAI 的能力半径来自 LangChain 工具生态：一个 Agent 可以查询 SQL 数据库、读取仓库 Issue，或运行本地脚本。这里每一项也都在扩大爆炸半径，因此要把工具访问当作安全决策，而不是图方便。

• **每个 Agent 最小权限。**只给每个 Agent 其角色所需的工具。一个只读的调研 Agent 不应持有写入或 shell 工具。约束这一点的不是 role 字符串，而是 tools 列表。
• **工具返回值是不可信输入。**一次网页搜索返回的是网页说了什么，其中可能包含为操纵模型而精心构造的内容。不要让 Agent 把检索到的文本当作带授权的指令或已核实的事实——要校验并标注出处。
• **认证不是授权。**如果某个工具封装了内部 API，就要在工具内部、每次调用时强制对象级和租户级的访问控制。一支团队能触达某个端点，并不等于它被允许对某条具体记录采取行动。
• **凡是执行代码的都要沙箱化。**本地脚本执行应在隔离环境中运行，绝不能直接跑在持有生产凭据的主机上。

常见问题

Agent 之间来回踢皮球或死循环怎么办？

这是无约束委派的典型症状。在每个 backstory 里收紧职责边界，设置任务的 max_iter，并让叶子执行者不具备委派能力（allow_delegation=False）。如果循环仍在持续，多半是任务拆解本身有问题——先简化，再谈加控制。

CrewAI 和 AutoGen 能一起用吗？

从架构上看它们是竞争关系，但任一方都能被封装成对方系统里的一个工具节点。当你想要显式的、基于角色的流程控制时选 CrewAI；关于有状态控制方面各方案如何对比，参见 LangGraph 与 AutoGen 对比。

怎样避免团队复述无法核实的论断？

把出处纳入 expected_output：要求每一条调研论断都带来源、把无法核实的标出来，并指示写作者略去所有未标注的内容。然后针对真实任务评估实际输出——一份精美的报告仍可能是错的，所以发布门禁是结果验证，而不是流畅的文笔。

总结

CrewAI 把多智能体系统变成可以像一个组织那样去推理的东西，这正是它真正的价值：角色、任务，以及一条可见的流程。当角色需要不同工具、工作能并行、或不同的人负责不同步骤时用它；当工作流只是一条固定序列时，转而用单个 AI Agent 或一条确定性流水线。而无论哪种 Agent，让它安全的纪律都一样：每个 Agent 最小权限、工具返回值不可信、针对真实结果做评估。

一手资料

• CrewAI 官方文档
• CrewAI：串行流程与层级流程
• Anthropic：Building Effective Agents
• LangChain 工具文档