/agentsop-crewai

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