メニュー
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.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/agentsope/SkillAlchemy --skill agentsop-crewaiコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
| 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)"] |
框架口号: "Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly." [github.com/crewAIInc/crewAI]
"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 角色。
Agent (role + goal + backstory) ← 谁
↓ 持有
Task (description + expected_output + agent + context) ← 做什么
↓ 组装
Crew (agents + tasks + process) ← 怎么协作
↓ 选择
Process (sequential | hierarchical) + Flow (event-driven 编排) ← 控制流
CrewAI 的核心假设：LLM 在 role-playing 状态下表现更好。
"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 会显著改变产出质量与风格。
| 维度 | 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/]
CrewAI 从零写成、零 LangChain 依赖，是 João Moura 刻意决定。这带来：
print 不易冒出来 [aaronyuqi.medium.com/first-hand-comparison-of-langgraph-crewai-and-autogen][问] 这个任务是否需要 ≥2 个截然不同的"专业视角"协作？
├─ 否 → 用单 agent + tools，停止使用 CrewAI
└─ 是 → 继续
[问] 流程是否有循环 / 状态依赖 / 人工中断点？
├─ 是 → 转 LangGraph (或 CrewAI Flow + 简化的 Crew)
└─ 否 → 进入 Phase 1
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],
)
配置与代码分离，使用 @CrewBase 装饰器 + config/agents.yaml + config/tasks.yaml，便于非工程人员迭代提示词 [docs.crewai.com YAML Configuration]。
"Analyze the search results for {topic} and identify 3 emerging trends""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]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=[...]。
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"})
CrewAI 内部日志薄。生产前必须：
mlflow.crewai.autolog() 或 Maxim / Langfuse / Datadogstep_callback= 捕获每步 agent action [docs.crewai.com/en/observability/overview]kickoff 设硬上限（外层 timeout + max_rpm）expected_output 契约是否兑现allow_delegation=False、max_iter=10context=[...]；可选 output_pydanticProcess.sequential；只有当任务路由真的需要 LLM 动态判断时才用 Process.hierarchical + 自定义 manager_agent（不要用裸 manager_llm）process= 与（若 hierarchical）一个带详细 backstory 的 manager_agentcontext=[...] 显式传递；只有当真的需要"跨 session 持久"才 memory=True；高级场景考虑 Mem0 后端memory=False 或 memory=Memory(scope=...)mlflow.crewai.autolog() + max_rpm + max_iter 每 agent + 外层 timeout + step_callback@start/@listen 写 Flow，每个 step 内部可 crew.kickoff()场景: writer agent 输出质量差，反复 self-critique，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]
场景: 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 的输出覆盖前面
三条路:
@listen + 条件函数显式路由，每分支调用一个小 Crew 或单 agent。判断规则:
红线: 永远不要把生产路由依赖默认 manager_llm——João Moura 团队也承认这是当前最大坑之一 [github.com/crewAIInc/crewAI/discussions/1220]。
Evidence: [§2.3, community.crewai.com/t/5710, towardsdatascience.com]
场景: 你有 web_search、code_executor、db_query 三个工具，3 个 agent (researcher / analyst / reporter)。
两条路:
tools=[search, exec, db]。简单但 agent 容易"逛工具" — researcher 也调 code_executor 写代码，违背角色分工。判断规则:
Evidence: [docs.crewai.com/en/concepts/tools, community.crewai.com/t/tool-best-practice-assign-to-agent-or-task/5919]
场景: 一个客服 crew，多个会话之间是否需要记住用户？
陷阱:
memory=True 默认开 short_term + entity，会自动跑额外 LLM 调用做"记忆 LLM 分析"，token 翻倍判断规则:
context=[...] 显式传，不用 memorymemory=True；首选 long_term（SQLite，便宜）memory=False，不然 trace 难读红线: 不要把"agent 没记住 X"当成必须开 memory 的信号。99% 的情况是 task description 没把 X 写清楚。
Evidence: [docs.crewai.com/en/concepts/memory, §4]
场景: hierarchical 模式下，是否给 worker agent 也开 allow_delegation=True？
陷阱: 多个 agent 都能 delegate → delegation ping-pong，agents 互相传球，token 爆炸 + 超时。已知 GitHub issue [#330 #4783 #2606]。
根因:
DelegateWorkTool schema 期望 string，新 LLM 传 dict，silent validation 失败 → 重试 [azguards.com delegation ping-pong]max_iter 在 hierarchical 跨 handoff 时不生效，protection 形同虚设判断规则:
allow_delegation=False 在所有 worker agent 上allow_delegation=FalseEvidence: [github.com/crewAIInc/crewAI/issues/330, azguards.com, inkog.io/glossary/crewai-infinite-loop]
| # | 反模式 | 症状 | 修复 |
|---|---|---|---|
| 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 |
| 场景 | 替代方案 |
|---|---|
| 单 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 事实标准) |
print() 经常不冒头。用 step_callback 或 verbose=True{topic} 在 kickoff(inputs={"topic": ...}) 时替换，不写在 inputs 里就是字面 "{topic}"| 框架 | 一句话定位 | 第一抽象 | 哲学 |
|---|---|---|---|
| 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 当群聊成员 |
你的核心需求是什么？
├─ 多角色明确 + 任务可线性串 → CrewAI Sequential
├─ 多角色 + 需要事件驱动分支 → CrewAI Flow（内嵌 Crew）
├─ 状态/循环/中断/恢复/precise control → LangGraph
├─ 多 agent 辩论/谈判/群体决策 → AutoGen
├─ 单 agent + handoff (不需要协作) → OpenAI Swarm / Anthropic
└─ 数据为中心 RAG → LlamaIndex
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)
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.
SOC 職業分類に基づく