SwarmRearrange

Overview

SwarmRearrange is a class for orchestrating multiple swarms in a flow pattern. Each swarm is looked up by its name attribute, and its output becomes the next step’s task. Every swarm’s output is also added to arrangement.conversation.

Installation

pip install -U swarms

Attributes

str

default:"generate_id('swarm-rearrange')"

Unique identifier for the swarm arrangement, e.g. swarm-rearrange-<32 hex> — not a UUID.

str

default:"SwarmRearrange"

Name of the swarm arrangement.

str

default:"A swarm of swarms..."

Description of the arrangement.

List[Any]

default:"[]"

List of swarm objects to be managed. Despite the default of [], the constructor runs reliability_checks() and raises ValueError if swarms is empty — a non-empty list is effectively required.

str

default:"None"

Flow pattern for swarm execution. Uses arrow notation to define execution order. Despite the default of None, reliability_checks() raises ValueError if flow is falsy — a flow string is effectively required.

int

default:"1"

Number of passes through the whole flow. Values of 0 or less are replaced with 1.

bool

default:"True"

Stored but not read. Logging happens either way.

bool

default:"False"

Enable human intervention during execution.

Callable

default:"None"

Custom function for human interaction.

bool

default:"False"

Stored but not read. run() always returns a string.

HistoryOutputType

default:"dict-all-except-first"

Currently has no effect: self.output_type is stored but never read. run() never calls history_output_formatter and always returns current_task, a plain string (see run() below).

Methods

add_swarm()

Adds a single swarm to the arrangement.

def add_swarm(self, swarm: Any)

Parameters:

swarm (Any): The swarm object to add

remove_swarm()

Removes a swarm by name from the arrangement.

def remove_swarm(self, swarm_name: str)

Parameters:

swarm_name (str): Name of the swarm to remove

add_swarms()

Adds multiple swarms to the arrangement.

def add_swarms(self, swarms: List[Any])

Parameters:

swarms (List[Any]): List of swarm objects to add

validate_flow()

Validates the flow pattern syntax and swarm names.

def validate_flow(self) -> bool

Returns: True if the flow is valid. Raises: ValueError if "->" is missing from the flow, a referenced swarm name isn’t registered (and isn’t "H"), or the flow contains duplicate swarm names.

set_custom_flow()

Overrides the current flow pattern.

def set_custom_flow(self, flow: str)

Parameters:

flow (str): The new flow pattern string

run()

Executes the swarm arrangement according to the flow pattern.

def run(self, task: str = None, img: str = None, custom_tasks: Dict[str, str] = None, *args, **kwargs)

Parameters:

task (str, optional): The task to be executed
img (str, optional): Image input for the task
custom_tasks (Dict[str, str], optional): Custom tasks mapped to specific swarms. See the warning below
*args, **kwargs: Forwarded to each swarm’s run() call, after task and img

Returns: A plain str — always current_task (the final swarm’s textual output), regardless of output_type. run() catches all exceptions internally and, on failure, returns str(e) instead of raising — so callers must check the returned string for error text rather than relying on a try/except around run().

custom_tasks does not work in the current release. Only its first entry is read, and it is matched against the raw flow segments, which keep their surrounding spaces. If it does match, the task text is spliced into the flow as if it were a swarm name, so the run fails and returns the error string. Put the task in task instead.

Flow Pattern Syntax

The flow pattern uses arrow notation (->) to define execution order:

Sequential: "SwarmA -> SwarmB -> SwarmC"
Fan-in: "SwarmA, SwarmB -> SwarmC". Comma-separated swarms run one after another, not concurrently, each on the same input. Their outputs are joined with "; " and passed to the next step
Human intervention: Use "H" in the flow. With human_in_the_loop=True and a custom_human_in_the_loop function, that function receives the current task and its return value becomes the next task. Otherwise run() prompts on stdin with input()

The flow must contain at least one ->, and each swarm name may appear only once.

Usage Examples

Basic Sequential Flow

import os
from swarms import Agent, AgentRearrange, SwarmRearrange

