agentsop-crewai

# 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) ```python 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 显式声明依赖 ```python 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 ```python 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"}) ``` ### Phase 4: 观测与收敛 #### 4.1 必装观测 CrewAI 内部日志薄。**生产前必须**： - 接 `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=10` - **Output**: 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_pydantic` - **Output**: 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_agent - **Evidence**: [§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_callback - **Output**: 可观测、可中止的 Crew - **Evidence**: [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 BaseModel - **Evidence**: [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%。 **判断规则**: 1. 看失败案例：失败模式是否**风格不一致**？ → 改 backstory 2. 失败模式是否**遗漏检查项**（事实错误、格式错误）？ → **拆 agent**，让 reviewer 用结构化 checklist 3. 如果 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。 **判断规则**: 1. 路由逻辑可以**用 5 行 Python 表达**？ → 用 **Flow** (D) 2. 路由真的需要 LLM 语义理解（不能写规则）→ Hierarchical + **自定义 manager**（C），**永远不要**靠默认 manager_llm 3. 不确定 → 先 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 不对（错召回、过期信息）→ 调试地狱 **判断规则**: 1. **单 kickoff 内**的上下文 → 用 task `context=[...]` 显式传，**不用 memory** 2. **跨 kickoff** 才考虑 `memory=True`；首选 long_term（SQLite，便宜） 3. 真正生产级 + 高频 → 接 Mem0 后端，**不要用默认 LanceDB** [mem0.ai/blog/crewai-memory-production-setup-with-mem0] 4. 调试期一律 `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`？