AutoSwarmBuilder

Overview

The AutoSwarmBuilder class automatically builds and manages swarms of AI agents by intelligently decomposing tasks and creating specialized agents as needed. It uses a sophisticated boss agent system to delegate work, design agent architectures, and orchestrate multi-agent collaboration.

Class Definition

from swarms import AutoSwarmBuilder

Parameters

str

default:"auto-swarm-builder"

The name of the swarm builder instance

str

default:"Auto Swarm Builder"

A description of the swarm builder’s purpose

bool

default:"True"

Whether to output detailed logs during execution

int

default:"1"

Maximum number of execution loops. Must be greater than 0

str

default:"gpt-5.4"

The LLM model to use for the boss agent that designs the swarm architecture

int

default:"8000"

Maximum tokens for the LLM responses from the boss agent

str

default:"return-agents"

Type of execution to perform. Options: “return-agents”, “return-swarm-router-config”, “return-agents-objects”

str

default:"BOSS_SYSTEM_PROMPT"

System prompt for the boss agent that designs swarm architectures. Defaults to comprehensive agent design prompt

dict

default:"{}"

Additional arguments to pass to the LiteLLM wrapper

bool

default:"False"

Default value for run()’s execute parameter. When True, run() builds real Agent objects from a freshly generated spec and executes them through a SwarmRouter (via build_and_run_swarm()) instead of returning a spec-only result

Execution Types

return-agents

Returns agent specifications as a dictionary:

{
    "agents": [
        {
            "agent_name": "Research-Agent",
            "description": "Expert in research",
            "system_prompt": "...",
            "model_name": "gpt-5.4",
            ...
        },
        ...
    ]
}

return-swarm-router-config

Returns complete SwarmRouter configuration:

{
    "name": "Research-Team",
    "description": "...",
    "agents": [...],
    "swarm_type": "SequentialWorkflow",
    "rearrange_flow": "...",
    "rules": "...",
    "task": "..."
}

return-agents-objects

Returns instantiated Agent objects ready for use:

[Agent(...), Agent(...), Agent(...)]

Methods

`run()`

def run(self, task: str, execute: Optional[bool] = None, *args, **kwargs) -> Any

Runs the swarm builder on a given task, creating agents based on execution type. Parameters:

str

required

The task to execute. The boss agent will analyze this task and design an appropriate swarm architecture

Optional[bool]

default:"None"

When True, builds real agents and a SwarmRouter from a freshly generated spec and runs it (see build_and_run_swarm()), returning a dict that includes the execution output. When False, only a spec-only result is returned, per swarm_type. Defaults to self.auto_execute when left as None

Returns:

Any

When executing (execute resolves to True): a dict from build_and_run_swarm(). Otherwise, the result depends on swarm_type:

“return-agents”: Dictionary with agent specifications
“return-swarm-router-config”: SwarmRouter configuration dictionary
“return-agents-objects”: List of instantiated Agent objects

Raises:

ValueError: If swarm_type is invalid
Exception: If there’s an error during swarm execution

`build_and_run_swarm()`

def build_and_run_swarm(self, task: str) -> dict

Designs a multi-agent team for task and executes it. Generates one validated SwarmRouterConfig, builds the real Agent objects from that same spec’s agents, and runs a SwarmRouter with them — so the agents that execute are exactly the ones described in the returned metadata, unlike chaining create_agents() and initialize_swarm_router() (which make two independent, potentially-disagreeing LLM calls). This is what run() calls when execute resolves to True. Parameters:

str

required

The task to design and run a swarm for

Returns:

dict

{"name", "description", "agents" (names actually built), "swarm_type", "task", "output"} where output is the SwarmRouter’s execution result

`create_agents()`

def create_agents(self, task: str) -> dict

Creates agent specifications for a given task using the boss agent. Parameters:

str

required

The task to create agents for

Returns:

dict

Dictionary containing agent specifications with comprehensive system prompts and configurations

Raises:

Exception: If there’s an error during agent creation

`create_agents_from_specs()`

def create_agents_from_specs(
    self,
    agents_dictionary: Any
) -> List[Agent]

Creates Agent objects from agent specifications. Parameters:

Any

required

Dictionary or Pydantic model containing agent specifications

