BatchedGridWorkflow

Overview

The BatchedGridWorkflow is a multi-agent orchestration pattern that executes tasks in a batched grid format, where each agent processes a different task simultaneously. This workflow is particularly useful for parallel processing scenarios where you have multiple agents and multiple tasks that can be distributed across them. The BatchedGridWorkflow provides a structured approach to:

Execute multiple tasks across multiple agents in parallel
Re-run the same task grid for a set number of loops
Handle error scenarios gracefully
Control the number of execution iterations

Architecture

Installation

pip install -U swarms

Key Features

Feature	Description
Parallel Execution	Multiple agents work on different tasks simultaneously
Error Handling	Comprehensive error logging and exception handling
Configurable Loops	Control the number of execution iterations
Agent Flexibility	Supports any agent type that implements the `AgentType` interface

Attributes

str

default:"auto-generated"

Unique identifier for the workflow. Auto-generated via generate_id("batched-grid-workflow") if not provided, producing batched-grid-workflow-<32 hex chars>.

str

default:"BatchedGridWorkflow"

Name of the workflow.

str

Description of what the workflow does.

List[AgentType]

default:"None"

List of agents to execute tasks.

int

default:"1"

Maximum number of execution loops to run. Must be a positive integer, or ValueError is raised at construction.

BatchedGridWorkflow has no output_type parameter and keeps no Conversation. run() returns each agent’s raw run() output.

Methods

step()

Execute one step of the batched grid workflow. Pairs each agent with the task at the same index and runs all agent/task pairs concurrently via batched_grid_agent_execution. The number of tasks must match the number of agents, or ValueError is raised.

def step(self, tasks: List[str])

Parameters:

tasks (List[str]): List of tasks to execute, one per agent (must be the same length as agents)

Returns: List[Any] - Results from each agent, in the same order as agents. If an agent fails, the exception is included in the results.

run()

Run the batched grid workflow with the given tasks for max_loops iterations. Every loop re-sends the same original tasks; outputs are not fed back in as new tasks, though each agent keeps its own conversation memory between loops. This is the main entry point that includes error handling (logs and re-raises any exception).

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

Parameters:

tasks (List[str]): List of tasks to execute, one per agent

Returns: List[List[Any]] - A list with one entry per loop iteration; each entry is the list of per-agent results returned by step() for that loop.

run_()

Internal method that runs the workflow without the top-level try/except error handling.

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

Parameters:

tasks (List[str]): List of tasks to execute, one per agent

Returns: List[List[Any]] - A list with one entry per loop iteration; each entry is the list of per-agent results returned by step() for that loop.

Usage Examples

Basic Usage

from swarms import Agent, BatchedGridWorkflow

# One agent per task; tasks run concurrently, so don't reuse one instance twice
gold_agent = Agent(
    agent_name="Gold-ETF-Agent",
    agent_description="Researches and recommends gold ETFs.",
    model_name="claude-sonnet-4-6",
    max_loops=1,
)

energy_agent = Agent(
    agent_name="Energy-ETF-Agent",
    agent_description="Researches and recommends US energy ETFs.",
    model_name="claude-sonnet-4-6",
    max_loops=1,
)

# Create workflow with default settings
workflow = BatchedGridWorkflow(agents=[gold_agent, energy_agent])

# Define simple tasks
tasks = [
    "What are the best GOLD ETFs?",
    "What are the best american energy ETFs?",
]

# Run the workflow
result = workflow.run(tasks)

print(result)

Multi-Loop Execution

from swarms import Agent, BatchedGridWorkflow

# Create workflow with multiple loops
workflow = BatchedGridWorkflow(
    agents=[agent1, agent2, agent3],
    max_loops=3,
)

# Execute tasks with multiple iterations
tasks = ["Task 1", "Task 2", "Task 3"]
result = workflow.run(tasks)

Error Handling

The workflow includes comprehensive error handling:

Validation: Ensures max_loops is a positive integer, and that each step gets one task per agent
Agent Errors: An agent that raises during a step has its exception returned in that step’s results instead of stopping the other agents
Execution Errors: Catches, logs and re-raises any other exception during execution
Detailed Logging: Provides detailed error information including traceback

Best Practices

Best Practice	Description
Agent Selection	Choose agents with complementary capabilities for diverse task processing
Task Distribution	Ensure tasks are well-distributed and can be processed independently
Loop Configuration	Each loop re-sends the original tasks; an agent sees its earlier loops only through its own conversation memory
Error Monitoring	Monitor logs for execution errors and adjust agent configurations accordingly
Resource Management	Consider computational resources when setting up multiple agents

Use Cases

Use Case	Description
Content Generation	Multiple writers working on different topics
Data Analysis	Different analysts processing various datasets
Research Tasks	Multiple researchers investigating different aspects of a problem
Parallel Processing	Any scenario requiring simultaneous task execution across multiple agents

Source Code

View the source code on GitHub

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

BatchedGridWorkflow

Overview

Architecture

Installation

Key Features

Attributes

Methods

step()

run()

run_()

Usage Examples

Basic Usage

Multi-Loop Execution

Error Handling

Best Practices

Use Cases

Source Code

​Overview

​Architecture

​Installation

​Key Features

​Attributes

​Methods

​step()

​run()

​run_()

​Usage Examples

​Basic Usage

​Multi-Loop Execution

​Error Handling

​Best Practices

​Use Cases

​Source Code

Overview

Architecture

Installation

Key Features

Attributes

Methods

step()

run()

run_()

Usage Examples

Basic Usage

Multi-Loop Execution

Error Handling

Best Practices

Use Cases

Source Code