From ee5ffa181e2f9480f0f959e0d6536967b827ba3d Mon Sep 17 00:00:00 2001 From: Kye Gomez Date: Fri, 5 Dec 2025 18:07:40 -0500 Subject: [PATCH] [RoundRobin][Improve round robin swarm with better communication flow][++docs --- docs/swarms/structs/round_robin_swarm.md | 199 ++++++++++++++++++++--- swarms/structs/round_robin.py | 38 ++++- 2 files changed, 214 insertions(+), 23 deletions(-) diff --git a/docs/swarms/structs/round_robin_swarm.md b/docs/swarms/structs/round_robin_swarm.md index 0a8215ea..f60d1172 100644 --- a/docs/swarms/structs/round_robin_swarm.md +++ b/docs/swarms/structs/round_robin_swarm.md @@ -2,6 +2,8 @@ The `RoundRobinSwarm` class is designed to manage and execute tasks among multiple agents in a round-robin fashion. This approach ensures that each agent in a swarm receives an equal opportunity to execute tasks, which promotes fairness and efficiency in distributed systems. It is particularly useful in environments where collaborative, sequential task execution is needed among various agents. +This swarm implements an AutoGen-style communication pattern where agents are shuffled randomly each loop for varied interaction patterns. Each agent receives the full conversation context to build upon others' responses. + ## What is Round-Robin? Round-robin is a scheduling technique commonly used in computing for managing processes in shared systems. It involves assigning a fixed time slot to each process and cycling through all processes in a circular order without prioritization. In the context of swarms of agents, this method ensures equitable distribution of tasks and resource usage among all agents. @@ -10,12 +12,33 @@ Round-robin is a scheduling technique commonly used in computing for managing pr In swarms, `RoundRobinSwarm` utilizes the round-robin scheduling to manage tasks among agents like software components, autonomous robots, or virtual entities. This strategy is beneficial where tasks are interdependent or require sequential processing. +## Architecture + +```mermaid +graph LR + User[Task] --> A1[Agent 1] + A1 --> A2[Agent 2] + A2 --> A3[Agent 3] + A3 --> A1 + A3 --> Output[Result] +``` + +Each agent receives the task with full conversation history, responds, then passes context to the next agent. This cycle repeats for `max_loops` iterations. + ## Class Attributes -- `agents (List[Agent])`: List of agents participating in the swarm. -- `verbose (bool)`: Enables or disables detailed logging of swarm operations. -- `max_loops (int)`: Limits the number of times the swarm cycles through all agents. -- `index (int)`: Maintains the current position in the agent list to ensure round-robin execution. +| Attribute | Type | Description | +|-----------|------|-------------| +| `name` | `str` | Name of the swarm. | +| `description` | `str` | Description of the swarm's purpose. | +| `agents` | `List[Agent]` | List of agents participating in the swarm. | +| `verbose` | `bool` | Enables or disables detailed logging of swarm operations. | +| `max_loops` | `int` | Limits the number of times the swarm cycles through all agents. | +| `callback` | `callable` | Callback function executed after each loop. | +| `index` | `int` | Maintains the current position in the agent list to ensure round-robin execution. | +| `max_retries` | `int` | Maximum number of retries for agent execution. | +| `output_type` | `OutputType` | Type of output format (e.g., "final", "all", "json"). | +| `conversation` | `Conversation` | Conversation history for the swarm. | ## Methods @@ -24,30 +47,92 @@ In swarms, `RoundRobinSwarm` utilizes the round-robin scheduling to manage tasks Initializes the swarm with the provided list of agents, verbosity setting, and operational parameters. **Parameters:** -| Parameter | Type | Description | -|-------------|---------------------|-----------------------------------------------------| -| agents | List[Agent], optional | List of agents in the swarm. | -| verbose | bool | Boolean flag for detailed logging. | -| max_loops | int | Maximum number of execution cycles. | -| callback | Callable, optional | Function called after each loop. | + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `name` | `str` | `"RoundRobinSwarm"` | Name of the swarm. | +| `description` | `str` | `"A swarm implementation..."` | Description of the swarm's purpose. | +| `agents` | `List[Agent]` | **Required** | List of agents in the swarm. | +| `verbose` | `bool` | `False` | Boolean flag for detailed logging. | +| `max_loops` | `int` | `1` | Maximum number of execution cycles. | +| `callback` | `callable` | `None` | Function called after each loop with `(loop_index, result)` arguments. | +| `max_retries` | `int` | `3` | Maximum number of retries for agent execution. | +| `output_type` | `OutputType` | `"final"` | Type of output format. | + +**Raises:** + +- `ValueError`: If no agents are provided during initialization. + +--- ### `run` -Executes a specified task across all agents in a round-robin manner, cycling through each agent repeatedly for the number of specified loops. +Executes a specified task across all agents in a randomized round-robin manner, cycling through each agent repeatedly for the number of specified loops. + +```python +def run(self, task: str, *args, **kwargs) -> Union[str, dict, list] +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `task` | `str` | The task string to be executed by the agents. | +| `*args` | `Any` | Variable length argument list passed to each agent. | +| `**kwargs` | `Any` | Arbitrary keyword arguments passed to each agent. | + +**Returns:** + +| Type | Description | +|------|-------------| +| `Union[str, dict, list]` | The result of the task execution in the format specified by `output_type`. | + +**Raises:** + +- `ValueError`: If no agents are configured for the swarm. + +- `Exception`: If an exception occurs during task execution. **Conceptual Behavior:** | Step | Description | |------|-------------| -| 1 | Distribute the task sequentially among all agents starting from the current index. | -| 2 | Each agent processes the task and potentially modifies it or produces new output. | -| 3 | After an agent completes its part of the task, the index moves to the next agent. | -| 4 | This cycle continues until the specified maximum number of loops is completed. | -| 5 | Optionally, a callback function can be invoked after each loop to handle intermediate results or perform additional actions. | +| 1 | Add the initial task to the conversation history. | +| 2 | Shuffle agents randomly for varied interaction patterns. | +| 3 | Each agent receives the full conversation context and processes the task. | +| 4 | Agents build upon insights from previous agents in the conversation. | +| 5 | After an agent completes its part, its response is added to the conversation. | +| 6 | This cycle continues until the specified maximum number of loops is completed. | +| 7 | Optionally, a callback function is invoked after each loop. | +| 8 | Returns the formatted conversation history based on `output_type`. | + +--- + +### `run_batch` + +Execute multiple tasks sequentially through the round-robin swarm. Each task is processed independently through the full round-robin execution cycle. + +```python +def run_batch(self, tasks: List[str]) -> List[Union[str, dict, list]] +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `tasks` | `List[str]` | A list of task strings to be executed. | + +**Returns:** + +| Type | Description | +|------|-------------| +| `List[Union[str, dict, list]]` | A list of results, one for each task, in the format specified by `output_type`. | ## Examples -In this example, `RoundRobinSwarm` is used to distribute network requests evenly among a group of servers. This is common in scenarios where load balancing is crucial for maintaining system responsiveness and scalability. +### Basic Usage with `run` + +In this example, `RoundRobinSwarm` is used to distribute a sales task among a group of specialized agents. Each agent contributes their unique perspective to the collaborative output. ```python from swarms import Agent, RoundRobinSwarm @@ -78,15 +163,89 @@ sales_agent3 = Agent( ) # Initialize the swarm with sales agents -sales_swarm = RoundRobinSwarm(agents=[sales_agent1, sales_agent2, sales_agent3], verbose=True) +sales_swarm = RoundRobinSwarm( + name="SalesTeamSwarm", + description="A collaborative sales team for generating comprehensive sales content", + agents=[sales_agent1, sales_agent2, sales_agent3], + verbose=True, + max_loops=2, + output_type="final", +) # Define a sales task task = "Generate a sales email for an accountant firm executive to sell swarms of agents to automate their accounting processes." -out = sales_swarm.run(task) -print(out) +# Run the task +result = sales_swarm.run(task) +print(result) ``` +### Batch Processing with `run_batch` + +Use `run_batch` when you need to process multiple independent tasks through the swarm. Each task is executed separately with full round-robin collaboration. + +```python +from swarms import Agent, RoundRobinSwarm + +# Define research agents +researcher1 = Agent( + agent_name="Technical Researcher", + system_prompt="You are a technical researcher who analyzes topics from a technical perspective.", + model_name="gpt-4.1", + max_loops=1, +) + +researcher2 = Agent( + agent_name="Market Researcher", + system_prompt="You are a market researcher who analyzes topics from a business and market perspective.", + model_name="gpt-4.1", + max_loops=1, +) + +# Initialize the swarm +research_swarm = RoundRobinSwarm( + name="ResearchSwarm", + agents=[researcher1, researcher2], + verbose=True, + max_loops=1, + output_type="json", +) + +# Define multiple research tasks +tasks = [ + "Analyze the current state of AI in healthcare.", + "Research the impact of automation on manufacturing.", + "Evaluate emerging trends in renewable energy.", +] + +# Run all tasks and get results +results = research_swarm.run_batch(tasks) + +# Process each result +for i, result in enumerate(results): + print(f"Task {i + 1} Result:") + print(result) + print("-" * 50) +``` + +### Using Callbacks + +You can use callbacks to monitor or process intermediate results after each loop: + +```python +def my_callback(loop_index: int, result: str): + """Called after each loop completes.""" + print(f"Loop {loop_index + 1} completed") + print(f"Latest result: {result[:100]}...") # Print first 100 chars + +swarm = RoundRobinSwarm( + agents=[agent1, agent2, agent3], + max_loops=3, + callback=my_callback, +) + +result = swarm.run("Analyze this complex topic from multiple perspectives.") +``` ## Conclusion diff --git a/swarms/structs/round_robin.py b/swarms/structs/round_robin.py index 795d104b..fb9d086b 100644 --- a/swarms/structs/round_robin.py +++ b/swarms/structs/round_robin.py @@ -18,10 +18,14 @@ class RoundRobinSwarm: """ A swarm implementation that executes tasks in a round-robin fashion. + This swarm implements an AutoGen-style communication pattern where agents + are shuffled randomly each loop for varied interaction patterns. Each agent + receives the full conversation context to build upon others' responses. + Args: name (str): Name of the swarm. Defaults to "RoundRobinSwarm". description (str): Description of the swarm's purpose. - agents (List[Agent], optional): List of agents in the swarm. Defaults to None. + agents (List[Agent]): List of agents in the swarm. Required. verbose (bool, optional): Flag to enable verbose mode. Defaults to False. max_loops (int, optional): Maximum number of loops to run. Defaults to 1. callback (callable, optional): Callback function to be called after each loop. Defaults to None. @@ -29,14 +33,25 @@ class RoundRobinSwarm: output_type (OutputType, optional): Type of output format. Defaults to "final". Attributes: + name (str): Name of the swarm. + description (str): Description of the swarm's purpose. agents (List[Agent]): List of agents in the swarm. verbose (bool): Flag to enable verbose mode. max_loops (int): Maximum number of loops to run. + callback (callable): Callback function executed after each loop. index (int): Current index of the agent being executed. + max_retries (int): Maximum number of retries for agent execution. + output_type (OutputType): Type of output format. conversation (Conversation): Conversation history for the swarm. Methods: - run(task: str, *args, **kwargs) -> Any: Executes the given task on the agents in a round-robin fashion. + run(task: str, *args, **kwargs) -> Union[str, dict, list]: + Executes the given task on the agents in a round-robin fashion. + run_batch(tasks: List[str]) -> List: + Executes multiple tasks sequentially, returning results for each. + + Raises: + ValueError: If no agents are provided during initialization. """ @@ -217,5 +232,22 @@ class RoundRobinSwarm: logger.error(f"Round-robin execution failed: {str(e)}") raise - def run_batch(self, tasks: List[str]): + def run_batch(self, tasks: List[str]) -> List[Union[str, dict, list]]: + """ + Execute multiple tasks sequentially through the round-robin swarm. + + Each task is processed independently through the full round-robin + execution cycle, with agents collaborating on each task in turn. + + Args: + tasks (List[str]): A list of task strings to be executed. + + Returns: + List[Union[str, dict, list]]: A list of results, one for each task, + in the format specified by output_type. + + Example: + >>> swarm = RoundRobinSwarm(agents=[agent1, agent2]) + >>> results = swarm.run_batch(["Task 1", "Task 2", "Task 3"]) + """ return [self.run(task) for task in tasks]