> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.world/llms.txt
> Use this file to discover all available pages before exploring further.
# BatchedGridWorkflow
> Multi-agent orchestration pattern that executes tasks in a batched grid format with parallel processing
## 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
* Manage conversation state across execution loops
* Handle error scenarios gracefully
* Control the number of execution iterations
## Architecture
```mermaid theme={null}
graph TD
A[Input Tasks] --> B[BatchedGridWorkflow]
B --> C[Initialize Agents]
C --> D[Create Conversation]
D --> E[Start Execution Loop]
E --> F[Distribute Tasks to Agents]
F --> G[Agent 1: Task 1]
F --> H[Agent 2: Task 2]
F --> I[Agent N: Task N]
G --> J[Collect Results]
H --> J
I --> J
J --> K[Update Conversation]
K --> L{More Loops?}
L -->|Yes| E
L -->|No| M[Return Final Results]
M --> N[Output]
```
## Installation
```bash theme={null}
pip install -U swarms
```
## Key Features
| Feature | Description |
| --------------------------- | ----------------------------------------------------------------- |
| **Parallel Execution** | Multiple agents work on different tasks simultaneously |
| **Conversation Management** | Maintains conversation state across execution loops |
| **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
Unique identifier for the workflow.
Name of the workflow.
Description of what the workflow does.
List of agents to execute tasks.
Arguments for the conversation.
Maximum number of execution loops to run (must be >= 1).
## Methods
### step()
Execute one step of the batched grid workflow.
```python theme={null}
def step(self, tasks: List[str])
```
**Parameters:**
* `tasks` (List\[str]): List of tasks to execute
**Returns:** Output from the batched grid agent execution
### run()
Run the batched grid workflow with the given tasks. This is the main entry point that includes error handling.
```python theme={null}
def run(self, tasks: List[str]) -> str
```
**Parameters:**
* `tasks` (List\[str]): List of tasks to execute
**Returns:** `str` - The final conversation string after all loops
### run\_()
Internal method that runs the workflow without error handling.
```python theme={null}
def run_(self, tasks: List[str]) -> str
```
**Parameters:**
* `tasks` (List\[str]): List of tasks to execute
**Returns:** `str` - The final conversation string after all loops
## Usage Examples
### Basic Usage
```python theme={null}
from swarms import Agent, BatchedGridWorkflow
# Initialize the ETF-focused agent
agent = Agent(
agent_name="ETF-Research-Agent",
agent_description="Specialized agent for researching, analyzing, and recommending Exchange-Traded Funds (ETFs) across various sectors and markets.",
model_name="claude-sonnet-4-20250514",
dynamic_temperature_enabled=True,
max_loops=1,
dynamic_context_window=True,
)
# Create workflow with default settings
workflow = BatchedGridWorkflow(agents=[agent, 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
```python theme={null}
from swarms import Agent, BatchedGridWorkflow
# Create workflow with multiple loops
workflow = BatchedGridWorkflow(
agents=[agent1, agent2, agent3],
max_loops=3,
conversation_args={"message_id_on": True}
)
# 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
* **Execution Errors**: Catches and logs exceptions 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** | Use multiple loops when iterative refinement is needed |
| **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](https://github.com/kyegomez/swarms/blob/master/swarms/structs/batched_grid_workflow.py)