CrewAI 核心概念：Agent / Task / Crew / Process

一、概念速查

四大核心概念

概念	类比	职责
Agent	团队中的个人	具备特定角色、技能和目标，能独立完成分配的任务
Task	工作任务单	明确描述做什么、用什么工具、输出什么，可指派给 Agent 或标记为协作
Crew	项目团队	管理 Agent 成员和 Task 队列，协调执行流程
Process	工作流引擎	定义 Task 的分发和完成顺序——串行、层级还是异步

Agent 配置参数

from crewai import Agent, Task, Crew, Process  # crewai>=0.30.0

agent = Agent(
    role="数据分析师",
    goal="从原始数据中提取有价值的业务洞察",
    backstory="你是一位有 10 年经验的资深数据分析师，擅长使用 Python 处理数据",
    tools=[],                         # 可用工具列表
    verbose=True,                     # 输出详细执行日志
    allow_delegation=False,           # 是否可委托任务给其他 Agent
    max_iter=15,                      # 单任务最大迭代次数
    memory=True,                      # 启用记忆
    cache=True,                       # 启用工具调用缓存
)

Task 配置参数

from crewai import Task  # crewai>=0.30.0

task = Task(
    description="分析销售数据文件 sales.csv，找出过去三个月的增长趋势",
    expected_output="包含月度增长率、TOP 5 产品和可视化图表的分析报告",
    agent="数据分析师",               # 指定的 Agent（可选，也可指定 crew 自动分配）
    tools=[],                         # 任务级工具覆盖
    async_execution=False,            # 是否异步执行
    context=[],                       # 依赖的其他任务输出
    human_input=False,                # 是否需要人工输入
)

代码示例：最小完整 Crew

from crewai import Agent, Task, Crew, Process  # crewai>=0.30.0

writer = Agent(
    role="技术写手",
    goal="撰写清晰的技术文档",
    backstory="你擅长用通俗语言解释复杂技术概念。",
)

researcher = Agent(
    role="技术研究员",
    goal="收集和分析技术资料",
    backstory="你擅长从文档和代码库中提取关键信息。",
)

research = Task(
    description="研究 CrewAI 框架的 Process 机制，包括顺序、层级和异步三种模式",
    expected_output="包含每种模式的优缺点对比表的研究笔记",
    agent=researcher,
)

write = Task(
    description="基于研究笔记撰写一篇 CrewAI Process 机制的技术博客",
    expected_output="一篇 800 字以上的技术博客，包含代码示例",
    agent=writer,
    context=[research],  # 依赖 research 的输出
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research, write],
    process=Process.sequential,  # 顺序执行
)

result = crew.kickoff()
print(result)

二、底层原理

Crew 执行流程

Agent 的执行循环

每个 Agent 内部运行一个 ReAct 循环：接到 Task 后解析描述 → 规划执行步骤 → 调用工具获取信息 → 观察结果 → 迭代直至产出预期输出。max_iter 参数控制最大迭代轮数，防止无限循环。工具调用失败时触发内置重试机制，重试耗尽后标记 Task 失败并报告到 Crew。

三种 Process 模式的差异

模式	调度方式	适用场景	优缺点
sequential	Task 列表顺序执行	流水线型任务	简单可靠，但并行度低
hierarchical	Manager Agent 动态分配和协调	任务不确定性高	灵活但需额外 LLM 调用
async	独立 Task 并行出队	子任务无依赖关系	吞吐高但结果聚合复杂

工具调用与缓存机制

CrewAI 的工具调用内置了基于输入哈希的缓存层。当同一个 Tool 以相同参数调用时，直接返回缓存结果而不是重新执行。这在 Agent 的 ReAct 循环中尤其有用——如果 Agent 反复查询同一数据，不会重复消耗 API 额度。缓存在 Crew 级别共享，跨 Task 的相同调用也会命中。

Memory 系统架构

Agent 可启用三类记忆：

1. 短期记忆：当前会话的执行上下文，用于保持多步推理的连贯性
2. 实体记忆：存储任务执行中识别到的关键实体和关系
3. 长期记忆：跨会话持久存储，保存在本地 SQLite 中，下次 kickoff 可加载

记忆通过 embedding 向量化后检索，在每次 Agent 执行前注入到 system prompt 中。

三、架构设计原则

1. 角色驱动设计

每个 Agent 必须定义 role、goal 和 backstory。这三要素构成 Agent 的"人格"，直接影响 LLM 的行为风格和决策倾向。role 定义身份，goal 定义目标，backstory 为历史行为提供上下文。三要素缺失任何一个，Agent 的输出质量都会明显下降。

2. Task 依赖显式声明

Task 之间通过 context 参数声明依赖关系。不声明则视为可并行。这种显式依赖图让 Process 引擎可以在执行前就计算出最优调度策略，而不是在运行时随机应变。

3. 错误隔离与容错

单个 Agent 的失败不会拉垮整个 Crew。失败 Task 的异常信息会写入输出，Process 引擎根据 process 模式决定是否跳过、重试或终止。生产环境建议将 max_iter 设为合理上限而不是默认值，并在每个 Task 中启用 human_input 作为最后兜底。

4. 工具级覆盖优于全局配置

Task 的 tools 参数优先级高于 Agent 的 tools。这允许你在不同上下文中复用同一 Agent 但配备不同工具集。例如"数据分析师"在"数据清洗"Task 中只用 pandas，在"可视化"Task 中只用 matplotlib。

5. 输出可追溯性

每个 Task 的完整执行日志（包括工具调用、LLM 推理过程、中间结果）默认写入 verbose 输出。生产部署时应将日志接入外部系统，因为 CrewAI 本身不提供持久化日志存储。每次 crew.kickoff() 返回的 CrewOutput 包含所有 Task 的输出快照。