Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Multi-Agent Topology Selection · SOP (ENHANCE overlay) · agentsope | DecimalAI

Agent Toolingby agentsope

Multi-Agent Topology Selection · SOP (ENHANCE overlay)

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 nev

Never made a case worseMaintained

SkillScore

SkillScore86/100

Test results 86

Safety

3/3 safety checks passed

Code scan
Intent
Content

What it changes

41%86%of test cases passed +45 pts

Without skill9 of 22

With skill19 of 22

10 fixed9 passed either way3 still failing0 broke

Measured on gemini-3.6-flash8/24/2026v121 comparable

Track record

Agent runs: 0; All time

See one task, with and without the skill

One test taskWalk through the topology selection decision questions for a customer support application where agents must dynamically hand off tickets to each other based on conversation details, and the customer expects a continuous dialogue with whichever agent currently holds the ticket.

Without the skillMissed

With the skillPassed

Same model, same task. Answers are capped and redacted.

Use this skill

Your agent runs on

Adds every file the skill has, pinned so you can update it. No account needed.

pip install "decimalai>=0.15"
decimalai skills add agentsope-agentsop-agent-topology-selection
claude --plugin-dir "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents"

The same install from Python, for a notebook or a setup script.

Install

pip install "decimalai>=0.15"

Add the skill

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

print("Added. Start Claude Code with the command below.")

Start Claude Code with it

claude --plugin-dir "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents"

Type these in a Claude Code session. No account or API key. It writes the skill and any files it bundles, and asks first when its safety rating isn't Passed.

Add the DecimalAI plugin, once

/plugin marketplace add decimal-labs/decimalai-claude-plugins
/plugin install decimalai@decimalai

Install this skill

/decimalai:install agentsope-agentsop-agent-topology-selection

The plugin needs python3 and curl on your machine.

No Python or account. Claude Code picks it up in its next session.

Save it into your project

curl -fsSL --create-dirs -o .claude/skills/agentsope-agentsop-agent-topology-selection/SKILL.md https://app.decimal.ai/s/agentsope-agentsop-agent-topology-selection/SKILL.md

Copy SKILL.md

Save it in your project, as

.claude/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Claude Code docs

agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.

Install

pip install "decimalai[claude-agent-sdk]"
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

import asyncio

from claude_agent_sdk import ClaudeAgentOptions
from decimalai.claude_agent_sdk import agent_config

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

async def main():
    question = "Hello!"
    async with support.run(question) as run:  # one user message, one run
        async for message in run.query(options=ClaudeAgentOptions(max_turns=6)):
            print(message)

# In a notebook or async code: await main()
asyncio.run(main())

Prefer its own loader? ClaudeAgentOptions(plugins=[skills_plugin()], skills="all") reads the same folder. Use one or the other: a skill delivered both ways reaches the prompt twice.

The same install from Python, for a notebook or a setup script. agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.

Install

pip install "decimalai[claude-agent-sdk]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

import asyncio

from claude_agent_sdk import ClaudeAgentOptions
from decimalai.claude_agent_sdk import agent_config

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

async def main():
    question = "Hello!"
    async with support.run(question) as run:  # one user message, one run
        async for message in run.query(options=ClaudeAgentOptions(max_turns=6)):
            print(message)

# In a notebook or async code: await main()
asyncio.run(main())

Prefer its own loader? ClaudeAgentOptions(plugins=[skills_plugin()], skills="all") reads the same folder. Use one or the other: a skill delivered both ways reaches the prompt twice.

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

import asyncio
from pathlib import Path
from claude_agent_sdk import ClaudeAgentOptions, query

skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
options = ClaudeAgentOptions(system_prompt=f"You are a helpful agent.\n\n{skill}", max_turns=6)

async def main():
    async for message in query(prompt="Hello!", options=options):
        print(message)

# In a notebook or async code: await main()
asyncio.run(main())

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Claude Agent SDK docs

agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.

Install

pip install "decimalai[openai-agents]"
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

from agents import Agent, Runner
from decimalai.openai_agents import agent_config

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

agent = Agent(
    name=support.name,
    instructions=support.instructions,  # your prompt, then the skill list
    tools=[*support.tools],             # your tools, then load_skill
)
# In a notebook or async code: result = await Runner.run(agent, "Hello!")
result = Runner.run_sync(agent, "Hello!")

Using SandboxAgent? capabilities=[Shell(), decimalai.openai_agents.sandbox_skills()] points its own loader at the same folder.