Returns:

List[Agent]

List of instantiated Agent objects ready for use

Note: Automatically handles parameter name mapping (e.g., ‘description’ → ‘agent_description’)

`create_router_config()`

def create_router_config(self, task: str) -> dict

Creates a SwarmRouter configuration for a given task. Parameters:

str

required

The task to create router configuration for

Returns:

dict

Complete SwarmRouter configuration including agents, swarm type, and execution parameters

Raises:

Exception: If there’s an error during router config creation

`batch_run()`

def batch_run(self, tasks: List[str]) -> List[Any]

Runs the swarm builder on a list of tasks sequentially. Parameters:

List[str]

required

List of tasks to execute

Returns:

List[Any]

List of results from each task execution

`reliability_check()`

def reliability_check(self) -> None

Performs reliability checks on the AutoSwarmBuilder configuration. Raises:

ValueError: If max_loops is set to 0

`list_types()`

def list_types(self) -> List[str]

Lists all available execution types. Returns:

List[str]

List of available execution types

`initialize_swarm_router()`

def initialize_swarm_router(self, agents: List[Agent], task: str) -> Any

Builds a SwarmRouterConfig for the task via the boss agent, then constructs and runs a SwarmRouter with the given agents. Not called automatically by run() for any swarm_type — call it directly if you want AutoSwarmBuilder to both design agents (via create_agents) and immediately execute them through a SwarmRouter. Parameters:

List[Agent]

required

Agents to pass to the constructed SwarmRouter

str

required

The task used to derive the SwarmRouter configuration and to execute

Returns: Result of swarm_router.run(task) Raises: Exception if router config generation or execution fails

`dict_to_agent()`

def dict_to_agent(self, output: dict) -> List[Agent]

Alternate helper that builds Agent objects directly from a raw {"agents": [...]} dictionary via Agent(**agent_config), without the field-name mapping (description → agent_description) that create_agents_from_specs() performs. Parameters:

dict

required

Dictionary containing an "agents" list of agent configuration dicts

Returns: List[Agent]

Data Models

AgentSpec

class AgentSpec(BaseModel):
    agent_name: Optional[str]              # Agent's unique name
    description: Optional[str]             # Detailed agent description
    system_prompt: Optional[str]           # Complete system prompt
    model_name: Optional[str] = "gpt-5.4" # LLM model name
    auto_generate_prompt: Optional[bool] = False
    max_tokens: Optional[int] = 8192
    temperature: Optional[float] = 0.5
    role: Optional[str] = "worker"
    max_loops: Optional[int] = 1
    goal: Optional[str]                    # Agent's primary objective

SwarmRouterConfig

class SwarmRouterConfig(BaseModel):
    name: str                              # Team name
    description: str                       # Team description
    agents: List[AgentSpec]                # Agent configurations
    swarm_type: SwarmType                  # Multi-agent structure type
    rearrange_flow: Optional[str]          # Flow configuration
    rules: Optional[str]                   # Rules for all agents
    multi_agent_collab_prompt: Optional[str]
    task: str                              # Task to execute

Boss Agent Design Principles

The AutoSwarmBuilder uses a sophisticated boss agent with expertise in:

Comprehensive Task Analysis: Deconstructing tasks into components and sub-tasks
Agent Design Excellence: Creating agents with clear purposes and complementary personalities
System Prompt Engineering: Crafting detailed prompts with role, capabilities, and protocols
Multi-Agent Coordination: Designing communication channels and task handoff procedures
Quality Assurance: Establishing success criteria and validation procedures

Usage Examples

Basic Agent Creation

from swarms import AutoSwarmBuilder

# Create swarm builder
builder = AutoSwarmBuilder(
    name="intelligent-swarm-builder",
    model_name="claude-sonnet-4-6",
    swarm_type="return-agents",
    verbose=True
)

# Generate agent specifications
agent_specs = builder.run(
    task="Create a team to analyze financial reports and generate investment recommendations"
)

print(agent_specs)

Create Agent Objects

builder = AutoSwarmBuilder(
    name="agent-factory",
    swarm_type="return-agents-objects",
    model_name="claude-sonnet-4-6"
)

