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.
agentsope · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add agentsope/SkillAlchemy --skill agentsop-crewaiAbout this skill
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
| 维度 | 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/]
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", # ← 含 {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],
)
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(
descripti
Read the complete source ↗