Install

pip install "decimalai[openai-agents]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

from agents import Agent, Runner
from decimalai.openai_agents import agent_config

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

agent = Agent(
    name=support.name,
    instructions=support.instructions,  # your prompt, then the skill list
    tools=[*support.tools],             # your tools, then load_skill
)
# In a notebook or async code: result = await Runner.run(agent, "Hello!")
result = Runner.run_sync(agent, "Hello!")

Using SandboxAgent? capabilities=[Shell(), decimalai.openai_agents.sandbox_skills()] points its own loader at the same folder.

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
from agents import Agent, Runner

skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
agent = Agent(name="support", instructions=f"You are a helpful agent.\n\n{skill}")
# In a notebook or async code: result = await Runner.run(agent, "Hello!")
result = Runner.run_sync(agent, "Hello!")

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

OpenAI Agents docs

agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.

Install

pip install "decimalai[openai]"
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

import json

from openai import OpenAI
from decimalai.openai import agent_config

client = OpenAI()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")


def lookup_order(order_id: str) -> str:
    return f"Order {order_id} shipped yesterday."


# Your tools, as Chat Completions takes them, and what answers each.
TOOLS = [{"type": "function", "function": {
    "name": "lookup_order",
    "description": "Look up the status of an order.",
    "parameters": {"type": "object", "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]},
}}]
FUNCTIONS = {"lookup_order": lookup_order}

question = "Where is order A1001?"
with support.run(question) as run:  # one user message, one run
    # run.system is your prompt, then the skill list.
    messages = [{"role": "system", "content": run.system}, run.message]
    while True:
        reply = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=messages,
            tools=[*TOOLS, *run.tools],  # your tools, then load_skill
        ).choices[0].message
        messages.append(reply)
        if not reply.tool_calls:
            break
        for call in reply.tool_calls:
            # load_skill is answered by the run; your own tools by FUNCTIONS.
            function = FUNCTIONS.get(call.function.name)
            messages.append(run.tool_result(call) or {
                "role": "tool", "tool_call_id": call.id,
                "content": function(**json.loads(call.function.arguments)) if function
                else f"There is no tool named {call.function.name!r}.",
            })
print(reply.content)

# The Responses API takes run.response_tools instead of run.tools.

Install

pip install "decimalai[openai]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

import json

from openai import OpenAI
from decimalai.openai import agent_config

client = OpenAI()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")


def lookup_order(order_id: str) -> str:
    return f"Order {order_id} shipped yesterday."


# Your tools, as Chat Completions takes them, and what answers each.
TOOLS = [{"type": "function", "function": {
    "name": "lookup_order",
    "description": "Look up the status of an order.",
    "parameters": {"type": "object", "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]},
}}]
FUNCTIONS = {"lookup_order": lookup_order}

question = "Where is order A1001?"
with support.run(question) as run:  # one user message, one run
    # run.system is your prompt, then the skill list.
    messages = [{"role": "system", "content": run.system}, run.message]
    while True:
        reply = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=messages,
            tools=[*TOOLS, *run.tools],  # your tools, then load_skill
        ).choices[0].message
        messages.append(reply)
        if not reply.tool_calls:
            break
        for call in reply.tool_calls:
            # load_skill is answered by the run; your own tools by FUNCTIONS.
            function = FUNCTIONS.get(call.function.name)
            messages.append(run.tool_result(call) or {
                "role": "tool", "tool_call_id": call.id,
                "content": function(**json.loads(call.function.arguments)) if function
                else f"There is no tool named {call.function.name!r}.",
            })
print(reply.content)

# The Responses API takes run.response_tools instead of run.tools.

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
from openai import OpenAI

client = OpenAI()
skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
reply = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[
        {"role": "system", "content": f"You are a helpful agent.\n\n{skill}"},
        {"role": "user", "content": "Hello!"},
    ],
).choices[0].message

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

OpenAI SDK docs

agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.

Install

pip install "decimalai[anthropic]"
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

import anthropic
from decimalai.anthropic import agent_config

client = anthropic.Anthropic()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

question = "Hello!"
with support.run(question) as run:  # one user message, one run
    answer = client.beta.messages.tool_runner(
        model="claude-haiku-5-5",
        max_tokens=4096,
        system=run.system,     # your prompt, then the skill list
        tools=[*run.tools],    # your tools, then load_skill
        messages=[{"role": "user", "content": question}],
    ).until_done()