# Get ready-to-use Agent objects
agents = builder.run(
    task="Build a content creation team with research, writing, and editing capabilities"
)

# Use the agents
for agent in agents:
    result = agent.run("Write an article about AI trends")
    print(f"{agent.agent_name}: {result}")

Generate SwarmRouter Config

builder = AutoSwarmBuilder(
    name="swarm-architect",
    swarm_type="return-swarm-router-config",
    model_name="claude-sonnet-4-6"
)

config = builder.run(
    task="Design a hierarchical swarm for comprehensive market research and analysis"
)

print(f"Swarm Type: {config['swarm_type']}")
print(f"Number of Agents: {len(config['agents'])}")

Batch Processing

builder = AutoSwarmBuilder(
    swarm_type="return-agents-objects"
)

tasks = [
    "Create a customer service team",
    "Build a data analysis team",
    "Design a creative writing team"
]

results = builder.batch_run(tasks)

for i, agents in enumerate(results):
    print(f"Team {i+1}: {len(agents)} agents created")

Advanced Features

Custom System Prompt

custom_prompt = """
You are an expert swarm architect specializing in financial analysis teams.
Design agents with deep expertise in financial modeling, risk assessment,
and investment strategy.
"""

builder = AutoSwarmBuilder(
    system_prompt=custom_prompt,
    model_name="claude-sonnet-4-6"
)

agents = builder.run("Create a financial analysis team")

Additional LLM Arguments

builder = AutoSwarmBuilder(
    model_name="claude-sonnet-4-6",
    additional_llm_args={
        "api_base": "https://custom-endpoint.com",
        "api_key": "custom-key",
        "timeout": 60
    }
)

Multi-Agent Architecture Types

The boss agent can design swarms using various architectures:

AgentRearrange: Dynamic task reallocation
MixtureOfAgents: Parallel specialized processing
SequentialWorkflow: Linear task progression
ConcurrentWorkflow: Parallel execution
GroupChat: Collaborative discussion
HierarchicalSwarm: Layered decision-making
HeavySwarm: High-capacity specialized processing
MajorityVoting: Democratic decision-making
And more…

Source Code

View the source code on GitHub

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

AutoSwarmBuilder

Overview

Class Definition

Parameters

Execution Types

return-agents

return-swarm-router-config

return-agents-objects

Methods

`run()`

`build_and_run_swarm()`

`create_agents()`

`create_agents_from_specs()`

`create_router_config()`

`batch_run()`

`reliability_check()`

`list_types()`

`initialize_swarm_router()`

`dict_to_agent()`

Data Models

AgentSpec

SwarmRouterConfig

Boss Agent Design Principles

Usage Examples

Basic Agent Creation

Create Agent Objects

Generate SwarmRouter Config

Batch Processing

Advanced Features

Custom System Prompt

Additional LLM Arguments

Multi-Agent Architecture Types

Source Code

​Overview

​Class Definition

​Parameters

​Execution Types

​return-agents

​return-swarm-router-config

​return-agents-objects

​Methods

​run()

​build_and_run_swarm()

​create_agents()

​create_agents_from_specs()

​create_router_config()

​batch_run()

​reliability_check()

​list_types()

​initialize_swarm_router()

​dict_to_agent()

​Data Models

​AgentSpec

​SwarmRouterConfig

​Boss Agent Design Principles

​Usage Examples

​Basic Agent Creation

​Create Agent Objects

​Generate SwarmRouter Config

​Batch Processing

​Advanced Features

​Custom System Prompt

​Additional LLM Arguments

​Multi-Agent Architecture Types

​Source Code

Overview

Class Definition

Parameters

Execution Types

return-agents

return-swarm-router-config

return-agents-objects

Methods

`run()`

`build_and_run_swarm()`

`create_agents()`

`create_agents_from_specs()`

`create_router_config()`

`batch_run()`

`reliability_check()`

`list_types()`

`initialize_swarm_router()`

`dict_to_agent()`

Data Models

AgentSpec

SwarmRouterConfig

Boss Agent Design Principles

Usage Examples

Basic Agent Creation

Create Agent Objects

Generate SwarmRouter Config

Batch Processing

Advanced Features

Custom System Prompt

Additional LLM Arguments

Multi-Agent Architecture Types

Source Code