company = "TGSC"

# Initialize the Managing Director agent
managing_director = Agent(
    agent_name="Managing-Director",
    system_prompt=f"""
    As the Managing Director at Blackstone, your role is to oversee the entire investment analysis process for potential acquisitions.
    Your responsibilities include:
    1. Setting the overall strategy and direction for the analysis
    2. Coordinating the efforts of the various team members and ensuring a comprehensive evaluation
    3. Reviewing the findings and recommendations from each team member
    4. Making the final decision on whether to proceed with the acquisition

    For the current potential acquisition of {company}, direct the tasks for the team to thoroughly analyze all aspects of the company, including its financials, industry position, technology, market potential, and regulatory compliance. Provide guidance and feedback as needed to ensure a rigorous and unbiased assessment.
    """,
    model_name="gpt-5.4",
    max_loops=1,
)

# Initialize the Vice President of Finance
vp_finance = Agent(
    agent_name="VP-Finance",
    system_prompt=f"""
    As the Vice President of Finance at Blackstone, your role is to lead the financial analysis of potential acquisitions.
    For the current potential acquisition of {company}, your tasks include:
    1. Conducting a thorough review of {company}' financial statements
    2. Analyzing key financial metrics such as revenue growth, profitability margins, liquidity ratios, and debt levels
    3. Assessing the company's historical financial performance and projecting future performance
    4. Identifying any financial risks or red flags that could impact the acquisition decision
    5. Providing a detailed report on your findings and recommendations to the Managing Director
    """,
    model_name="gpt-5.4",
    max_loops=1,
)

# Initialize the Industry Analyst
industry_analyst = Agent(
    agent_name="Industry-Analyst",
    system_prompt=f"""
    As the Industry Analyst at Blackstone, your role is to provide in-depth research and analysis on the industries and markets relevant to potential acquisitions.
    For the current potential acquisition of {company}, your tasks include:
    1. Conducting a comprehensive analysis of the industrial robotics and automation solutions industry
    2. Identifying the major players in the industry and assessing their market share
    3. Evaluating {company}' competitive position within the industry
    4. Analyzing the key drivers and restraints for the industry
    5. Identifying potential risks and opportunities for {company} based on the industry analysis
    """,
    model_name="gpt-5.4",
    max_loops=1,
)

# Initialize the Technology Expert
tech_expert = Agent(
    agent_name="Tech-Expert",
    system_prompt=f"""
    As the Technology Expert at Blackstone, your role is to assess the technological capabilities, competitive advantages, and potential risks of companies being considered for acquisition.
    For the current potential acquisition of {company}, your tasks include:
    1. Conducting a deep dive into {company}' proprietary technologies
    2. Assessing the uniqueness, scalability, and defensibility of {company}' technology stack
    3. Comparing {company}' technologies to those of its competitors
    4. Evaluating {company}' research and development capabilities
    5. Identifying any potential technology risks or disruptive threats
    """,
    model_name="gpt-5.4",
    max_loops=1,
)

# Initialize the Market Researcher
market_researcher = Agent(
    agent_name="Market-Researcher",
    system_prompt=f"""
    As the Market Researcher at Blackstone, your role is to analyze the target company's customer base, market share, and growth potential.
    For the current potential acquisition of {company}, your tasks include:
    1. Analyzing {company}' current customer base
    2. Assessing {company}' market share within its target markets
    3. Conducting a detailed market sizing and segmentation analysis
    4. Evaluating the demand drivers and sales cycles
    5. Developing financial projections and estimates for revenue growth potential
    """,
    model_name="gpt-5.4",
    max_loops=1,
)

# Initialize the Regulatory Specialist
regulatory_specialist = Agent(
    agent_name="Regulatory-Specialist",
    system_prompt=f"""
    As the Regulatory Specialist at Blackstone, your role is to identify and assess any regulatory risks, compliance requirements, and potential legal liabilities.
    For the current potential acquisition of {company}, your tasks include:
    1. Identifying all relevant regulatory bodies and laws that govern the operations
    2. Reviewing {company}' current compliance policies, procedures, and track record
    3. Assessing the potential impact of any pending or proposed changes to relevant regulations
    4. Evaluating the potential legal liabilities and risks
    5. Providing recommendations on regulatory or legal due diligence steps
    """,
    model_name="gpt-5.4",
    max_loops=1,
)

