ai-mirow-projects
/
swarms
mirror of https://github.com/kyegomez/swarms
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[docs][improve auto swarm builder docs]

Browse Source
pull/1102/head
Kye Gomez 2 weeks ago
parent 4ce854d4b7
commit 4650c5d70e
4 changed files with 345 additions and 61 deletions
Show Stats Download Patch File Download Diff File

360
docs/swarms/structs/auto_swarm_builder.md
Unescape View File

@ -1,35 +1,50 @@
# AutoSwarmBuilder Documentation # AutoSwarmBuilder Documentation
The `AutoSwarmBuilder` is a powerful class that automatically builds and manages swarms of AI agents to accomplish complex tasks. It uses a boss agent to delegate work and create specialized agents as needed. The `AutoSwarmBuilder` is a powerful class that automatically builds and manages swarms of AI agents to accomplish complex tasks. It uses a sophisticated boss agent system to delegate work and create specialized agents as needed.
## Overview ## Overview
The AutoSwarmBuilder is designed to: The AutoSwarmBuilder is designed to:
- Automatically create and coordinate multiple AI agents | Feature | Description |
|---------|-------------|
- Delegate tasks to specialized agents | Automatic Agent Creation | Automatically create and coordinate multiple AI agents |
| Task Delegation | Delegate tasks to specialized agents based on task requirements |
- Manage communication between agents | Agent Communication Management | Manage communication between agents through a swarm router |
| Complex Workflow Handling | Handle complex workflows with various execution types |
- Handle complex workflows through a swarm router | Architecture Pattern Support | Support different multi-agent architecture patterns |
| Error Handling & Logging | Provide comprehensive error handling and logging |
## Parameters ## Parameters
| Parameter | Type | Default | Description | | Parameter | Type | Default | Description |
|-----------|------|---------|-------------| |-----------|------|---------|-------------|
| name | str | None | The name of the swarm | | name | str | "auto-swarm-builder" | The name of the swarm |
| description | str | None | A description of the swarm's purpose | | description | str | "Auto Swarm Builder" | A description of the swarm's purpose |
| verbose | bool | True | Whether to output detailed logs | | verbose | bool | True | Whether to output detailed logs |
| max_loops | int | 1 | Maximum number of execution loops | | max_loops | int | 1 | Maximum number of execution loops |
| random_models | bool | True | Whether to use random models for agents | | model_name | str | "gpt-4.1" | The LLM model to use for the boss agent |
| generate_router_config | bool | False | Whether to generate router configuration |
| interactive | bool | False | Whether to enable interactive mode |
| max_tokens | int | 8000 | Maximum tokens for the LLM responses |
| execution_type | str | "return-agents" | Type of execution to perform |
## Execution Types
The `execution_type` parameter controls how the AutoSwarmBuilder operates:
| Execution Type | Description |
|----------------------------------|-----------------------------------------------------------|
| **"return-agents"** | Creates and returns a list of Agent objects (default) |
| **"execute-swarm-router"** | Executes the swarm router with the created agents |
| **"return-swarm-router-config"** | Returns the swarm router configuration as a dictionary |
| **"return-agent-configurations"**| Returns agent configurations as a dictionary |
## Core Methods ## Core Methods
### run(task: str, *args, **kwargs) ### run(task: str, *args, **kwargs)
Executes the swarm on a given task. Executes the swarm on a given task based on the configured execution type.
**Parameters:** **Parameters:**
@ -41,11 +56,15 @@ Executes the swarm on a given task.
**Returns:** **Returns:**
- The result of the swarm execution - The result of the swarm execution (varies by execution_type)
**Raises:**
- `Exception`: If there's an error during execution
### create_agents(task: str) ### create_agents(task: str)
Creates specialized agents for a given task. Creates specialized agents for a given task using the boss agent system.
**Parameters:** **Parameters:**
@ -53,26 +72,69 @@ Creates specialized agents for a given task.
**Returns:** **Returns:**
- List[Agent]: List of created agents - `List[Agent]`: List of created agents
**Raises:**
- `Exception`: If there's an error during agent creation
### build_agent(agent_name: str, agent_description: str, agent_system_prompt: str) ### build_agent(agent_name: str, agent_description: str, agent_system_prompt: str)
Builds a single agent with specified parameters.
Builds a single agent with specified parameters and enhanced error handling.
**Parameters:** **Parameters:**
- `agent_name` (str): Name of the agent
- `agent_description` (str): Description of the agent | Parameter | Type | Description |
|-----------------------|-------|--------------------------------|
| `agent_name` | str | Name of the agent |
| `agent_description` | str | Description of the agent |
| `agent_system_prompt` | str | System prompt for the agent |
**Returns:**
- `Agent`: The constructed agent
- `agent_system_prompt` (str): System prompt for the agent **Raises:**
- `Exception`: If there's an error during agent construction
### create_router_config(task: str)
Creates a swarm router configuration for a given task.
**Parameters:**
- `task` (str): The task to create router config for
**Returns:** **Returns:**
- Agent: The constructed agent - `dict`: Swarm router configuration dictionary
**Raises:**
- `Exception`: If there's an error creating the configuration
### initialize_swarm_router(agents: List[Agent], task: str)
Initializes and runs the swarm router with the provided agents.
**Parameters:**
- `agents` (List[Agent]): List of agents to use
- `task` (str): The task to execute
**Returns:**
- `Any`: The result of the swarm router execution
**Raises:**
- `Exception`: If there's an error during router initialization or execution
### batch_run(tasks: List[str]) ### batch_run(tasks: List[str])
Executes the swarm on multiple tasks. Executes the swarm on multiple tasks sequentially.
**Parameters:** **Parameters:**
@ -80,16 +142,121 @@ Executes the swarm on multiple tasks.
**Returns:** **Returns:**
- List[Any]: Results from each task execution - `List[Any]`: List of results from each task execution
**Raises:**
- `Exception`: If there's an error during batch execution
### list_types()
Returns the available execution types.
**Returns:**
- `List[str]`: List of available execution types
### dict_to_agent(output: dict)
Converts a dictionary output to a list of Agent objects.
**Parameters:**
- `output` (dict): Dictionary containing agent configurations
**Returns:**
- `List[Agent]`: List of constructed agents
### build_llm_agent(config: BaseModel)
Builds an LLM agent for configuration generation.
**Parameters:**
- `config` (BaseModel): Pydantic model for response format
**Returns:**
- `LiteLLM`: Configured LLM agent
### reliability_check()
Performs reliability checks on the AutoSwarmBuilder configuration.
**Raises:**
- `ValueError`: If max_loops is set to 0
## Configuration Classes
### AgentConfig
Configuration model for individual agents in a swarm.
**Fields:**
| Field | Type | Description |
|-----------------|---------|-----------------------------------------------------------------------------------------------|
| `name` | str | Unique identifier for the agent |
| `description` | str | Comprehensive description of the agent's purpose and capabilities |
| `system_prompt` | str | Detailed system prompt defining agent behavior |
| `goal` | str | Primary objective the agent is tasked with achieving |
| `model_name` | str | LLM model to use for the agent (e.g., 'gpt-4o-mini') |
| `temperature` | float | Controls randomness of responses (0.0-1.0) |
| `max_loops` | int | Maximum number of execution loops (typically 1) |
### AgentsConfig
Configuration model for a list of agents in a swarm.
**Fields:**
- `agents` (List[AgentConfig]): List of agent configurations
### SwarmRouterConfig
Configuration model for SwarmRouter.
**Fields:**
- `name` (str): Name of the team of agents
- `description` (str): Description of the team of agents
- `agents` (List[AgentConfig]): List of agent configurations
- `swarm_type` (SwarmType): Type of multi-agent structure to use
- `rearrange_flow` (Optional[str]): Flow configuration for AgentRearrange structure
- `rules` (Optional[str]): Rules to inject into every agent's system prompt
- `task` (str): The task to be executed by the swarm
## Multi-Agent Architecture Types
The AutoSwarmBuilder supports various multi-agent architecture patterns:
| Architecture Type | Description |
|--------------------------|-----------------------------------------------------------|
| **AgentRearrange** | Dynamic task reallocation based on agent performance |
| **MixtureOfAgents** | Parallel processing with specialized agents |
| **SpreadSheetSwarm** | Structured data processing with coordinated workflows |
| **SequentialWorkflow** | Linear task progression with handoffs |
| **ConcurrentWorkflow** | Parallel execution with coordination |
| **GroupChat** | Collaborative discussion and consensus-building |
| **MultiAgentRouter** | Intelligent routing and load balancing |
| **AutoSwarmBuilder** | Self-organizing and self-optimizing teams |
| **HiearchicalSwarm** | Layered decision-making with management tiers |
| **MajorityVoting** | Democratic decision-making with voting |
| **MALT** | Multi-agent learning and training |
| **CouncilAsAJudge** | Deliberative decision-making with expert panels |
| **InteractiveGroupChat** | Dynamic group interactions |
| **HeavySwarm** | High-capacity processing with multiple agents |
## Examples ## Examples
### Example 1: Content Creation Swarm ### Example 1: Basic Content Creation Swarm
```python ```python
from swarms.structs.auto_swarm_builder import AutoSwarmBuilder from swarms.structs.auto_swarm_builder import AutoSwarmBuilder
# Initialize the swarm builder # Initialize the swarm builder with default settings
swarm = AutoSwarmBuilder( swarm = AutoSwarmBuilder(
name="Content Creation Swarm", name="Content Creation Swarm",
description="A swarm specialized in creating high-quality content" description="A swarm specialized in creating high-quality content"
@ -102,15 +269,19 @@ result = swarm.run(
) )
``` ```
### Example 2: Data Analysis Swarm ### Example 2: Advanced Configuration with Custom Model
```python ```python
from swarms.structs.auto_swarm_builder import AutoSwarmBuilder from swarms.structs.auto_swarm_builder import AutoSwarmBuilder
# Initialize the swarm builder # Initialize with custom configuration
swarm = AutoSwarmBuilder( swarm = AutoSwarmBuilder(
name="Data Analysis Swarm", name="Data Analysis Swarm",
description="A swarm specialized in data analysis and visualization" description="A swarm specialized in data analysis and visualization",
model_name="gpt-4o",
max_tokens=12000,
verbose=True,
execution_type="return-agents"
) )
# Run the swarm on a data analysis task # Run the swarm on a data analysis task
@ -120,7 +291,50 @@ result = swarm.run(
) )
``` ```
### Example 3: Batch Processing Multiple Tasks ### Example 3: Getting Agent Configurations Only
```python
from swarms.structs.auto_swarm_builder import AutoSwarmBuilder
# Initialize to return agent configurations
swarm = AutoSwarmBuilder(
name="Marketing Swarm",
description="A swarm for marketing strategy development",
execution_type="return-agent-configurations"
)
# Get agent configurations without executing
agent_configs = swarm.run(
"Create a comprehensive marketing strategy for a new tech product launch"
)
print("Generated agents:")
for agent in agent_configs["agents"]:
print(f"- {agent['name']}: {agent['description']}")
```
### Example 4: Getting Swarm Router Configuration
```python
from swarms.structs.auto_swarm_builder import AutoSwarmBuilder
# Initialize to return router configuration
swarm = AutoSwarmBuilder(
name="Research Swarm",
description="A swarm for research and analysis",
execution_type="return-swarm-router-config"
)
# Get the complete swarm router configuration
router_config = swarm.run(
"Conduct market research on renewable energy trends and create a detailed report"
)
print(f"Swarm Type: {router_config['swarm_type']}")
print(f"Number of Agents: {len(router_config['agents'])}")
```
### Example 5: Batch Processing Multiple Tasks
```python ```python
from swarms.structs.auto_swarm_builder import AutoSwarmBuilder from swarms.structs.auto_swarm_builder import AutoSwarmBuilder
@ -128,7 +342,9 @@ from swarms.structs.auto_swarm_builder import AutoSwarmBuilder
# Initialize the swarm builder # Initialize the swarm builder
swarm = AutoSwarmBuilder( swarm = AutoSwarmBuilder(
name="Multi-Task Swarm", name="Multi-Task Swarm",
description="A swarm capable of handling multiple diverse tasks" description="A swarm capable of handling multiple diverse tasks",
max_loops=2,
interactive=True
) )
# Define multiple tasks # Define multiple tasks
@ -140,40 +356,92 @@ tasks = [
# Run the swarm on all tasks # Run the swarm on all tasks
results = swarm.batch_run(tasks) results = swarm.batch_run(tasks)
# Process results
for i, result in enumerate(results):
print(f"Task {i+1} completed: {result}")
```
### Example 6: Interactive Mode with Custom Parameters
```python
from swarms.structs.auto_swarm_builder import AutoSwarmBuilder
# Initialize with interactive mode and custom settings
swarm = AutoSwarmBuilder(
name="Interactive Swarm",
description="An interactive swarm for real-time collaboration",
model_name="claude-3-sonnet-20240229",
max_tokens=16000,
interactive=True,
generate_router_config=True,
verbose=True
)
# Run with interactive capabilities
result = swarm.run(
"Help me design a user interface for a mobile app that helps people track their fitness goals"
)
``` ```
## Best Practices ## Best Practices
!!! tip "Task Definition" !!! tip "Task Definition"
- Provide clear, specific task descriptions - Provide clear, specific task descriptions
- Include any relevant context or constraints - Include any relevant context or constraints
- Specify expected output format if needed - Specify expected output format if needed
- Break complex tasks into smaller, manageable components
!!! note "Configuration" !!! note "Configuration"
- Set appropriate `max_loops` based on task complexity - Set appropriate `max_loops` based on task complexity
- Use `verbose=True` during development for debugging - Use `verbose=True` during development for debugging
- Choose the right `execution_type` for your use case:
- Consider using `random_models=True` for diverse agent capabilities - Use `"return-agents"` for direct agent interaction
- Use `"return-agent-configurations"` for inspection
- Use `"return-swarm-router-config"` for configuration analysis
- Set `max_tokens` appropriately based on expected response length
- Use `interactive=True` for real-time collaboration scenarios
!!! note "Model Selection"
- Choose appropriate `model_name` based on task requirements
- Consider model capabilities and token limits
- Use more powerful models for complex reasoning tasks
- Balance performance with cost considerations
!!! warning "Error Handling" !!! warning "Error Handling"
- The class includes comprehensive error handling - The class includes comprehensive error handling
- All methods include try-catch blocks with detailed logging - All methods include try-catch blocks with detailed logging
- Errors are propagated with full stack traces for debugging - Errors are propagated with full stack traces for debugging
- Always handle exceptions in your calling code
!!! info "Performance Optimization"
- Use `batch_run()` for processing multiple similar tasks
- Consider using `generate_router_config=True` for complex workflows
- Monitor token usage with `max_tokens` parameter
- Use appropriate `swarm_type` for your specific use case
## Notes ## Notes
!!! info "Architecture" !!! info "Architecture"
- The AutoSwarmBuilder uses a sophisticated boss agent system with comprehensive system prompts
- The AutoSwarmBuilder uses a sophisticated boss agent system to coordinate tasks - Agents are created dynamically based on task requirements using AI-powered analysis
- The system supports multiple execution types for different use cases
- Agents are created dynamically based on task requirements - Built-in logging and error handling with detailed traceback information
- Results are returned in structured formats (agents, configurations, or execution results)
- The system includes built-in logging and error handling - Supports various multi-agent architecture patterns through SwarmRouter
- Uses LiteLLM for flexible model support and response formatting
- Results are returned in a structured format for easy processing
!!! info "Dependencies"
- Requires `loguru` for logging
- Uses `pydantic` for data validation and configuration
- Integrates with `swarms.structs.agent.Agent` for individual agents
- Uses `swarms.structs.swarm_router.SwarmRouter` for coordination
- Leverages `swarms.utils.litellm_wrapper.LiteLLM` for LLM interactions
!!! info "System Prompt"
- The boss agent uses a comprehensive system prompt that includes:
- Multi-agent architecture design principles
- Agent creation guidelines and best practices
- Support for various swarm types and patterns
- Quality assurance and governance frameworks
- Error handling and recovery procedures

21
examples/demos/apps/hiring_swarm.py
Unescape View File

@ -13,7 +13,9 @@ from typing import List
from swarms.structs.agent import Agent from swarms.structs.agent import Agent
from swarms.structs.conversation import Conversation from swarms.structs.conversation import Conversation
from swarms.structs.ma_utils import set_random_models_for_agents from swarms.structs.ma_utils import set_random_models_for_agents
from swarms.utils.history_output_formatter import history_output_formatter from swarms.utils.history_output_formatter import (
history_output_formatter,
)
# System prompts for each agent # System prompts for each agent
@ -131,6 +133,7 @@ Provide an employee engagement report:
5. Plan for ongoing engagement efforts 5. Plan for ongoing engagement efforts
""" """
class HiringSwarm: class HiringSwarm:
def __init__( def __init__(
self, self,
@ -157,8 +160,8 @@ class HiringSwarm:
self.conversation.add( self.conversation.add(
role=self.user_name, role=self.user_name,
content=f"Company: {self.name}\n" content=f"Company: {self.name}\n"
f"Description: {self.description}\n" f"Description: {self.description}\n"
f"Job Role: {self.job_role}" f"Job Role: {self.job_role}",
) )
def _initialize_agents(self) -> List[Agent]: def _initialize_agents(self) -> List[Agent]:
@ -232,7 +235,9 @@ class HiringSwarm:
) )
def interview_coordination(self): def interview_coordination(self):
olivia_agent = self.find_agent_by_name("Interview-Coordinator") olivia_agent = self.find_agent_by_name(
"Interview-Coordinator"
)
olivia_output = olivia_agent.run( olivia_output = olivia_agent.run(
f"History: {self.conversation.get_str()}\n" f"History: {self.conversation.get_str()}\n"
f"Schedule and coordinate interviews for shortlisted {self.job_role} candidates, manage logistics, and collect feedback." f"Schedule and coordinate interviews for shortlisted {self.job_role} candidates, manage logistics, and collect feedback."
@ -242,7 +247,9 @@ class HiringSwarm:
) )
def onboarding_preparation(self): def onboarding_preparation(self):
nathan_agent = self.find_agent_by_name("Onboarding-Specialist") nathan_agent = self.find_agent_by_name(
"Onboarding-Specialist"
)
nathan_output = nathan_agent.run( nathan_output = nathan_agent.run(
f"History: {self.conversation.get_str()}\n" f"History: {self.conversation.get_str()}\n"
f"Prepare onboarding materials and schedule, coordinate setup, and organize training for the new {self.job_role} hire." f"Prepare onboarding materials and schedule, coordinate setup, and organize training for the new {self.job_role} hire."
@ -278,6 +285,7 @@ class HiringSwarm:
self.conversation, type=self.output_type self.conversation, type=self.output_type
) )
def main(): def main():
# Initialize the swarm # Initialize the swarm
hiring_swarm = HiringSwarm( hiring_swarm = HiringSwarm(
@ -302,5 +310,6 @@ def main():
# Run the swarm # Run the swarm
hiring_swarm.run(task=sample_task) hiring_swarm.run(task=sample_task)
if __name__ == "__main__": if __name__ == "__main__":
main() main()

1
heavy_swarm.py
Unescape View File

@ -8,7 +8,6 @@ swarm = HeavySwarm(
question_agent_model_name="gpt-4.1", question_agent_model_name="gpt-4.1",
loops_per_agent=1, loops_per_agent=1,
agent_prints_on=False, agent_prints_on=False,
# worker_tools=[exa_search],
random_loops_per_agent=False, random_loops_per_agent=False,
) )

24
swarms/structs/auto_swarm_builder.py
Unescape View File

@ -212,15 +212,19 @@ class AutoSwarmBuilder:
"""A class that automatically builds and manages swarms of AI agents. """A class that automatically builds and manages swarms of AI agents.
This class handles the creation, coordination and execution of multiple AI agents working This class handles the creation, coordination and execution of multiple AI agents working
together as a swarm to accomplish complex tasks. It uses a boss agent to delegate work together as a swarm to accomplish complex tasks. It uses a sophisticated boss agent system
and create new specialized agents as needed. to delegate work and create new specialized agents as needed.
Args: Args:
name (str): The name of the swarm name (str): The name of the swarm. Defaults to "auto-swarm-builder".
description (str): A description of the swarm's purpose description (str): A description of the swarm's purpose. Defaults to "Auto Swarm Builder".
verbose (bool, optional): Whether to output detailed logs. Defaults to True. verbose (bool): Whether to output detailed logs. Defaults to True.
max_loops (int, optional): Maximum number of execution loops. Defaults to 1. max_loops (int): Maximum number of execution loops. Defaults to 1.
random_models (bool, optional): Whether to use random models for agents. Defaults to True. model_name (str): The LLM model to use for the boss agent. Defaults to "gpt-4.1".
generate_router_config (bool): Whether to generate router configuration. Defaults to False.
interactive (bool): Whether to enable interactive mode. Defaults to False.
max_tokens (int): Maximum tokens for the LLM responses. Defaults to 8000.
execution_type (str): Type of execution to perform. Defaults to "return-agents".
""" """
def __init__( def __init__(
@ -242,7 +246,11 @@ class AutoSwarmBuilder:
description (str): A description of the swarm's purpose description (str): A description of the swarm's purpose
verbose (bool): Whether to output detailed logs verbose (bool): Whether to output detailed logs
max_loops (int): Maximum number of execution loops max_loops (int): Maximum number of execution loops
random_models (bool): Whether to use random models for agents model_name (str): The LLM model to use for the boss agent
generate_router_config (bool): Whether to generate router configuration
interactive (bool): Whether to enable interactive mode
max_tokens (int): Maximum tokens for the LLM responses
execution_type (str): Type of execution to perform
""" """
self.name = name self.name = name
self.description = description self.description = description

Write Preview
Loading…
Cancel
Save