Install

pip install "decimalai[anthropic]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

import anthropic
from decimalai.anthropic import agent_config

client = anthropic.Anthropic()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

question = "Hello!"
with support.run(question) as run:  # one user message, one run
    answer = client.beta.messages.tool_runner(
        model="claude-haiku-5-5",
        max_tokens=4096,
        system=run.system,     # your prompt, then the skill list
        tools=[*run.tools],    # your tools, then load_skill
        messages=[{"role": "user", "content": question}],
    ).until_done()

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
import anthropic

client = anthropic.Anthropic()
skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
reply = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=4096,
    system=f"You are a helpful agent.\n\n{skill}",
    messages=[{"role": "user", "content": "Hello!"}],
)

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Anthropic docs

agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.

Install

pip install "decimalai[google-genai]"
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

from google import genai
from google.genai import types
from decimalai.google_genai import agent_config

client = genai.Client()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")


def lookup_order(order_id: str) -> str:
    return f"Order {order_id} shipped yesterday."


# Your functions, as declarations for the model, and what answers each.
TOOLS = [{"function_declarations": [{
    "name": "lookup_order",
    "description": "Look up the status of an order.",
    "parameters_json_schema": {"type": "object", "properties": {"order_id": {"type": "string"}},
                               "required": ["order_id"]},
}]}]
FUNCTIONS = {"lookup_order": lookup_order}

question = "Where is order A1001?"
with support.run(question) as run:  # one user message, one run
    config = types.GenerateContentConfig(
        system_instruction=run.system,     # your prompt, then the skill list
        tools=[*TOOLS, *run.tool_params],  # your functions, then load_skill
    )
    contents = [{"role": "user", "parts": [{"text": run.message}]}]
    while True:
        response = client.models.generate_content(
            model="gemini-3.5-flash", contents=contents, config=config,
        )
        if not response.function_calls:
            break
        contents.append(response.candidates[0].content)
        parts = []
        for call in response.function_calls:
            # load_skill is answered by the run; your own functions by FUNCTIONS.
            # A loop of your own rather than automatic function calling, which
            # raises KeyError when the model asks for a function you did not pass.
            function = FUNCTIONS.get(call.name)
            parts.append(run.tool_result(call) or {"function_response": {
                "name": call.name, "id": call.id,
                "response": {"result": function(**(call.args or {})) if function
                             else f"There is no function named {call.name!r}."},
            }})
        contents.append({"role": "user", "parts": parts})
print(response.text)

Install

pip install "decimalai[google-genai]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

from google import genai
from google.genai import types
from decimalai.google_genai import agent_config

client = genai.Client()
# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")


def lookup_order(order_id: str) -> str:
    return f"Order {order_id} shipped yesterday."


# Your functions, as declarations for the model, and what answers each.
TOOLS = [{"function_declarations": [{
    "name": "lookup_order",
    "description": "Look up the status of an order.",
    "parameters_json_schema": {"type": "object", "properties": {"order_id": {"type": "string"}},
                               "required": ["order_id"]},
}]}]
FUNCTIONS = {"lookup_order": lookup_order}

question = "Where is order A1001?"
with support.run(question) as run:  # one user message, one run
    config = types.GenerateContentConfig(
        system_instruction=run.system,     # your prompt, then the skill list
        tools=[*TOOLS, *run.tool_params],  # your functions, then load_skill
    )
    contents = [{"role": "user", "parts": [{"text": run.message}]}]
    while True:
        response = client.models.generate_content(
            model="gemini-3.5-flash", contents=contents, config=config,
        )
        if not response.function_calls:
            break
        contents.append(response.candidates[0].content)
        parts = []
        for call in response.function_calls:
            # load_skill is answered by the run; your own functions by FUNCTIONS.
            # A loop of your own rather than automatic function calling, which
            # raises KeyError when the model asks for a function you did not pass.
            function = FUNCTIONS.get(call.name)
            parts.append(run.tool_result(call) or {"function_response": {
                "name": call.name, "id": call.id,
                "response": {"result": function(**(call.args or {})) if function
                             else f"There is no function named {call.name!r}."},
            }})
        contents.append({"role": "user", "parts": parts})
print(response.text)

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Hello!",
    config=types.GenerateContentConfig(system_instruction=f"You are a helpful agent.\n\n{skill}"),
)

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Gemini API docs

agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.

Install

pip install "decimalai[langchain]" langchain-openai
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

