Skip to main content Home Creators agentsope skillalchemy agentsop-crewai
agentsop-crewai 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.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/agentsope/SkillAlchemy --skill agentsop-crewaiThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository SkillAlchemy — One thought conceived, one goal achieved. Accept any idea or
distillation target and produce an installable SKILL.md.
It uses Lens to clarify the problem and LEAP to run distillation or fusion.
This is the sole user-facing entry point.
Use when the user asks to distill, generate a skill, fuse skills, or says,
"I want to build X, but I do not know where to start."
LEAP builds skills through two pipelines: Branch A distills a skill from raw
data, while Branch B combines multiple skills into one. It is called by the
main SkillAlchemy workflow. Use when SkillAlchemy requires distillation or fusion.
Lens — Add a cognitive lens to any problem. It accepts a task description and
produces an enhanced description that surfaces hidden dimensions, prerequisites,
and lines of inquiry—the things you do not know you do not know.
Use when the user asks to brainstorm, analyze, generate a skill, distill, or fuse,
or when the input is too simple and needs to be expanded.
Related occupations SOC
Based on SOC occupation classification
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)"]
CrewAI SOP — Role-Based Multi-Agent Orchestration
框架口号: "Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly." [github.com/crewAIInc/crewAI]
1. 何时激活 (When to Activate)
1.1 直接信号 (Direct triggers)
用户说 "我需要 researcher + writer + reviewer 这种团队配合"
用户说 "用 CrewAI 实现 / 我已经在用 crew.kickoff()"
任务可以拆为 2–5 个专业角色 ，且每个角色有明确职责边界
流程是线性 pipeline （数据→分析→报告）或轻度分支
1.2 反向信号 (Skip CrewAI when)
单 agent + tool-use 就够 → 直接用 SDK / Instructor（CrewAI 是 over-engineering）
需要状态图 + 循环 + 中断恢复 → LangGraph 更合适
需要 agents 之间自由对话辩论 → AutoGen 更合适
需要严格条件路由（"if X then only A else B"）→ 用 CrewAI Flows 而非 hierarchical Crew，或直接 LangGraph
延迟敏感（<500ms） → 多 agent 编排不适合
1.3 心智门槛 (Mental check)
"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 角色。
2. 核心心智模型 (Mental Model)
2.1 四元抽象 (The 4 primitives)
Agent (role + goal + backstory) ← 谁
↓ 持有
Task (description + expected_output + agent + context) ← 做什么
↓ 组装
Crew (agents + tasks + process) ← 怎么协作
↓ 选择
Process (sequential | hierarchical) + Flow (event-driven 编排) ← 控制流
2.2 为什么 "role + goal + backstory" 三件套？
CrewAI 的核心假设：LLM 在 role-playing 状态下表现更好 。
role : 函数性身份 ("Senior Data Researcher") — 决定 prompt 主语goal : 个体目标 ("Uncover cutting-edge developments in {topic}") — 决定决策方向backstory : 经验/性格 ("You're a seasoned researcher with a knack for…") — 校准语气与判断风格
"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 会显著改变产出质量与风格。
2.3 Sequential vs Hierarchical vs 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/]
2.4 Crew 不是 LangChain CrewAI 从零写成、零 LangChain 依赖 ，是 João Moura 刻意决定。这带来：
更快 import / 更小 footprint
但生态工具少 （observability、eval 需要外接 Maxim/MLflow/Datadog）
错误日志在 Task 内部不易捕获，print 不易冒出来 [aaronyuqi.medium.com/first-hand-comparison-of-langgraph-crewai-and-autogen]
3. SOP 工作流 (Standard Operating Procedure)
Phase 0: 决策 — 真的需要 Crew 吗？ [问] 这个任务是否需要 ≥2 个截然不同的"专业视角"协作？
├─ 否 → 用单 agent + tools，停止使用 CrewAI
└─ 是 → 继续
[问] 流程是否有循环 / 状态依赖 / 人工中断点？
├─ 是 → 转 LangGraph (或 CrewAI Flow + 简化的 Crew)
└─ 否 → 进入 Phase 1
Phase 1: 角色设计 (Agent Design)
1.1 拆分原则
每个 agent 一个职能动词 : research / write / review / extract / decide避免 "万能 agent"。一个 agent 同时 research + write，质量必劣于两个专家
2–5 个 agent 是甜区 。≥7 个开始出现协调失败 [medium.com/@armankamran/anti-patterns-in-multi-agent-gen-ai-solutions]
1.2 三件套写法 (role/goal/backstory) researcher = Agent(
role="Senior AI Research Analyst" ,
goal="Uncover cutting-edge developments in {topic} with citations" ,
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 ,
max_iter=10 ,
verbose=True ,
tools=[search_tool],
)
1.3 YAML 化（生产推荐） 配置与代码分离，使用 @CrewBase 装饰器 + config/agents.yaml + config/tasks.yaml，便于非工程人员迭代提示词 [docs.crewai.com YAML Configuration]。
Phase 2: 任务设计 (Task Design)
2.1 描述写法 (description)
动词开头 + 具体输入："Analyze the search results for {topic} and identify 3 emerging trends"不要写 how ，写 what。HOW 是 agent 的自由度长度建议: 1–4 句。过长 = 把 agent 当工程模板用，违背 agency 哲学
2.2 expected_output（验收契约）
必填 。这是 CrewAI 的"测试断言"写成可机器校验的结构化描述："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]
2.3 context 显式声明依赖 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=[...]。
Phase 3: 装配 Crew crew = Crew(
agents=[researcher, analyst, writer],
tasks=[research_task, analysis_task, write_task],
process=Process.sequential,
memory=False ,
verbose=True ,
max_rpm=30 ,
planning=False ,
)
result = crew.kickoff(inputs={"topic" : "agentic RAG" })
Phase 4: 观测与收敛
4.1 必装观测
接 mlflow.crewai.autolog() 或 Maxim / Langfuse / Datadog
包一层 step_callback= 捕获每步 agent action [docs.crewai.com/en/observability/overview]
4.2 token / 成本上限
单次 kickoff 设硬上限（外层 timeout + max_rpm）
Hierarchical 模式追加 30–50% token 预算 [callsphere.ai/blog/crewai-process-types]
4.3 eval 化
把每次失败的 kickoff trace 转成 eval case
用 LLM-as-judge 检查 expected_output 契约是否兑现
4. 操作模型 (Operational Model — Trigger / Action / Output / Evidence)
OP-1: 决定是否使用 CrewAI
Trigger : 用户描述任务时出现"团队/协作/不同角色"语义Action : 检查 §1.1/§1.2 清单 + Phase 0 决策树Output : 三选一 — (a) 用 CrewAI Sequential, (b) 用 CrewAI Flow+Crew, (c) 换框架Evidence : [§1, github.com/crewAIInc/crewAI README]
OP-2: 设计 agent role/goal/backstory
Trigger : 已决定用 Crew，开始建模角色Action : 每个 agent 填 role (头衔)、goal (含 {var} 与验收)、backstory (经验+判断偏好)；默认 allow_delegation=False、max_iter=10Output : agents.yaml 或 Python Agent() 调用Evidence : [docs.crewai.com/en/concepts/agents, §2.2]
OP-3: 写 Task
Trigger : agent 设计完毕，开始拆任务Action : description 写 what 不写 how；expected_output 写可校验契约；显式 context=[...]；可选 output_pydanticOutput : tasks.yaml 或 Task() 调用列表Evidence : [docs.crewai.com/en/concepts/tasks, §3.2]
OP-4: 选 Process
Trigger : 装配 Crew 前Action : 默认 Process.sequential；只有当任务路由真的需要 LLM 动态判断时才用 Process.hierarchical + 自定义 manager_agent （不要用裸 manager_llm）Output : process= 与（若 hierarchical）一个带详细 backstory 的 manager_agentEvidence : [§5.2, towardsdatascience.com 'Manager-Worker fails']
OP-5: 启用 Memory
Trigger : 跨 kickoff 需要"记住"或同一 kickoff 内复杂上下文聚合Action : 优先用 task context=[...] 显式传递；只有当真的需要"跨 session 持久"才 memory=True；高级场景考虑 Mem0 后端Output : memory=False 或 memory=Memory(scope=...)Evidence : [docs.crewai.com/en/concepts/memory, mem0.ai/blog/crewai-memory-production-setup-with-mem0]
OP-6: 加观测与上限
Trigger : 上生产前Action : mlflow.crewai.autolog() + max_rpm + max_iter 每 agent + 外层 timeout + step_callbackOutput : 可观测、可中止的 CrewEvidence : [docs.crewai.com/en/observability/overview, §4]
OP-7: 从 Crew 升级到 Flow
Trigger : Crew 出现 — (1) 需要条件分支 (2) 需要多个 Crew 串联 (3) hierarchical 不可控Action : 用 @start/@listen 写 Flow，每个 step 内部可 crew.kickoff()Output : 一个 Flow 类，state 用 Pydantic BaseModelEvidence : [docs.crewai.com/en/concepts/flows, community.crewai.com/t/5710]
5. 困境决策案例 (Dilemma Cases)
DC-1: Agent 卡住反复重试 — 改 prompt 还是拆 agent？ 场景 : writer agent 输出质量差，反复 self-critique，5 次迭代后还在改文章结构。
A. 改 prompt — 把 backstory 写得更具体，goal 加更严的验收。优点：零改动 crew 结构。缺点：当 agent 在做"两件不同的事"（写 + 审），单 prompt 永远抓不住。B. 拆 agent — writer + reviewer 双 agent，sequential pass。优点：每个 agent 职责单一，更稳定。缺点：多一次 LLM 调用，token+50%。
看失败案例：失败模式是否风格不一致 ？ → 改 backstory
失败模式是否遗漏检查项 （事实错误、格式错误）？ → 拆 agent ，让 reviewer 用结构化 checklist
如果 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]
DC-2: Sequential vs Hierarchical — 何时 manager 开销值得？ 场景 : 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 的输出覆盖前面
A. Sequential — 写死顺序，所有 task 都跑。简单稳定但浪费 token。B. Hierarchical + 默认 manager_llm — 不推荐 。manager 会失控执行所有 task。C. Hierarchical + 自定义 manager_agent (带显式分支 backstory) — 可工作但需要细致 prompt 工程。D. CrewAI Flow — 用 @listen + 条件函数显式路由，每分支调用一个小 Crew 或单 agent。
路由逻辑可以用 5 行 Python 表达 ？ → 用 Flow (D)
路由真的需要 LLM 语义理解（不能写规则）→ Hierarchical + 自定义 manager （C），永远不要 靠默认 manager_llm
不确定 → 先 Sequential (A)，性能可接受就停
红线 : 永远不要把生产路由依赖默认 manager_llm ——João Moura 团队也承认这是当前最大坑之一 [github.com/crewAIInc/crewAI/discussions/1220]。
Evidence : [§2.3, community.crewai.com/t/5710, towardsdatascience.com]
DC-3: 工具共享 vs 每个 agent 独立工具集？ 场景 : 你有 web_search、code_executor、db_query 三个工具，3 个 agent (researcher / analyst / reporter)。
A. 全部共享 — 每个 agent tools=[search, exec, db]。简单但 agent 容易"逛工具" — researcher 也调 code_executor 写代码，违背角色分工。B. 按角色配 — researcher=[search]，analyst=[exec, db]，reporter=[]（纯综合）。职责更清晰，错误更可定位 。
CrewAI 官方推荐 B （write once, use everywhere — tool 定义可复用；但每个 agent 只绑定其角色匹配的工具） [docs.crewai.com/en/concepts/tools]
如果发现 agent 跨工具滥用 → 收紧工具白名单是最快的 fix
工具定义层面共享（同一个 BaseTool 类），但绑定层面按需
Evidence : [docs.crewai.com/en/concepts/tools, community.crewai.com/t/tool-best-practice-assign-to-agent-or-task/5919]
DC-4: Memory 默认关 vs 全开？ 场景 : 一个客服 crew，多个会话之间是否需要记住用户？
memory=True 默认开 short_term + entity，会自动跑额外 LLM 调用做"记忆 LLM 分析" ，token 翻倍当 memory 不对（错召回、过期信息）→ 调试地狱
单 kickoff 内 的上下文 → 用 task context=[...] 显式传，不用 memory 跨 kickoff 才考虑 memory=True；首选 long_term（SQLite，便宜）真正生产级 + 高频 → 接 Mem0 后端，不要用默认 LanceDB [mem0.ai/blog/crewai-memory-production-setup-with-mem0]
调试期一律 memory=False，不然 trace 难读
红线 : 不要把"agent 没记住 X"当成必须开 memory 的信号。99% 的情况是 task description 没把 X 写清楚。
Evidence : [docs.crewai.com/en/concepts/memory, §4]
DC-5: allow_delegation 开还是关？ 场景 : hierarchical 模式下，是否给 worker agent 也开 allow_delegation=True？
陷阱 : 多个 agent 都能 delegate → delegation ping-pong ，agents 互相传球，token 爆炸 + 超时。已知 GitHub issue [#330 #4783 #2606]。
循环 delegation（A → B → A → B…）
DelegateWorkTool schema 期望 string，新 LLM 传 dict，silent validation 失败 → 重试 [azguards.com delegation ping-pong]max_iter 在 hierarchical 跨 handoff 时不生效，protection 形同虚设
默认 allow_delegation=False 在所有 worker agent 上仅 manager_agent 开 delegation
即使在 hierarchical，链中至少有一个 agent allow_delegation=False
加全局 token / 时间上限（外层包 timeout）
如果一定要复杂 delegation → 用 Flow 显式编排，别让 LLM 决定 delegate 给谁
Evidence : [github.com/crewAIInc/crewAI/issues/330, azguards.com, inkog.io/glossary/crewai-infinite-loop]
6. 反模式与边界 (Anti-Patterns & Boundaries)
6.1 五大反模式 # 反模式 症状 修复 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
6.2 何时不要 用 CrewAI（重要） 场景 替代方案 单 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 事实标准)
6.3 已知工程坑速查表
日志 : Task 内 print() 经常不冒头。用 step_callback 或 verbose=Truetoken 预算 : hierarchical +30~50%；memory=True 再 +1×（记忆 LLM 分析）Pydantic 版本 : CrewAI 与某些 langchain-tools 的 pydantic v1/v2 不兼容时常爆错manager 模型选择 : gpt-4o-mini 不够强，hierarchical 推荐 gpt-4o / Claude SonnetYAML 模板变量 : {topic} 在 kickoff(inputs={"topic": ...}) 时替换，不写在 inputs 里就是字面 "{topic}"
7. 生态对照 (Ecosystem Comparison)
7.1 三大框架定位 框架 一句话定位 第一抽象 哲学 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 当群聊成员
7.2 选择决策树 你的核心需求是什么？
├─ 多角色明确 + 任务可线性串 → CrewAI Sequential
├─ 多角色 + 需要事件驱动分支 → CrewAI Flow（内嵌 Crew）
├─ 状态/循环/中断/恢复/precise control → LangGraph
├─ 多 agent 辩论/谈判/群体决策 → AutoGen
├─ 单 agent + handoff (不需要协作) → OpenAI Swarm / Anthropic
└─ 数据为中心 RAG → LlamaIndex
7.3 CrewAI 独特价值（什么时候首选）
学习曲线最低 — PM/ops 能读懂 role/goal/backstoryYAML 优先 — 提示词与代码分离，非工程人员可改Flow + Crew 混搭 — 既要 LLM agency 又要工程控制时的平衡点生态轻量 — 无 LangChain 依赖，启动快角色叙事 = 团队建模工具 — 在跨职能讨论中比 "node graph" 更易达成共识
7.4 CrewAI 已知短板（要承认的）
生产可靠性 — hierarchical 模式有结构性 bug（OP-4, DC-2, DC-5），LangGraph 在生产部署占优observability — 内置日志薄，必须外接状态管理 — 比 LangGraph 浅；复杂状态用 Flow 也吃力测试范式 — eval 工具链不如 LangSmith 成熟AutoGen 近况 — AutoGen 已进入 maintenance，长期看 LangGraph + CrewAI 是双雄
Appendix A: 最小可工作示例 (Reference snippet) 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)
Sources (核心引用) 