AutoSwarmBuilder: Practical Tutorial

A comprehensive guide to using AutoSwarmBuilder for automatic multi-agent team generation and orchestration.

Overview

AutoSwarmBuilder is an intelligent system that automatically designs, creates, and orchestrates multi-agent teams based on natural language task descriptions. It uses a sophisticated "boss" agent that analyzes your requirements and generates specialized agents with comprehensive system prompts, distinct personalities, and appropriate swarm architectures.

Feature	Description
Intelligent Agent Generation	Creates agents with roles, personalities, expertise, and limitations
Comprehensive System Prompts	Generates detailed prompts including decision-making frameworks
Automatic Architecture Selection	Chooses optimal swarm type for the task
Flexible Output Formats	Returns agents, swarm configs, or agent objects
Scalable Teams	Generates from 2 to dozens of specialized agents

When to Use AutoSwarmBuilder

Best For: - Rapid prototyping of multi-agent systems - Exploring different team compositions - Tasks where optimal agent design isn't obvious - Creating specialized teams for one-time use - Learning about multi-agent architectures

Not Ideal For: - Production systems requiring precise agent tuning - Tasks with well-established agent patterns - When you need complete control over every detail

---

Installation

pip install -U swarms

---

Basic Example

from swarms.structs.auto_swarm_builder import AutoSwarmBuilder
import json

# Create builder
swarm = AutoSwarmBuilder(
    name="Content-Creation-Team",
    description="Builds content creation teams",
    model_name="gpt-4o",  # Boss agent model
    max_loops=1,
    execution_type="return-agents",
    verbose=True
)

# Define task
task = """
Create a content creation team with 4 agents:
- Researcher: Gathers information and data
- Writer: Creates compelling narratives
- Editor: Refines and polishes content
- SEO Specialist: Optimizes for search engines

They should collaborate on creating high-quality blog posts.
"""

# Generate team
team_config = swarm.run(task=task)

# View generated team
print(json.dumps(team_config, indent=2))

---

Key Parameters

Parameter	Type	Default	Description
name	str	Required	Name of the builder instance
description	str	Required	Purpose/description of the builder
model_name	str	"gpt-4o"	Model for boss agent
max_loops	int	1	Loops for generation process
execution_type	str	"return-agents"	Output format type
verbose	bool	False	Enable detailed logging

Execution Types

Type	Returns	Structure
"return-agents"	List of agent dicts	[{"agent_name": "...", "system_prompt": "...", "description": "..."}]
"return-swarm-router-config"	SwarmRouter config	Complete configuration ready to use
"return-agents-objects"	List of Agent objects	Instantiated Agent objects

---

Advanced Examples

Example 1: Financial Analysis Team

from swarms.structs.auto_swarm_builder import AutoSwarmBuilder

swarm = AutoSwarmBuilder(
    name="Financial-Analysis-Builder",
    description="Creates specialized financial analysis teams",
    model_name="gpt-4o",
    execution_type="return-agents",
    verbose=True
)

task = """
Create a comprehensive financial analysis team with 6 highly specialized agents:

1. **Equity Analyst**: Expert in stock market analysis, company valuations, and sector trends
2. **Fixed Income Analyst**: Specialist in bonds, credit ratings, and debt instruments
3. **Quantitative Analyst**: Builds mathematical models and trading algorithms
4. **Risk Manager**: Assesses portfolio risk, VaR calculations, and hedging strategies
5. **Macro Economist**: Analyzes macroeconomic trends, monetary policy, and global markets
6. **Portfolio Manager**: Oversees overall strategy, asset allocation, and rebalancing

The team should work together to analyze investment opportunities and manage a diversified portfolio.
Make each agent's system prompt extremely detailed with specific methodologies and frameworks.
"""

team = swarm.run(task=task)

# Each agent will have:
# - Specific role and responsibilities
# - Distinct personality and approach
# - Comprehensive system prompt (often 500+ words)
# - Clear capabilities and limitations
# - Collaboration guidelines

for agent in team:
    print(f"\nAgent: {agent['agent_name']}")
    print(f"Description: {agent['description']}")
    print(f"Prompt Length: {len(agent['system_prompt'])} characters")

Example 2: Software Development Team

swarm = AutoSwarmBuilder(
    name="Dev-Team-Builder",
    model_name="gpt-4o",
    execution_type="return-swarm-router-config",  # Get complete swarm
)

task = """
Create an enterprise software development team:

- **Tech Lead**: Architecture decisions, code reviews, technical strategy
- **Backend Developer**: API design, database optimization, server-side logic
- **Frontend Developer**: UI components, state management, responsive design
- **DevOps Engineer**: CI/CD, infrastructure, monitoring, deployments
- **QA Engineer**: Testing strategy, automation, quality assurance
- **Security Engineer**: Security audits, vulnerability assessment, compliance

Team should use Agile methodology and collaborate on building a SaaS platform.
Include detailed technical specifications and best practices in each agent's prompt.
"""

swarm_config = swarm.run(task=task)

# swarm_config is ready to use with SwarmRouter
# It includes the complete architecture and agent specifications

Example 3: Research Team

swarm = AutoSwarmBuilder(
    name="Research-Team-Builder",
    model_name="gpt-4o",
    execution_type="return-agents-objects",  # Get Agent objects
)