from langchain.agents import create_agent
from decimalai.langchain import agent_config

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

agent = create_agent(
    "openai:gpt-5.4-mini",
    tools=[],                         # your tools; the middleware adds load_skill
    middleware=[support.middleware],  # your prompt, the skill list and load_skill
)
result = agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})

Install

pip install "decimalai[langchain]" langchain-openai

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

from langchain.agents import create_agent
from decimalai.langchain import agent_config

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

agent = create_agent(
    "openai:gpt-5.4-mini",
    tools=[],                         # your tools; the middleware adds load_skill
    middleware=[support.middleware],  # your prompt, the skill list and load_skill
)
result = agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
from langchain.agents import create_agent

skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
agent = create_agent("openai:gpt-5.4-mini", tools=[], system_prompt=f"You are a helpful agent.\n\n{skill}")
result = agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

LangChain docs

CrewAI's own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" "crewai>=1.15.27"
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

import decimalai.crewai
from crewai import Agent, Crew, Task

agent = Agent(
    role="Support", goal="Help the customer", backstory="A support agent.",
    llm=llm,                               # your own CrewAI LLM
    skills=decimalai.crewai.skills(),      # the installed folder
    tools=decimalai.crewai.skill_tools(),  # reads a skill's files, runs its scripts
)
task = Task(description="Hello!", expected_output="an answer", agent=agent)
Crew(agents=[agent], tasks=[task]).kickoff()

The same install from Python, for a notebook or a setup script. CrewAI's own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" "crewai>=1.15.27"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

import decimalai.crewai
from crewai import Agent, Crew, Task

agent = Agent(
    role="Support", goal="Help the customer", backstory="A support agent.",
    llm=llm,                               # your own CrewAI LLM
    skills=decimalai.crewai.skills(),      # the installed folder
    tools=decimalai.crewai.skill_tools(),  # reads a skill's files, runs its scripts
)
task = Task(description="Hello!", expected_output="an answer", agent=agent)
Crew(agents=[agent], tasks=[task]).kickoff()

No DecimalAI package. CrewAI's own loader reads the folder, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
from crewai import Agent, Crew, Task

agent = Agent(
    role="Support", goal="Help the customer", backstory="A support agent.",
    llm=llm,                         # your own CrewAI LLM
    skills=[Path(".agents/skills")],
)
task = Task(description="Hello!", expected_output="an answer", agent=agent)
Crew(agents=[agent], tasks=[task]).kickoff()

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

CrewAI docs

agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.

Install

pip install "decimalai[adk]"
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

from decimalai.adk import DecimalAIPlugin, agent_config
from google.adk.agents import LlmAgent
from google.adk.apps import App

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

agent = LlmAgent(
    name="support",          # ADK needs a Python identifier
    model="gemini-3.5-flash",
    instruction=support.instruction,  # your prompt, then the skill list
    tools=[*support.tools],           # your tools, then load_skill
)
# DecimalAIPlugin makes each invocation of runners built from this App one trace.
app = App(name="support", root_agent=agent, plugins=[DecimalAIPlugin()])

Prefer ADK's own loader? SkillToolset(skills=decimalai.adk.skills(), ...) reads the same folder. Use one or the other: a skill delivered both ways reaches the prompt twice.

Install

pip install "decimalai[adk]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

from decimalai.adk import DecimalAIPlugin, agent_config
from google.adk.agents import LlmAgent
from google.adk.apps import App

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

agent = LlmAgent(
    name="support",          # ADK needs a Python identifier
    model="gemini-3.5-flash",
    instruction=support.instruction,  # your prompt, then the skill list
    tools=[*support.tools],           # your tools, then load_skill
)
# DecimalAIPlugin makes each invocation of runners built from this App one trace.
app = App(name="support", root_agent=agent, plugins=[DecimalAIPlugin()])

Prefer ADK's own loader? SkillToolset(skills=decimalai.adk.skills(), ...) reads the same folder. Use one or the other: a skill delivered both ways reaches the prompt twice.

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
from google.adk.agents import LlmAgent

skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
agent = LlmAgent(
    name="support",
    model="gemini-3.5-flash",
    instruction=lambda context: f"You are a helpful agent.\n\n{skill}",
)

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Google ADK docs

agent_config() hands your agent the skill. With no DecimalAI key it reads your project's files and sends nothing. Needs SDK 0.27 or newer.

Install

