AgentLoader

Overview

The AgentLoader class provides a unified interface for instantiating Agent objects from on-disk definitions. It supports three file formats and dispatches automatically based on the file extension.

Format	Extension	Backing loader
Markdown	`.md`	`load_agents_from_markdown`
YAML	`.yaml`	`create_agents_from_yaml`
CSV	`.csv`	`CSVAgentLoader`

Extensions are matched exactly: auto() does not accept .yml or upper-case extensions. Use this when you want agent definitions to live as data — checked into git, edited by humans, generated by tools — rather than hard-coded in Python.

Installation

pip install -U swarms

Constructor

from swarms import AgentLoader

loader = AgentLoader(concurrent=True)

bool

default:"True"

Stored as loader.concurrent. No method reads it; pass concurrent to load_agents_from_markdown() to control parallel loading.

Methods

auto()

Dispatch to the right loader based on file extension. The simplest entry point.

def auto(self, file_path: str, *args, **kwargs)

Parameters:

file_path (str): Path to .md, .yaml, or .csv file.
*args, **kwargs: Forwarded to the underlying loader.

Returns: Whatever the matching loader returns: a List[Agent] for Markdown and CSV, and the shape described under load_agents_from_yaml() for YAML. Raises: ValueError if the file extension is not .md, .yaml, or .csv.

load_single_agent()

Alias for auto() — loads a single file by dispatching on extension, and returns the same shape.

def load_single_agent(self, *args, **kwargs)

load_multiple_agents()

Apply auto() to a list of files. Each file may be a different format.

def load_multiple_agents(
    self,
    file_paths: List[str],
    *args,
    **kwargs,
) -> list

Parameters:

file_paths (List[str]): Paths to agent definition files.

Returns: One auto() result per input file, in order.

load_agent_from_markdown()

Load a single agent from a Markdown file.

def load_agent_from_markdown(
    self,
    file_path: str,
    **kwargs,
) -> Agent

load_agents_from_markdown()

Load multiple agents from one or more Markdown files.

def load_agents_from_markdown(
    self,
    file_paths: Union[str, List[str]],
    concurrent: bool = True,
    max_file_size_mb: float = 10.0,
    **kwargs,
) -> List[Agent]

Union[str, List[str]]

A single file, a directory (every *.md file in it), or a list of file paths.

bool

default:"True"

Load files in parallel when there is more than one. Agents are then returned in completion order.

float

default:"10.0"

Files above this size are skipped.

Any

Override the parsed configuration for every agent, for example model_name="gpt-5.4".

A file that fails to parse or build is logged and skipped. Each file needs YAML frontmatter and a non-empty body, which becomes the system prompt. The frontmatter keys read are name, description, model_name (or model), temperature, max_loops, mcp_url, and streaming_on. Markdown agents default to temperature=0.1 when the frontmatter sets none.

The parsed mcp_url field is typed as an integer, so a URL in the frontmatter fails validation and the file is skipped. Pass it as a keyword argument instead, e.g. load_agents_from_markdown("agents/", mcp_url="http://localhost:8000/sse").

load_agents_from_yaml()

Load agents from a single YAML file through create_agents_from_yaml.

def load_agents_from_yaml(
    self,
    yaml_file: str,
    return_type: ReturnTypes = "auto",
    **kwargs,
)

str

Path to the YAML definitions file. It needs an agents list and may have a swarm_architecture section.

ReturnTypes

default:"\"auto\""

Controls the return shape. One of "auto", "agents", "both", "swarm", "run_swarm", "tasks".

`return_type`	Returns
`"auto"`	A `SwarmRouter` when `swarm_architecture` is defined; otherwise one `Agent` if the file defines one agent, or a `List[Agent]`
`"agents"`	One `Agent` if the file defines one agent, otherwise a `List[Agent]`
`"both"`	A tuple of the `"auto"` result and the full agent list
`"swarm"`, `"run_swarm"`	Runs the `SwarmRouter` on `swarm_architecture.task` and returns its output
`"tasks"`	An empty list

"swarm" and "run_swarm" execute the swarm, which calls the model. They raise ValueError when the file has no swarm_architecture or no task.

load_many_agents_from_yaml()

Load agents from a list of YAML files with per-file return type control.

