菜单
SOP for building multi-agent systems with CrewAI — role-based collaboration, sequential/hierarchical processes, Flows, memory, delegation. Use when modeling agent teams with clear roles and task pipelines.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/agentsope/SkillAlchemy --skill agentsop-crewai命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | agentsop-crewai |
| version | 1.0.0 |
| description | SOP for building multi-agent systems with CrewAI — role-based collaboration, sequential/hierarchical processes, Flows, memory, delegation. Use when modeling agent teams with clear roles and task pipelines. |
| domain | multi-agent-orchestration |
| framework | crewAI |
| framework_version | >=0.80, current 1.14.x (May 2026) |
| trigger_keywords | ["multi-agent crew","role-based agents","agent collaboration","sequential process","hierarchical agents","manager agent","CrewAI Flow","agent delegation"] |
| when_to_use | ["modeling 2-5 specialized agents with clear roles (researcher + writer + reviewer)","linear or hierarchical content pipelines where role separation is intuitive","rapid prototyping of agent teams without graph-state engineering","business workflows where ops/PM can reason about agents as 'team members'"] |
| when_not_to_use | ["single-agent tasks (~80% of use cases per production guides — use plain LLM call)","cyclic / state-rich workflows with branching logic (use LangGraph)","real-time / sub-second latency (multi-agent handshakes add 30–50% tokens)","conversational debate / negotiation patterns (use AutoGen)","deterministic routing with strict SLA (CrewAI hierarchical executes tasks sequentially regardless of triage)"] |
框架口号: "Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly." [github.com/crewAIInc/crewAI]
"An agent needs agency, otherwise it's just another script." — João Moura, CrewAI 创始人 [softwareengineeringdaily.com/2025/06/03/crew-ai-with-joao-moura/]
如果你能用 if/else 提前写死流程，不要用 Crew。Crew 的本质是把"决策权"让渡给 LLM 角色。
Agent (role + goal + backstory) ← 谁
↓ 持有
Task (description + expected_output + agent + context) ← 做什么
↓ 组装
Crew (agents + tasks + process) ← 怎么协作
↓ 选择
Process (sequential | hierarchical) + Flow (event-driven 编排) ← 控制流
CrewAI 的核心假设：LLM 在 role-playing 状态下表现更好。
"Backstory provides depth to the agent's persona, enriching its motivations and engagements within the crew." [docs.crewai.com/en/concepts/agents]
关键洞察: backstory 不是装饰。它是 system prompt 的最大杠杆——同一个 role+goal，换 backstory 会显著改变产出质量与风格。
| 维度 | Sequential | Hierarchical |
|---|
| Flow |
|---|
| 任务路由 | 静态列表顺序 | manager LLM 动态分派 | @listen 事件驱动 |
| 控制力 | 高 (写死顺序) | 低 (manager 自由发挥) | 最高 (代码 + 状态) |
| Token 开销 | 1× 基线 | 1.3–1.5× (manager overhead) | 接近 1× |
| 调试难度 | 低 | 高 (manager 黑盒) | 中 |
| 何时用 | 80% 场景默认 | 真正需要动态分派 | 复杂分支 + 多 Crew 编排 |
| 已知坑 | task context 自动透传可能膨胀 | manager 会"执行所有 task"而非"按需调用" | 学习曲线 + 状态设计 |
参考: [docs.crewai.com/en/learn/hierarchical-process], [docs.crewai.com/en/concepts/flows], [towardsdatascience.com/why-crewais-manager-worker-architecture-fails-and-how-to-fix-it/]
CrewAI 从零写成、零 LangChain 依赖，是 João Moura 刻意决定。这带来：
print 不易冒出来 [aaronyuqi.medium.com/first-hand-comparison-of-langgraph-crewai-and-autogen][问] 这个任务是否需要 ≥2 个截然不同的"专业视角"协作？
├─ 否 → 用单 agent + tools，停止使用 CrewAI
└─ 是 → 继续
[问] 流程是否有循环 / 状态依赖 / 人工中断点？
├─ 是 → 转 LangGraph (或 CrewAI Flow + 简化的 Crew)
└─ 否 → 进入 Phase 1
researcher = Agent(
role="Senior AI Research Analyst", # ← 名词性头衔，含"高级/资深"提升先验
goal="Uncover cutting-edge developments in {topic} with citations", # ← 含 {var} 模板 + 验收标准
backstory=(
"You're a methodical researcher with 10 years at top AI labs. "
"You distrust hype and always cross-check with primary sources." # ← 注入判断偏好
),
allow_delegation=False, # ← 默认 False，避免 ping-pong
max_iter=10, # ← 显式收敛上限（默认 20–25）
verbose=True, # ← 开发期必开
tools=[search_tool],
)
配置与代码分离，使用 @CrewBase 装饰器 + config/agents.yaml + config/tasks.yaml，便于非工程人员迭代提示词 [docs.crewai.com YAML Configuration]。
"Analyze the search results for {topic} and identify 3 emerging trends""A markdown report with H2 headers per trend, each containing: trend name, 3 supporting citations, risk assessment"output_pydantic=MyModel 强制结构化 [docs.crewai.com/en/concepts/tasks]analysis_task = Task(
description="...",
expected_output="...",
agent=analyst,
context=[research_task], # ← 不依赖隐式自动透传，显式声明
)
"In crewAI, the output of one task is automatically relayed into the next one, but you can specifically define what tasks' output … should be used as context."
默认隐式透传是坑——pipeline 长了之后 prompt 爆炸。建议从一开始就显式 context=[...]。
crew = Crew(
agents=[researcher, analyst, writer],
tasks=[research_task, analysis_task, write_task],
process=Process.sequential, # ← 默认；改 hierarchical 前请读 §5.2
memory=False, # ← 默认关，除非真的跨 kickoff 需要持久化
verbose=True,
max_rpm=30, # ← 防止 API 限流爆炸
planning=False, # ← v0.80+ 的实验功能，生产前先测
)
result = crew.kickoff(inputs={"topic": "agentic RAG"})
CrewAI 内部日志薄。生产前必须：
mlflow.crewai.autolog() 或 Maxim / Langfuse / Datadogstep_callback= 捕获每步 agent action [docs.crewai.com/en/observability/overview]kickoff 设硬上限（外层 timeout + max_rpm）expected_output 契约是否兑现allow_delegation=False、max_iter=10context=[...]；可选 output_pydanticProcess.sequential；只有当任务路由真的需要 LLM 动态判断时才用 Process.hierarchical + 自定义 manager_agent（不要用裸 manager_llm）process= 与（若 hierarchical）一个带详细 backstory 的 manager_agentcontext=[...] 显式传递；只有当真的需要"跨 session 持久"才 memory=True；高级场景考虑 Mem0 后端memory=False 或 memory=Memory(scope=...)mlflow.crewai.autolog() + max_rpm + max_iter 每 agent + 外层 timeout + step_callback@start/@listen 写 Flow，每个 step 内部可 crew.kickoff()场景: writer agent 输出质量差，反复 self-critique，5 次迭代后还在改文章结构。
两条路:
判断规则:
推荐: 默认拆。CrewAI 的核心红利就在"单一职责角色"。当你纠结要不要拆，答案 80% 是拆。
"Single-agent is right for approximately 80% of cases; the trap is reaching for multi-agent because it sounds more capable. But once you've committed to multi-agent, the next trap is putting too much in one agent." [daily.dev AI agents guide]
Evidence: [§2.2, anti-patterns]
场景: 5 个 agent，task 顺序大致固定但偶尔需要根据上游结果跳过某些 task。
陷阱: 看起来"hierarchical 应该能自动路由"，但实测 hierarchical 会执行所有 task，不会真的按 triage 结果跳过 [towardsdatascience.com Manager-Worker fails]。论文式案例：
Query: "Why is my laptop overheating?" (纯技术问题)
期望: triage → technical_agent → done
实际 hierarchical: triage → technical → billing → ... → 最后一个 task 的输出覆盖前面
三条路:
@listen + 条件函数显式路由，每分支调用一个小 Crew 或单 agent。判断规则:
红线: 永远不要把生产路由依赖默认 manager_llm——João Moura 团队也承认这是当前最大坑之一 [github.com/crewAIInc/crewAI/discussions/1220]。
Evidence: [§2.3, community.crewai.com/t/5710, towardsdatascience.com]
场景: 你有 web_search、code_executor、db_query 三个工具，3 个 agent (researcher / analyst / reporter)。
两条路:
tools=[search, exec, db]。简单但 agent 容易"逛工具" — researcher 也调 code_executor 写代码，违背角色分工。判断规则:
Evidence: [docs.crewai.com/en/concepts/tools, community.crewai.com/t/tool-best-practice-assign-to-agent-or-task/5919]
场景: 一个客服 crew，多个会话之间是否需要记住用户？
陷阱:
memory=True 默认开 short_term + entity，会自动跑额外 LLM 调用做"记忆 LLM 分析"，token 翻倍判断规则:
context=[...] 显式传，不用 memorymemory=True；首选 long_term（SQLite，便宜）memory=False，不然 trace 难读红线: 不要把"agent 没记住 X"当成必须开 memory 的信号。99% 的情况是 task description 没把 X 写清楚。
Evidence: [docs.crewai.com/en/concepts/memory, §4]
场景: hierarchical 模式下，是否给 worker agent 也开 allow_delegation=True？
陷阱: 多个 agent 都能 delegate → delegation ping-pong，agents 互相传球，token 爆炸 + 超时。已知 GitHub issue [#330 #4783 #2606]。
根因:
DelegateWorkTool schema 期望 string，新 LLM 传 dict，silent validation 失败 → 重试 [azguards.com delegation ping-pong]max_iter 在 hierarchical 跨 handoff 时不生效，protection 形同虚设判断规则:
allow_delegation=False 在所有 worker agent 上allow_delegation=FalseEvidence: [github.com/crewAIInc/crewAI/issues/330, azguards.com, inkog.io/glossary/crewai-infinite-loop]
| # | 反模式 | 症状 | 修复 |
|---|---|---|---|
| AP-1 | Agent 数量爆炸 (>5 个 agent) | 协调失败、token 飞涨、debug 困难 | 合并职能近似的 agent；7+ 几乎必拆 Flow |
| AP-2 | Backstory 不写或写"你是助手" | 输出风格平庸、判断偏好混乱 | 注入经验、判断偏好、禁忌 |
| AP-3 | 依赖默认 hierarchical manager_llm | manager 执行所有 task / 路由错乱 | 永远自定义 manager_agent，或换 Flow |
| AP-4 | allow_delegation=True 全开 | 无限 delegation ping-pong | 默认关，仅 manager 开 |
| AP-5 | 没 observability 就上生产 | trace 黑盒，故障无法复现 | 上线前必接 MLflow/Maxim/Datadog |
| 场景 | 替代方案 |
|---|---|
| 单 agent 就够（80% 任务） | OpenAI/Anthropic SDK + Instructor/Outlines |
| 状态机 / 循环 / human-in-the-loop / 中断恢复 | LangGraph |
| 长对话 / 辩论 / 群体决策 | AutoGen |
| 简单工具调用 + handoff | OpenAI Swarm / Anthropic Computer Use |
| 数据为中心的 RAG (300+ connectors) | LlamaIndex |
| 严格的低延迟 SLA | 不用 multi-agent 框架，直接编排 |
| 需要 production-grade durability + 精细 state | LangGraph (已成 production-deployment 事实标准) |
print() 经常不冒头。用 step_callback 或 verbose=True{topic} 在 kickoff(inputs={"topic": ...}) 时替换，不写在 inputs 里就是字面 "{topic}"| 框架 | 一句话定位 | 第一抽象 | 哲学 |
|---|---|---|---|
| CrewAI | "Agents are role-playing teammates" | Agent (role) | 把 LLM 当人格化协作者 |
| LangGraph | "Agents are nodes in a state graph" | Node + State | 把 agent 当可编译的图 |
| AutoGen | "Agents are chat participants" | Conversation | 把 agent 当群聊成员 |
你的核心需求是什么？
├─ 多角色明确 + 任务可线性串 → CrewAI Sequential
├─ 多角色 + 需要事件驱动分支 → CrewAI Flow（内嵌 Crew）
├─ 状态/循环/中断/恢复/precise control → LangGraph
├─ 多 agent 辩论/谈判/群体决策 → AutoGen
├─ 单 agent + handoff (不需要协作) → OpenAI Swarm / Anthropic
└─ 数据为中心 RAG → LlamaIndex
from crewai import Agent, Task, Crew, Process
researcher = Agent(
role="Senior AI Research Analyst",
goal="Surface 3 emerging trends in {topic} with verifiable citations",
backstory=(
"You're a meticulous researcher who distrusts hype and demands "
"primary sources. You've spent a decade at frontier AI labs."
),
allow_delegation=False,
max_iter=8,
verbose=True,
)
writer = Agent(
role="Technical Writer",
goal="Turn research findings into a crisp executive brief",
backstory=(
"You write for time-poor execs. Bullet points over paragraphs. "
"You refuse to ship without inline citations."
),
allow_delegation=False,
max_iter=5,
verbose=True,
)
research_task = Task(
description="Research {topic}. Find 3 emerging trends from 2025–2026.",
expected_output=(
"Markdown with 3 H2 sections, each: trend name, 2-sentence summary, "
"≥2 citations (URL + title)."
),
agent=researcher,
)
write_task = Task(
description="Write an executive brief from the research output.",
expected_output="≤400 word brief, bullet structure, inline citations preserved.",
agent=writer,
context=[research_task], # 显式
)
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, write_task],
process=Process.sequential,
memory=False,
verbose=True,
max_rpm=30,
)
result = crew.kickoff(inputs={"topic": "agentic RAG"})
print(result.raw)