pip install "decimalai[pydantic-ai]"
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

from pydantic_ai import Agent
from decimalai.pydantic_ai import agent_config

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

agent = Agent(
    "openai:gpt-4o-mini",
    name=support.name,
    tools=[],                 # your tools; the capability adds load_skill
    capabilities=[support],   # your prompt, the skill list and load_skill
)
# In a notebook or async code: result = await agent.run("Hello!")
result = agent.run_sync("Hello!")

On the Pydantic AI harness, decimalai.pydantic_ai_harness.skills(project) uses its own loader instead.

Install

pip install "decimalai[pydantic-ai]"

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

from pydantic_ai import Agent
from decimalai.pydantic_ai import agent_config

# With no DECIMAL_API_KEY this reads the skills your project lists, from disk.
support = agent_config("support", fallback="You are a helpful agent.")

agent = Agent(
    "openai:gpt-4o-mini",
    name=support.name,
    tools=[],                 # your tools; the capability adds load_skill
    capabilities=[support],   # your prompt, the skill list and load_skill
)
# In a notebook or async code: result = await agent.run("Hello!")
result = agent.run_sync("Hello!")

On the Pydantic AI harness, decimalai.pydantic_ai_harness.skills(project) uses its own loader instead.

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
from pydantic_ai import Agent

skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
agent = Agent("openai:gpt-4o-mini", instructions=f"You are a helpful agent.\n\n{skill}")
# In a notebook or async code: result = await agent.run("Hello!")
result = agent.run_sync("Hello!")

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Pydantic AI docs

Deep Agents' own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" deepagents
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

import decimalai.deepagents
from deepagents import create_deep_agent

agent = create_deep_agent(model=model, **decimalai.deepagents.skills())
agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})

The default backend reads files but has no shell. To run a skill's scripts, pass skills(backend=LocalShellBackend(...)).

The same install from Python, for a notebook or a setup script. Deep Agents' own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" deepagents

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

import decimalai.deepagents
from deepagents import create_deep_agent

agent = create_deep_agent(model=model, **decimalai.deepagents.skills())
agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})

The default backend reads files but has no shell. To run a skill's scripts, pass skills(backend=LocalShellBackend(...)).

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
from deepagents import create_deep_agent

skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
agent = create_deep_agent(model=model, system_prompt=f"You are a helpful agent.\n\n{skill}")
agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Deep Agents docs

Its own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" agent-framework
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

import asyncio

from agent_framework import Agent
from decimalai.agent_framework import skills

agent = Agent(client=client, instructions="You are a helpful agent.", context_providers=[skills()])
asyncio.run(agent.run("Hello!"))

It caches skills by default, so restart the process after decimalai skills update.

The same install from Python, for a notebook or a setup script. Its own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" agent-framework

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

import asyncio

from agent_framework import Agent
from decimalai.agent_framework import skills

agent = Agent(client=client, instructions="You are a helpful agent.", context_providers=[skills()])
asyncio.run(agent.run("Hello!"))

It caches skills by default, so restart the process after decimalai skills update.

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

import asyncio
from pathlib import Path
from agent_framework import Agent

skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
agent = Agent(client=client, instructions=f"You are a helpful agent.\n\n{skill}")
asyncio.run(agent.run("Hello!"))

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Microsoft Agent Framework docs

Strands' own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" strands-agents
decimalai skills add agentsope-agentsop-agent-topology-selection

Add it to your agent

from decimalai.strands import skills
from strands import Agent
from strands.vended_tools import file_editor, shell

agent = Agent(
    model=model,                # always pass one: the default is Amazon Bedrock
    system_prompt="You are a helpful agent.",
    tools=[file_editor, shell],
    plugins=[skills()],
)
agent("Hello!")

Strands loads an agent's skills once, so build the agent again after decimalai skills update.

The same install from Python, for a notebook or a setup script. Strands' own skill loader reads the installed folder. No DecimalAI account needed.

Install

pip install "decimalai>=0.16" strands-agents

Add it to your agent

from decimalai import skillpkg

# Writes .agents/skills and .decimal/skills.toml. Safe to run twice.
result = skillpkg.add("agentsope-agentsop-agent-topology-selection")
if result.exit_code:
    raise SystemExit(result.problems)

from decimalai.strands import skills
from strands import Agent
from strands.vended_tools import file_editor, shell

