SpreadSheetSwarm

Overview

The SpreadSheetSwarm processes tasks concurrently across multiple agents and automatically saves execution metadata to CSV files. It supports loading agent configurations from CSV files and running tasks either from configuration or on-demand.

SpreadSheetSwarm emits OpenTelemetry spans: one when it is constructed, and one for each run() and run_from_config() call. See Telemetry to turn tracing off.

Installation

pip install -U swarms

Attributes

str

default:"Spreadsheet-Swarm"

The name of the swarm

str

default:"A swarm that processes tasks concurrently..."

The description of the swarm

List[Agent]

default:"None"

The agents participating in the swarm. Required — the constructor runs a reliability check before any CSV loading happens, so a non-empty agents list must be supplied even if load_path is also set

bool

default:"True"

Whether to save results. When True, each run appends rows to the CSV at save_file_path and writes a JSON metadata file to the swarm’s workspace directory. When False, nothing is written to disk

str

default:"None"

The CSV file path. When None, it defaults to spreadsheet_swarm_run_id_<hex>.csv inside the swarm’s workspace directory ($WORKSPACE_DIR/swarms/SpreadSheetSwarm/<name>-<timestamp>/), falling back to WORKSPACE_DIR or the current directory when autosave is off. An explicit path is kept as given

int

default:"1"

The number of times to repeat the swarm tasks. Loops run one after another; within a loop every agent runs once, concurrently with the others. Each agent’s conversation is reset before every loop, so loops are independent samples rather than refinements of the previous loop

str

default:"None"

Path to a CSV file of agent configurations. Call load_from_csv() explicitly after construction to build agents and per-agent tasks from it before calling run_from_config()

bool

default:"False"

Enable verbose logging

Methods

run()

Run the swarm with the specified task.

def run(self, task: str = None, *args, **kwargs) -> dict

Parameters:

task (str): The task every agent runs. If None and tasks were loaded with load_from_csv(), it calls run_from_config() instead

Returns: Dictionary containing run summary with outputs and metadata Raises: Re-raises any exception from the run after logging it

run_from_config()

Run each agent that has a configured task, concurrently. Agents whose agent_name has no entry in the loaded tasks are skipped.

def run_from_config(self) -> dict

Returns: Dictionary containing execution summary

load_from_csv()

Load agent configurations from the CSV at load_path. For each row it builds a new Agent, appends it to agents, and records the row’s task under its agent_name.

def load_from_csv(self)

Expected CSV format:

agent_name,description,system_prompt,task,model_name,max_loops

agent_name, description, system_prompt and task are required. The description column must be present but is not applied to the agent’s agent_description. model_name defaults to "openai/gpt-4o" when the column is missing, and max_loops defaults to 1. Optional user_name and stopping_token columns are also read. Errors while loading are logged, not raised.

export_to_json()

Export the swarm outputs to JSON.

def export_to_json(self) -> str

Returns: JSON string representation of swarm outputs

data_to_json_file()

Save the swarm outputs (via export_to_json()) to a JSON file in the workspace directory. Called automatically after each run when autosave=True.

def data_to_json_file(self)

Returns: None. Writes the JSON metadata file to disk.

Usage Examples

Basic Usage with Agents

from swarms import Agent, SpreadSheetSwarm

# Create agents
agents = [
    Agent(
        agent_name="Research-Agent",
        system_prompt="You are a research agent.",
        model_name="openai/gpt-5.4",
    ),
    Agent(
        agent_name="Analysis-Agent",
        system_prompt="You are an analysis agent.",
        model_name="openai/gpt-5.4",
    ),
]

# Create swarm
swarm = SpreadSheetSwarm(
    name="My-Swarm",
    agents=agents,
    max_loops=1,
    autosave=True
)

# Run with a task
result = swarm.run("Analyze the latest AI trends")

print(result)

Load from CSV Configuration

agents must be provided at construction. The constructor runs a reliability check before any CSV loading occurs, so calling SpreadSheetSwarm(load_path="agents_config.csv", ...) without agents raises ValueError("No agents are provided."). Pass real Agent instances in agents, then call load_from_csv() explicitly.load_from_csv() builds a new agent for every CSV row and appends it to agents. It does not reuse the agents you passed. If a passed agent shares an agent_name with a CSV row, run_from_config() runs both the passed agent and the new one on that row’s task.