def load_many_agents_from_yaml(
    self,
    yaml_files: List[str],
    return_types: List[ReturnTypes] = ["auto"],
    **kwargs,
) -> list

Returns one load_agents_from_yaml() result per file. return_types needs one entry per file; the default ["auto"] covers a single file and raises IndexError for more.

load_agents_from_csv()

Load agents from a CSV file via CSVAgentLoader.

def load_agents_from_csv(
    self,
    csv_file: str,
    **kwargs,
) -> List[Agent]

**kwargs are accepted but ignored. Each row becomes one agent, built on up to 10 threads, so agents come back in completion order. Rows that fail validation are printed and skipped.

Column	Default when the column is absent
`model_name`	Required. Checked against LiteLLM’s model list
`agent_name`	`""`
`system_prompt`	`""`
`max_loops`	`1`
`autosave`	`true`
`dashboard`	`false`
`verbose`	`true`
`dynamic_temperature`	`true` (sets `dynamic_temperature_enabled`)
`saved_state_path`	`""`
`user_name`	`default_user`
`retry_attempts`	`3`
`context_length`	`200000`
`output_type`	`string`
`streaming`	`false` (sets `streaming_on`)

Boolean cells count as true only when they read true (any case).

parse_markdown_file()

Lower-level: parse a Markdown file via MarkdownAgentLoader without building an agent.

def parse_markdown_file(self, file_path: str) -> MarkdownAgentConfig

Returns the parsed configuration (a Pydantic model). Raises FileNotFoundError when the file is missing and ValueError when it has no frontmatter or fails validation.

Usage Examples

Auto-Dispatch on Extension

The shortest path — let auto() figure out the format.

from swarms import AgentLoader

loader = AgentLoader()

# Each file uses its own format; auto() picks the right loader
research_agents = loader.auto("agents/research_team.yaml")  # shape depends on return_type
support_agents = loader.auto("agents/support_squad.md")
sales_agents = loader.auto("agents/sales_reps.csv")

Load Many Files in One Call

from swarms import AgentLoader

loader = AgentLoader()

all_agents = loader.load_multiple_agents([
    "agents/support_squad.md",
    "agents/sales_reps.csv",
])

# One list of agents per file
for file_agents in all_agents:
    for agent in file_agents:
        print(agent.agent_name)

Markdown with Concurrency Control

from swarms import AgentLoader

loader = AgentLoader()

agents = loader.load_agents_from_markdown(
    file_paths=[
        "agents/researcher.md",
        "agents/writer.md",
        "agents/editor.md",
    ],
    concurrent=True,
    max_file_size_mb=5.0,
)

Compose with a Swarm

from swarms import AgentLoader, SequentialWorkflow

loader = AgentLoader()

# The file defines two or more agents
agents = loader.load_agents_from_yaml(
    "agents/research_pipeline.yaml", return_type="agents"
)

workflow = SequentialWorkflow(agents=agents, max_loops=1)
result = workflow.run("Summarize the current state of multi-agent research")

Source Code

View the source on GitHub.

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

Overview

Installation

Constructor

Methods

auto()

load_single_agent()

load_multiple_agents()

load_agent_from_markdown()

load_agents_from_markdown()

load_agents_from_yaml()

load_many_agents_from_yaml()

load_agents_from_csv()

parse_markdown_file()

Usage Examples

Auto-Dispatch on Extension

Load Many Files in One Call

Markdown with Concurrency Control

Compose with a Swarm

Source Code

​Overview

​Installation

​Constructor

​Methods

​auto()

​load_single_agent()

​load_multiple_agents()

​load_agent_from_markdown()

​load_agents_from_markdown()

​load_agents_from_yaml()

​load_many_agents_from_yaml()

​load_agents_from_csv()

​parse_markdown_file()

​Usage Examples

​Auto-Dispatch on Extension

​Load Many Files in One Call

​Markdown with Concurrency Control

​Compose with a Swarm

​Source Code

Overview

Installation

Constructor

Methods

auto()

load_single_agent()

load_multiple_agents()

load_agent_from_markdown()

load_agents_from_markdown()

load_agents_from_yaml()

load_many_agents_from_yaml()

load_agents_from_csv()

parse_markdown_file()

Usage Examples

Auto-Dispatch on Extension

Load Many Files in One Call

Markdown with Concurrency Control

Compose with a Swarm

Source Code