agent = Agent(
    model=model,                # always pass one: the default is Amazon Bedrock
    system_prompt="You are a helpful agent.",
    tools=[file_editor, shell],
    plugins=[skills()],
)
agent("Hello!")

Strands loads an agent's skills once, so build the agent again after decimalai skills update.

No DecimalAI package. The whole skill goes in every prompt, and nothing pins or updates it.

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

Give it to your agent

from pathlib import Path
from strands import Agent

skill = Path(".agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md").read_text()
agent = Agent(model=model, system_prompt=f"You are a helpful agent.\n\n{skill}")
agent("Hello!")

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Strands docs

Adds every file the skill has, pinned so you can update it. Cursor, Copilot, Cline and Warp read this folder by themselves.

pip install "decimalai>=0.15"
decimalai skills add agentsope-agentsop-agent-topology-selection

No Python or account. Cursor, Copilot, Cline and Warp read this folder by themselves.

Save it into your project

curl -fsSL --create-dirs -o .agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md https://app.decimal.ai/s/agentsope-agentsop-agent-topology-selection/SKILL.md

Copy SKILL.md

Save it in your project, as

.agents/skills/agentsope-agentsop-agent-topology-selection/SKILL.md

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Cursor and other editors docs

Fetch the file and give its text to your model as instructions. No account or package needed.

Get the file

curl -fsSL https://app.decimal.ai/s/agentsope-agentsop-agent-topology-selection/SKILL.md

Read the summary as JSON

curl -fsSL https://app.decimal.ai/s/agentsope-agentsop-agent-topology-selection.json

This gets SKILL.md only. The skill's 1 other file is not included.

Other ways to add it

Other setups docs

You don't need a DecimalAI account.

Version: v1, tested 8/24/2026
Source: agentsope/skillalchemy ↗
License: MIT

Manage it in DecimalAI

Saved prompts and skills, pinned versions, and traces of this skill in your runs. DecimalAI does not run your agent.

Claude Code reads files from your project, so DecimalAI config does not apply there.

On Claude Agent SDK: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.

On OpenAI Agents: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.

On OpenAI SDK: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.

On Anthropic: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.

On Gemini API: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.

On LangChain: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.

On CrewAI: set DECIMAL_API_KEY and add decimalai.init(crewai=True) to record runs and skill use. The skill version stays in your repo.

On Google ADK: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.

On Pydantic AI: save the skill to an agent here, set DECIMAL_API_KEY, and the same code uses it with no command to run. Changes you save reach the next run with no redeploy.

On Deep Agents: set DECIMAL_API_KEY and add decimalai.init(langchain=True) to record runs and skill use. The skill version stays in your repo.

On Microsoft Agent Framework: set DECIMAL_API_KEY and add decimalai.init(otel=True, agent_name="support") to record runs and skill use. The skill version stays in your repo.

On Strands: set DECIMAL_API_KEY and add decimalai.init(otel=True, agent_name="support") to record runs and skill use. The skill version stays in your repo.

Editors read files from your project, so DecimalAI config does not apply there.

Anywhere else: record a use with decimalai.log_skill_activation() inside a trace.

Use this skill

SKILL.md

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:

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.
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]].

About this skill

Automatic

AI Engineer pack

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/3/2026

View 15 scanner checks

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

agentsope / skillalchemy

skills/agentsop-agent-topology-selection/SKILL.md

View on GitHub ↗

License MITImported 8/3/2026Version v1Bundled 1 file

Illustrative Want to see what agentsope/agentsop-agent-topology-selection would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Related skills

Skills that do similar work, with their headline benchmark lift.

From the same source and nearby in the catalogue.

Ready to supercharge your AI agents?

SkillScore

Safety

What it changes

Track record

Use this skill

Multi-Agent Topology Selection · SOP (ENHANCE overlay)

1. 何时激活 (When to Activate)

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

The selection rubric (three binary questions)

3. SOP 工作流 (Selection Protocol)

Step 1 · Defend the single-agent baseline first

Step 2 · If splitting, decide static vs dynamic routing

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

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

Step 5 · Verify the chosen topology can terminate

Step 6 · Reconsider before scaling agents up

4. 操作模型 (Operation Models)

OP-1 · Defend the single-agent baseline

OP-2 · Single-vs-multi gate

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

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

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

OP-6 · Apply the supervisor-default caveat

OP-7 · Tune-before-switch

OP-8 · Bound the topology

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

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

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

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

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

附录: 引用 (Citations)

SkillSafety

Source

Related skills

More in the registry