Create a CSV file (agents_config.csv) mapping each agent name to a task:

agent_name,description,system_prompt,task
Research-Agent,Research specialist,You are a research agent,Research quantum computing
Analysis-Agent,Data analyst,You are an analysis agent,Analyze the research findings

Then construct with a seed agent, load the CSV, and run:

from swarms import Agent, SpreadSheetSwarm

# Satisfies the constructor check; it has no CSV task, so run_from_config() skips it
seed = Agent(agent_name="Seed-Agent", model_name="gpt-5.4", max_loops=1)

swarm = SpreadSheetSwarm(
    name="CSV-Swarm",
    agents=[seed],
    load_path="agents_config.csv",
    max_loops=1
)

# Builds one Agent per row and records each row's task
swarm.load_from_csv()

result = swarm.run_from_config()

Multiple Loops

# Three sequential loops, each agent starts every loop from a fresh conversation
swarm = SpreadSheetSwarm(
    agents=agents,
    max_loops=3
)

result = swarm.run("Process this task multiple times")

With max_loops=3 a run takes about three times as long as a single loop, and outputs holds one row per agent per loop.

Custom Save Path

swarm = SpreadSheetSwarm(
    name="Custom-Swarm",
    agents=agents,
    save_file_path="./results/swarm_outputs.csv",
    autosave=True
)

result = swarm.run("Custom task")

Export Results

# Run swarm
result = swarm.run("Some task")

# Export to JSON
json_output = swarm.export_to_json()
print(json_output)

# Results are automatically saved to CSV if autosave=True

Output Format

The run() method returns a dictionary:

{
    "run_id": "spreadsheet_swarm_run_abc123",
    "name": "My-Swarm",
    "description": "A swarm that processes tasks...",
    "start_time": "2026-10-02T12:00:00.123456",
    "end_time": "2026-10-02T12:05:00.654321",
    "tasks_completed": 6,
    "number_of_agents": 3,
    "outputs": [
        {
            "agent_name": "Research-Agent",
            "task": "Analyze the latest AI trends",
            "result": "...",
            "timestamp": "2026-10-02T12:01:00.246810"
        },
        # ... more outputs
    ]
}

start_time, end_time and each output’s timestamp are ISO 8601 strings recorded when the run starts, when it ends, and when each result is tracked.

outputs and tasks_completed are not reset between run() calls on the same instance. A second run returns the first run’s outputs too, and the CSV save writes every accumulated output again. Create a new SpreadSheetSwarm when you want a clean result set.

CSV Output Format

Results are automatically saved to CSV with these columns:

Run ID,Agent Name,Task,Result,Timestamp
abc-123,Research-Agent,Analyze trends,...,2026-10-02T12:00:00.123456
abc-123,Analysis-Agent,Analyze trends,...,2026-10-02T12:00:05.654321

The header row is written only when the file does not exist yet. Later saves append to it.

Features

Concurrent Execution: All agents run in parallel within each loop, and no agent is ever run by two threads at once
Automatic CSV Logging: All executions are logged to CSV files automatically
CSV Configuration: Load agent configurations from CSV files
Multiple Loops: Run each agent multiple times with max_loops
Workspace Integration: Automatically uses workspace directory from environment
JSON Export: Export results to JSON format
Metadata Tracking: Tracks timestamps, run IDs, and execution metadata
Telemetry: Emits OpenTelemetry spans for construction and each run

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

SpreadSheetSwarm

Overview

Installation

Attributes

Methods

run()

run_from_config()

load_from_csv()

export_to_json()

data_to_json_file()

Usage Examples

Basic Usage with Agents

Load from CSV Configuration

Multiple Loops

Custom Save Path

Export Results

Output Format

CSV Output Format

Features

​Overview

​Installation

​Attributes

​Methods

​run()

​run_from_config()

​load_from_csv()

​export_to_json()

​data_to_json_file()

​Usage Examples

​Basic Usage with Agents

​Load from CSV Configuration

​Multiple Loops

​Custom Save Path

​Export Results

​Output Format

​CSV Output Format

​Features

Overview

Installation

Attributes

Methods

run()

run_from_config()

load_from_csv()

export_to_json()

data_to_json_file()

Usage Examples

Basic Usage with Agents

Load from CSV Configuration

Multiple Loops

Custom Save Path

Export Results

Output Format

CSV Output Format

Features