task = """
Create a scientific research team for a clinical study:

- **Principal Investigator**: Leads research, designs studies, interprets results
- **Biostatistician**: Statistical analysis, study design, data interpretation
- **Data Scientist**: Machine learning, data mining, predictive modeling
- **Literature Reviewer**: Systematic reviews, meta-analysis, evidence synthesis
- **Research Coordinator**: Project management, participant recruitment, data collection

Team should collaborate on a longitudinal study analyzing treatment efficacy.
"""

agents = swarm.run(task=task)

# agents is a list of Agent objects
# Ready to use immediately
for agent in agents:
    result = agent.run("Analyze the study protocol")
    print(f"{agent.agent_name}: {result[:100]}...")

---

Use Cases

Use Case 1: Accounting Team

task = """
Create an accounting team to analyze cryptocurrency transactions with 5 agents:

1. **Tax Accountant**: Cryptocurrency tax implications, capital gains, reporting requirements
2. **Forensic Accountant**: Transaction tracing, fraud detection, blockchain analysis
3. **Compliance Officer**: Regulatory compliance, AML/KYC requirements, reporting standards
4. **Financial Auditor**: Accuracy verification, reconciliation, audit trails
5. **Risk Assessor**: Risk analysis, exposure assessment, mitigation strategies

Each agent needs extremely extensive and comprehensive system prompts with specific frameworks,
regulations, and methodologies for handling crypto transactions.
"""

swarm = AutoSwarmBuilder(
    name="Crypto-Accounting-Team",
    model_name="gpt-4o",
    execution_type="return-agents"
)

team = swarm.run(task=task)

Use Case 2: Customer Support Team

task = """
Create a customer support team with specialized agents:

- **Tier 1 Support**: Handle common questions, basic troubleshooting, ticket routing
- **Technical Support**: Advanced troubleshooting, bug investigation, technical guidance
- **Escalation Specialist**: Handle complex issues, coordinate with engineering, customer advocacy
- **Quality Assurance**: Monitor support quality, provide feedback, identify training needs
- **Knowledge Manager**: Maintain documentation, create FAQs, identify common patterns

Team should provide 24/7 support for a SaaS platform with focus on customer satisfaction.
"""

swarm = AutoSwarmBuilder(
    name="Support-Team-Builder",
    model_name="gpt-4o",
)

team = swarm.run(task=task)

Use Case 3: Marketing Campaign Team

task = """
Create a marketing team for product launch:

- **Market Researcher**: Audience analysis, competitive research, trend identification
- **Content Strategist**: Content calendar, messaging framework, brand voice
- **Copywriter**: Ad copy, landing pages, email campaigns, social posts
- **Social Media Manager**: Platform strategy, community engagement, influencer outreach
- **Analytics Specialist**: Campaign performance, A/B testing, ROI analysis

Team should collaborate on launching a new AI productivity tool targeting enterprise clients.
"""

swarm = AutoSwarmBuilder(
    name="Marketing-Campaign-Builder",
    model_name="gpt-4o",
)

team = swarm.run(task=task)

---

Best Practices

1. Be Extremely Specific: Provide detailed role descriptions
2. Request Comprehensive Prompts: Ask for "extremely detailed" and "comprehensive" prompts
3. Define Team Size: Specify exact number of agents needed
4. Describe Collaboration: Explain how agents should work together
5. Use Powerful Models: gpt-4o or claude-sonnet-4 for best results
6. Review and Customize: Always review generated agents before production use
7. Iterate: Run multiple times with refined descriptions if needed

---

Boss System Prompt

The boss agent uses a sophisticated system prompt that includes:

Core Design Principles

• Comprehensive task analysis and decomposition
• Agent design excellence with distinct personalities
• Multi-agent coordination architecture
• Quality assurance and governance

Agent Design Framework

For each agent, the boss defines: - Role & Purpose - Personality Profile - Expertise Matrix - Communication Protocol - Decision-Making Framework - Limitations & Boundaries - Collaboration Strategy

Architecture Types

The boss can select from 14+ swarm architectures: - AgentRearrange - MixtureOfAgents - SequentialWorkflow - ConcurrentWorkflow - HierarchicalSwarm - MajorityVoting - GroupChat - And more...

---

Output Structure

Format: return-agents

[
  {
    "agent_name": "Market-Researcher",
    "description": "Expert market researcher specializing in...",
    "system_prompt": "You are a market research specialist... [comprehensive prompt]"
  },
  {
    "agent_name": "Data-Analyst",
    "description": "Data analysis expert focusing on...",
    "system_prompt": "You are a data analyst... [comprehensive prompt]"
  }
]

Format: return-swarm-router-config

Includes complete SwarmRouter configuration with: - All agent specifications - Swarm type selection - Architecture parameters - Ready to instantiate and run

---

Common Patterns

Pattern 1: Specialized Expertise Teams

# Create domain expert teams
task = "Create 5 medical specialists: cardiologist, neurologist, oncologist, radiologist, pathologist"

Pattern 2: Workflow Teams

# Create process-oriented teams
task = "Create workflow team: intake specialist, processor, quality checker, approver, notifier"

Pattern 3: Cross-Functional Teams

# Create diverse skill teams
task = "Create cross-functional team: technical, business, creative, operational, strategic perspectives"

---

Related Architectures

Architecture	Relationship
SwarmRouter	Can use AutoSwarmBuilder output
HierarchicalSwarm	One possible architecture AutoSwarmBuilder might choose
SequentialWorkflow	Another architecture option

---

Next Steps

• Explore AutoSwarmBuilder Quickstart
• See GitHub Examples
• Learn about Agent Design Principles
• Try SwarmRouter for task routing