跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add agentsope/SkillAlchemy --skill 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

维度SequentialHierarchicalFlow
任务路由静态列表顺序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
阅读完整来源 ↗