> ## 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.
# AgentLoader
> Loader class for creating Agent objects from Markdown, YAML, and CSV files
## 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
```bash theme={null}
pip install -U swarms
```
## Constructor
```python theme={null}
from swarms import AgentLoader
loader = AgentLoader(concurrent=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.
```python theme={null}
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.
```python theme={null}
def load_single_agent(self, *args, **kwargs)
```
### load\_multiple\_agents()
Apply `auto()` to a list of files. Each file may be a different format.
```python theme={null}
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.
```python theme={null}
def load_agent_from_markdown(
self,
file_path: str,
**kwargs,
) -> Agent
```
### load\_agents\_from\_markdown()
Load multiple agents from one or more Markdown files.
```python theme={null}
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]
```
A single file, a directory (every `*.md` file in it), or a list of file paths.
Load files in parallel when there is more than one. Agents are then returned in completion order.
Files above this size are skipped.
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`.
```python theme={null}
def load_agents_from_yaml(
self,
yaml_file: str,
return_type: ReturnTypes = "auto",
**kwargs,
)
```
Path to the YAML definitions file. It needs an `agents` list and may have a `swarm_architecture` section.
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.
```python theme={null}
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`.
```python theme={null}
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.
```python theme={null}
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.
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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](https://github.com/kyegomez/swarms/blob/master/swarms/structs/agent_loader.py).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.