# Create a list of agents
agents = [
    managing_director,
    vp_finance,
    industry_analyst,
    tech_expert,
    market_researcher,
    regulatory_specialist,
]

# Define multiple flow patterns
flows = [
    "Industry-Analyst -> Tech-Expert -> Market-Researcher -> Regulatory-Specialist -> Managing-Director -> VP-Finance",
    "Managing-Director -> VP-Finance -> Industry-Analyst -> Tech-Expert -> Market-Researcher -> Regulatory-Specialist",
    "Tech-Expert -> Market-Researcher -> Regulatory-Specialist -> Industry-Analyst -> Managing-Director -> VP-Finance",
]

# Create instances of AgentRearrange for each flow pattern
blackstone_acquisition_analysis = AgentRearrange(
    name="Blackstone-Acquisition-Analysis",
    description="A system for analyzing potential acquisitions",
    agents=agents,
    flow=flows[0],
)

blackstone_investment_strategy = AgentRearrange(
    name="Blackstone-Investment-Strategy",
    description="A system for evaluating investment opportunities",
    agents=agents,
    flow=flows[1],
)

blackstone_market_analysis = AgentRearrange(
    name="Blackstone-Market-Analysis",
    description="A system for analyzing market trends and opportunities",
    agents=agents,
    flow=flows[2],
)

swarm_arrange = SwarmRearrange(
    swarms=[
        blackstone_acquisition_analysis,
        blackstone_investment_strategy,
        blackstone_market_analysis,
    ],
    flow=f"{blackstone_acquisition_analysis.name} -> {blackstone_investment_strategy.name} -> {blackstone_market_analysis.name}",
)

print(
    swarm_arrange.run(
        "Analyze swarms, 150k revenue with 45m+ agents build, with 1.4m downloads since march 2024"
    )
)

Human-in-the-Loop

from swarms import SwarmRearrange

def custom_human_input(task):
    return input(f"Review {task} and provide feedback: ")

# Create arrangement with human intervention
arrangement = SwarmRearrange(
    name="HumanAugmented",
    swarms=[swarm1, swarm2],  # swarm1.name == "SwarmA", swarm2.name == "SwarmB"
    flow="SwarmA -> H -> SwarmB",
    human_in_the_loop=True,
    custom_human_in_the_loop=custom_human_input
)

# Execute with human intervention
result = arrangement.run("Initial task")

Best Practices

Best Practice	Description
Flow Validation	Always validate flows before execution
Error Handling	`run()` never raises — it catches all exceptions internally and returns `str(e)`. Inspect the returned string for error text rather than wrapping `run()` in try/catch
History Tracking	Read `arrangement.conversation` to see every swarm’s output in order
Resource Management	Set appropriate `max_loops` to prevent infinite execution
Logging	Enable verbose mode during development for detailed logging

Source Code

View the source code on GitHub

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

SwarmRearrange

Overview

Installation

Attributes

Methods

add_swarm()

remove_swarm()

add_swarms()

validate_flow()

set_custom_flow()

run()

Flow Pattern Syntax

Usage Examples

Basic Sequential Flow

Human-in-the-Loop

Best Practices

Source Code

​Overview

​Installation

​Attributes

​Methods

​add_swarm()

​remove_swarm()

​add_swarms()

​validate_flow()

​set_custom_flow()

​run()

​Flow Pattern Syntax

​Usage Examples

​Basic Sequential Flow

​Human-in-the-Loop

​Best Practices

​Source Code

Overview

Installation

Attributes

Methods

add_swarm()

remove_swarm()

add_swarms()

validate_flow()

set_custom_flow()

run()

Flow Pattern Syntax

Usage Examples

Basic Sequential Flow

Human-in-the-Loop

Best Practices

Source Code