agentsop-agent-topology-selection

name	agentsop-agent-topology-selection
version	0.1.0
description	Cross-framework enhancement overlay for choosing a multi-agent topology BEFORE writing any agent. A binary-question rubric — is single-agent + tools enough? do agents need to know about each other? does the output need one voice? — maps the answer to single-agent / supervisor / swarm / sequential / hierarchical. Activates when a coder agent is tempted to "split the work into roles" or reaches for a multi-agent framework. Encodes the *selection rubric* that the per-framework skills assume but never surface. Search keywords: when to use multi-agent, single vs multi agent, do I need multiple agents, supervisor vs swarm, multi-agent vs single agent, agent team design.
overlay	true
cross_links	["crewai","langgraph","bounded-loop"]

Multi-Agent Topology Selection · SOP (ENHANCE overlay)

Overlay posture: this skill decides whether and which topology. It does not teach the API — descend to [[crewai]] or [[agentsop-langgraph]] for that. Every load-bearing claim carries an inline source tag resolving in references/R1-source-evidence.md.

---

1. 何时激活 (When to Activate)

Activate when any of the following fire:

• The task description contains "team of agents", "researcher + writer + reviewer", "manager agent", "agents that hand off", "split this into roles", or "multi-agent".
• A coder agent is about to instantiate ≥2 agents (CrewAI Agent(...) × N, LangGraph supervisor/swarm, OpenAI Swarm handoffs) and has not yet justified why a single agent with tools is insufficient.
• Someone is choosing between CrewAI Process.sequential vs Process.hierarchical, or LangGraph supervisor vs swarm vs hierarchical-teams, and wants the rubric, not the syntax.
• A multi-agent system is over budget on tokens/latency and the question is "can we collapse agents back into one?".

Do not activate for: a single LLM call, a one-shot RAG query, or a fixed tool-call pipeline with no role separation. Those are the single-agent baseline this skill defends.

Mental check: "An agent needs agency, otherwise it's just another script." — João Moura, CrewAI founder [[crewai · §1.3]]. If you can write the control flow in if/else, you do not need multiple agents — you need one agent (or a graph) with explicit edges.

---

2. 核心心智模型 (Core Mental Model)

Most "multi-agent" problems are single-agent + tools. Add agents only when context isolation or parallel expertise genuinely demands it.

"Single-agent is right for approximately 80% of cases; the trap is reaching for multi-agent because it sounds more capable." [[crewai · DC-1]]

Two — and only two — forces justify a second agent:

1. Context isolation. One agent's working context would pollute another's (a critic that must not see its own draft's rationalisations; a tool-heavy sub-task whose 40 intermediate tool calls should not bloat the main thread). Splitting gives each agent a clean, bounded prompt.
2. Parallel expertise. Two genuinely different skills run concurrently or in strict sequence (research → write → review), where a single prompt provably cannot hold both jobs without quality collapse [[crewai · DC-1]].

If neither force is present, a single agent with the union of tools wins — fewer hops, fewer tokens, no handoff failures. This is the baseline the rubric must beat, not the default to escape.

The selection rubric (three binary questions)

Q0  Is single-agent + tools enough?
      (no context-isolation need, no parallel-expertise need)
        YES → single-agent + tools. STOP. Do not add agents.
        NO  → ↓

Q1  Do the agents need to KNOW ABOUT EACH OTHER (peer handoff)?
        NO  → one funnels through a coordinator → SUPERVISOR
              (or static order → SEQUENTIAL, if order is fixed)
        YES → ↓

Q2  Must the OUTPUT speak with ONE VOICE / single audit funnel?
        YES → SUPERVISOR (single user-facing persona, one funnel)
        NO  → SWARM (dynamic peer handoff, last-active agent remembered)

Scaling override: ≥6 specialists that group into teams → HIERARCHICAL
(supervisor-of-supervisors). Use only for grouping, not for routing.

The two questions that actually separate the patterns: (a) can sub-agents know each other, (b) is one user-facing voice mandated. Everything else is tuning [[langgraph · Case 2]].

---

3. SOP 工作流 (Selection Protocol)

Walk top-down. Each gate can send you back down the ladder — collapsing agents is as valid an answer as adding them.

Step 1 · Defend the single-agent baseline first

Ask Q0. Enumerate the would-be roles. For each, ask: would merging it into one agent's prompt + toolset actually degrade output? If you cannot point to a concrete failure mode (style drift, missed checklist, context bloat, parallel latency), the honest answer is single-agent + tools. Exit here ~80% of the time [[crewai · DC-1]].

Step 2 · If splitting, decide static vs dynamic routing

• Order is fixed and known at design time (research always precedes write precedes review) → SEQUENTIAL. Cheapest, most debuggable, 1× token baseline [[crewai · §2.3]]. In CrewAI this is Process.sequential; in LangGraph it is static edges A→B→C.
• Routing must be decided at runtime (which specialist handles this query) → you need a coordinator or peer handoff → continue to Step 3.

Step 3 · Coordinator (supervisor) vs peers (swarm)

Ask Q1 then Q2.

• Agents that do not know each other and funnel through one router → SUPERVISOR. Sub-agents are effectively tools the supervisor calls; the supervisor "translates" their output back to the user — which is exactly why it costs the most tokens [[langgraph · Step 4]].
• Agents that do know each other and no single voice is mandated → SWARM. Dynamic handoff, last-active agent stays active across turns, no translation step → fewer tokens, slightly higher accuracy on the τ-bench retest [[langgraph · §SOP Step 4]].

Step 4 · Apply the supervisor-default caveat (read this twice)

LangChain's own benchmark found swarm "slightly outperformed supervisor across all scenarios" and supervisor "consistently uses more tokens than swarm" — yet they still ship supervisor as the recommended default [[langgraph · Step 4]]. Why the nuance matters:

• Supervisor is the safest with third-party / untrusted agents (single funnel, single audit log, single place to enforce policy) [[langgraph · Step 4]].
• Swarm is a bad fit for third-party agents — peers handing off to peers means no central control point [[langgraph · Step 4]].
• So: do not copy "default = supervisor" blindly. If your agents are internal and trusted, swarm is often the better pick the default hides. Pick on the two questions, not on the framework's default.

Step 5 · Verify the chosen topology can terminate

Any topology with runtime handoff (swarm, hierarchical, CrewAI delegation) can loop. Bound it before shipping — cross-link [[agentsop-bounded-loop]]. Concretely: default allow_delegation=False on workers, set per-agent max_iter, wrap an outer timeout, and bake an explicit exit counter into state rather than trusting the LLM to stop [[crewai · DC-5]] [[agentsop-bounded-loop]].

Step 6 · Reconsider before scaling agents up

≥6 specialists → group into HIERARCHICAL teams purely for navigability, not to get free routing (see Anti-patterns). At >5 agents CrewAI starts hitting coordination failure [[crewai · §6.1]]; that is a signal to group or collapse, not to add more.

---

4. 操作模型 (Operation Models)

Format: Trigger → Action → Output → Evidence.

OP-1 · Defend the single-agent baseline

• Trigger: a task is being described as "a team of agents".
• Action: list the proposed roles; for each, name the concrete failure that merging into one agent would cause (style drift / missed checklist / context bloat / required parallelism). No nameable failure ⇒ single agent.
• Output: single-agent + tools, OR a justified list of must-split roles.
• Evidence: [[crewai · DC-1]] "single-agent right for ~80% of cases".

OP-2 · Single-vs-multi gate

• Trigger: baseline defended and at least one role has a real split-justifying failure mode.
• Action: confirm the force is context isolation or parallel expertise — not "it sounds more capable". If only the latter, stay single.
• Output: a yes/no on multi-agent with the force named in one sentence.
• Evidence: [[crewai · §2.2]], [[crewai · DC-1]].

OP-3 · Static-order gate (→ sequential)

• Trigger: multi-agent confirmed; the order of work is fixed at design time.
• Action: choose SEQUENTIAL — list agents in execution order; pass dependencies explicitly (CrewAI context=[...]), do not rely on implicit transfer.
• Output: an ordered task list; CrewAI Process.sequential or LangGraph static edges.
• Evidence: [[crewai · §2.3]] (sequential = 1× tokens, low debug cost).

OP-4 · Peer-awareness gate (Q1 → supervisor vs swarm branch)

• Trigger: routing must be decided at runtime.
• Action: ask "do sub-agents know about each other?" — NO ⇒ supervisor branch; YES ⇒ continue to OP-5.
• Output: chosen branch.
• Evidence: [[langgraph · Step 4]] decision tree.

OP-5 · Single-voice gate (Q2 → supervisor vs swarm)

• Trigger: peers know each other (Q1=YES).
• Action: ask "must output be one voice / single audit funnel?" — YES ⇒ SUPERVISOR; NO ⇒ SWARM.
• Output: SUPERVISOR or SWARM.
• Evidence: [[langgraph · Case 2]] (compliance ⇒ supervisor; UX continuity ⇒ swarm).

OP-6 · Apply the supervisor-default caveat

• Trigger: supervisor was selected, OR you are about to accept a framework default.
• Action: check trust. Third-party/untrusted agents ⇒ supervisor is correct. Internal/trusted ⇒ re-test whether swarm's lower token cost wins; if so, switch.
• Output: a topology chosen on trust + the two questions, not on the default.
• Evidence: [[langgraph · Step 4]] — swarm beats supervisor on bench, yet supervisor remains the shipped default for third-party safety.

OP-7 · Tune-before-switch

• Trigger: chosen topology is over token/latency budget.
• Action: before changing paradigm, apply the published fixes to the current one. For supervisor: remove handoff messages, add a forwarding-messages tool, optimise tool naming — LangChain measured "nearly 50% increase in performance" [[langgraph · Step 4]]. Switch paradigm only if still over budget.
• Output: a tuned topology or a justified migration.
• Evidence: [[langgraph · Case 2]].

OP-8 · Bound the topology

• Trigger: any runtime-handoff topology before ship.
• Action: allow_delegation=False on workers, per-agent max_iter, outer timeout, explicit state-based exit counter.
• Output: a topology that provably terminates.
• Evidence: [[crewai · DC-5]] (delegation ping-pong), [[agentsop-bounded-loop]].

---

5. 困境决策案例 (Dilemma Cases)

Case 1 · "Swarm beats supervisor on the benchmark — why ship supervisor?"

• 困境: LangChain's own multi-agent benchmark shows swarm "slightly outperformed supervisor across all scenarios" and supervisor "consistently uses more tokens" (the telephone-game translation overhead). Yet LangChain's recommended default is still supervisor [[langgraph · Step 4]]. A coder agent copying the default would leave accuracy and tokens on the table.
• 约束:
  • Want the benchmark's efficiency (swarm).
  • But may integrate third-party / untrusted agents later.
  • Need a single auditable funnel for tool calls (compliance).
• 决策步骤:
  1. Read the default's reason, not the default. Supervisor wins on safety with third-party agents and single audit funnel — not on accuracy [[langgraph · Step 4]].
  2. If all agents are internal and trusted and no single-voice mandate → pick swarm; the default does not apply to you.
  3. If a single auditable funnel is mandated → keep supervisor, then apply the three fixes (remove handoff messages, forwarding-messages tool, tool-name tuning) for the measured ~50% bump before concluding it is too slow [[langgraph · Case 2]].
  4. Re-measure tokens; migrate to swarm only if still over budget and audit is tolerant.
• 结果: Topology chosen on trust + the two questions. The benchmark's "swarm > supervisor" is true and the supervisor default is rational — for a different constraint (third-party safety) than the one the benchmark measured (accuracy/cost).
• 可提取的操作: OP-6. A framework default encodes the framework author's worst-case constraint, not yours. Decode the reason; re-derive for your case.

Case 2 · "CrewAI hierarchical for simple routing is structurally broken"

• 困境: 5 agents, order roughly fixed, but the system should route — skip irrelevant specialists based on the query. Process.hierarchical looks like it "should auto-route". In practice the manager executes all tasks and the last task's output overwrites the rest — it does not skip on triage [[crewai · DC-2]].

  Query: "Why is my laptop overheating?" (pure technical)
  Expected:  triage → technical_agent → done
  Hierarchical reality: triage → technical → billing → … → last output wins
  

• 约束: routing is required; default manager_llm is unreliable; latency/cost matter.
• 决策步骤:
  1. Recognise hierarchical-for-routing is the wrong tool: CrewAI hierarchical is a coordination topology, not a router [[crewai · DC-2]].
  2. If routing logic fits in ~5 lines of Python → use a CrewAI Flow (@router / @listen) or a LangGraph conditional edge — explicit branch, then call one small crew / single agent per branch [[crewai · DC-2]].
  3. If routing genuinely needs LLM semantic judgement → hierarchical with a custom manager_agent carrying an explicit branching backstory — never the bare default manager_llm [[crewai · OP-4]].
  4. Bound it: workers allow_delegation=False, outer timeout [[agentsop-bounded-loop]].
• 结果: Routing handled by explicit control flow; hierarchical reserved for true coordination of trusted teams, never for if/else routing.
• 可提取的操作: Hierarchical ≠ router. Routing is control flow — make it explicit (Flow / conditional edge), don't delegate it to a manager LLM that will run everything. Compare with d-query-routing-skill for the routing-specific rubric.

---

6. 反模式与边界 (Anti-patterns & Boundaries)

• Multi-agent theater. Splitting into roles because it "sounds more capable" with no context-isolation or parallel-expertise force. Symptom: agents that just pass a string along, each adding a paragraph. Fix: collapse to one agent + tools [[crewai · DC-1]].
• Hierarchical for simple routing. Using Process.hierarchical (or a supervisor) to get free if/else routing. It runs everything; routing must be explicit control flow (Flow / conditional edge) [[crewai · DC-2]].
• Copying the supervisor default blindly. The benchmark says swarm is better on accuracy and tokens; supervisor is the default for third-party safety. Internal trusted agents should reconsider swarm [[langgraph · Step 4]].
• Agent-count explosion (>5). Coordination failure, token blow-up, debug pain. ≥6 ⇒ group into hierarchical teams for navigability, or merge near-duplicate roles [[crewai · §6.1]].
• Unbounded delegation. allow_delegation=True on every agent ⇒ ping-pong loops. Default off on workers; bound with max_iter + timeout [[crewai · DC-5]], [[agentsop-bounded-loop]].
• Picking on aesthetics. Choosing supervisor/swarm/sequential by which "feels cleaner" instead of the two binary questions (peer-awareness, single-voice) [[langgraph · Case 2]].

Hard boundaries (this rubric does NOT decide):

• Which framework — see [[crewai]] vs [[agentsop-langgraph]] ecosystem sections.
• Routing by query kind — that is d-query-routing-skill.
• Bounding the loop — that is [[agentsop-bounded-loop]].
• Latency < 200ms / single LLM call — no multi-agent framework at all [[langgraph · 反模式]].

---

7. 跨框架对照 (Cross-Framework Mapping)

Topology	CrewAI	LangGraph	OpenAI Swarm	Choose when
Single-agent + tools	one Agent + tools (skip Crew)	create_react_agent	one routine	Q0=YES — ~80% of cases [[crewai · DC-1]]
Sequential	Process.sequential + context=[...]	static edges A→B→C	linear handoffs	order fixed at design time [[crewai · §2.3]]
Supervisor	Process.hierarchical + custom manager_agent	supervisor pattern (sub-agents as tools)	central routine dispatching	peers don't know each other; one voice / third-party safety [[langgraph · Step 4]]
Swarm	(no native; Flow + handoff funcs)	swarm pattern (dynamic handoff)	handoff between agents	peers know each other; no single-voice mandate; internal/trusted [[langgraph · Step 4]]
Hierarchical teams	nested crews via Flow	supervisor-of-supervisors / subgraphs	n/a	≥6 specialists needing grouping [[crewai · §6.1]]

Notes:

• CrewAI frames agents as role-playing teammates; hierarchical is coordination, not routing — the default manager_llm runs all tasks [[crewai · DC-2]].
• LangGraph frames topology as routing logic over typed state; supervisor is the shipped default for third-party safety despite swarm winning the bench [[langgraph · Step 4, Case 2]].
• OpenAI Swarm is the minimal handoff baseline — OpenAI labels it experimental; use as reference, not production [[langgraph · 生态对照]].
• Single-agent + tools is the baseline every topology above must beat. Defend it first (OP-1).

Pick the smallest topology that fits the two questions; promote upward only when a named force demands it, and collapse back down when the force disappears.

---

附录: 引用 (Citations)

Inline tags resolve to source-skill sections in references/R1-source-evidence.md:

• [[crewai]] = /Users/5imp1ex/Desktop/Skill-Workplace/output/crewai-sop-skill/SKILL.md
• [[agentsop-langgraph]] = /Users/5imp1ex/Desktop/Skill-Workplace/output/langgraph-sop-skill/SKILL.md
• The benchmark: LangChain, Benchmarking Multi-Agent Architectures (www.langchain.com/blog/benchmarking-multi-agent-architectures), surfaced via [[langgraph · Step 4 / Case 2]].