crewai

CrewAI 专家技能

CrewAI 是一个用于基于角色的多 Agent 编排的框架。与 LangGraph 的底层状态机图不同，CrewAI 提供了更高层次的抽象：Agent 通过角色、目标和背景故事来定义，团队由内置的顺序或层级工作流组成，Agent 之间的委派也内置于框架中。

核心范式

from crewai import Agent, Task, Crew, Process
from crewai.tools import tool

@tool("search")
def search_web(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

researcher = Agent(
    role="Senior Researcher",
    goal="Find accurate information on any topic",
    backstory="Expert researcher with 10 years of experience",
    tools=[search_web],
    verbose=True,
)

writer = Agent(
    role="Technical Writer",
    goal="Write clear reports from research findings",
    backstory="Experienced technical writer",
    verbose=True,
)

research_task = Task(
    description="Research the topic thoroughly",
    expected_output="A detailed research brief",
    agent=researcher,
)

write_task = Task(
    description="Write a report based on research",
    expected_output="A well-structured report",
    agent=writer,
)

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

result = crew.kickoff()

核心原则

1. Agent 是角色，不是函数。 角色 + 目标 + 背景故事定义了 Agent 的身份。明确的角色定义可以减少幻觉。
2. 任务声明做什么，而非如何做。 描述 + 预期输出定义了任务。Agent 会自行决定如何执行。
3. 顺序流程适用于流水线，层级流程适用于复杂场景。 顺序流程按顺序执行任务。层级流程使用管理者 Agent 进行委派和验证。
4. 层级流程必须配置管理者 LLM。 未设置 manager_llm 时，层级流程会静默失败。
5. 委派循环确实会发生。 设置 allow_delegation=True 却不限制 max_iter，可能导致无限交接。
6. 工具错误不会抛出异常。 工具调用失败会将任务标记为失败，但不会抛出异常。请检查任务输出。

从哪里开始

你已有……	从这里开始
什么都没有——正在探索 CrewAI	使用 2 个 Agent 的顺序团队（研究 → 写作）
想要协调的 Agent	使用 manager_llm 构建层级团队
想要集成的工具	使用 @tool 装饰器，并将工具添加到相关 Agent
生产环境部署	添加回调、记忆和错误处理

快速参考

任务	方法	参考
定义 Agent	Agent(role, goal, backstory)	references/agent-design.md
定义任务	Task(description, expected_output, agent)	references/task-design.md
顺序团队	Crew(process=Process.sequential)	references/crew-patterns.md
层级团队	Crew(process=Process.hierarchical, manager_llm=...)	references/crew-patterns.md
创建工具	@tool("name") 装饰器	references/tool-integration.md
添加回调	在 Agent 上设置 step_callback=fn	references/callbacks.md
启用记忆	在 Crew 或 Agent 上设置 memory=True	references/crew-patterns.md

框架选择指南

场景	选择	原因
基于角色的多 Agent 团队	CrewAI	角色/目标/背景故事是其原生抽象
基于状态机的多 Agent 系统	LangGraph	图拓扑、子图和人在回路中
对话式多 Agent 系统	AutoGen	Agent 聊天是编排的基本构件
链/Agent 组合	LangChain	LCEL 管道运算符适用于通用链
文档查询 / RAG	LlamaIndex	数据摄取是其主要基本构件

参考文件

参考	加载时机	文件
Agent 设计	定义具有角色、目标和背景故事的 Agent 时	references/agent-design.md
任务设计	创建包含描述和输出的任务时	references/task-design.md
团队模式	使用顺序、层级和共识团队时	references/crew-patterns.md
工具集成	使用 @tool 装饰器创建工具时	references/tool-integration.md
回调	监控 Agent 和任务执行时	references/callbacks.md
记忆系统	使用统一的 Memory 类和跨 Agent 上下文时	references/memory-system.md
Flows	使用事件驱动编排来连接团队时	references/flows.md
常见问题与故障排除	遇到常见错误及其修复方法时	references/faq-and-troubleshooting.md

模板

模板	使用时机	文件
研究团队	顺序流程：研究员 → 撰写者 → 审阅者	templates/research-crew.py
层级团队	使用管理者和专业 Agent	templates/hierarchical-crew.py
客户支持	分流 → 专家 → 回复	templates/support-crew.py

故障排除

症状	可能原因	修复方法	参考
Crew 运行但没有输出	Agent 陷入委派循环	在 Agent 上设置 max_iter=15	references/agent-design.md
层级式 Crew 失败	未设置 manager_llm	添加 manager_llm=ChatOpenAI(model="gpt-4")	references/crew-patterns.md
任务始终无法完成	Agent 超出 max_iter	增大 max_iter 或简化任务	references/agent-design.md
未调用工具	未将工具添加到 Agent	在 Agent 定义中添加 tools=[my_tool]	references/tool-integration.md
Token 用量高	层级模式	Manager 会处理所有输出 — 使用成本更低的大模型	references/crew-patterns.md
任务之间的记忆不起作用	未设置 Crew 级记忆	在 Crew 中添加 memory=True	references/crew-patterns.md

何时不应使用 CrewAI

• 单 Agent 任务 — 对一个 Agent 来说抽象层过多
• 需要精细控制图（循环、条件分支）— 使用 LangGraph
• 需要对话式 Agent 交互 — 使用 AutoGen
• 需要简单的链组合 — 使用 LangChain LCEL