CLI Configuration

This guide covers how to configure agents and swarms using YAML configuration files and environment variables.

YAML Configuration

The Swarms CLI supports loading agent configurations from YAML files, allowing you to define complex agent setups and swarm architectures declaratively.

Basic YAML Structure

A Swarms YAML configuration file has two main sections:

agents - List of agent configurations
swarm_architecture (optional at the schema level, but required in practice — see Running YAML Configurations) - Swarm configuration

Agent Configuration

Single Agent Example

agents:
  - agent_name: "Research-Agent"
    model_name: "gpt-5.4"
    temperature: 0.1
    max_tokens: 2000
    system_prompt: "You are an expert research analyst specializing in technology trends."
    max_loops: 1
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: true
    saved_state_path: "research_agent.json"
    user_name: "researcher"
    retry_attempts: 3
    context_length: 4000
    output_type: "str"

swarm_architecture:
  name: "Research-Swarm"
  description: "A single-agent swarm that researches a topic"
  swarm_type: "SequentialWorkflow"
  task: "Analyze the latest developments in quantum computing"

swarm_architecture is required here — run-agents always runs through a SwarmRouter, so a YAML file with only an agents section will fail. See Running YAML Configurations below.

Multiple Agents Example

agents:
  - agent_name: "Financial-Analysis-Agent"
    model_name: "gpt-5.4"
    temperature: 0.1
    max_tokens: 2000
    system_prompt: "You are a financial analyst expert."
    max_loops: 1
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: true
    saved_state_path: "finance_agent.json"
    user_name: "swarms_corp"
    retry_attempts: 1
    context_length: 4000
    output_type: "str"

  - agent_name: "Stock-Analysis-Agent"
    model_name: "gpt-5.4"
    temperature: 0.2
    max_tokens: 1500
    system_prompt: "You are a stock market analysis expert."
    max_loops: 2
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: false
    saved_state_path: "stock_agent.json"
    user_name: "stock_user"
    retry_attempts: 3
    context_length: 4000
    output_type: "json"

swarm_architecture:
  name: "Financial-Advisory-Swarm"
  description: "A swarm of agents working together to provide comprehensive financial advice"
  swarm_type: "SequentialWorkflow"
  task: "How can I establish a ROTH IRA to buy stocks and get a tax break?"

Swarm Architecture Configuration

You can define how agents work together using the swarm_architecture section:

agents:
  - agent_name: "Financial-Analysis-Agent"
    # ... agent config ...

  - agent_name: "Stock-Analysis-Agent"
    # ... agent config ...

swarm_architecture:
  name: "Financial-Advisory-Swarm"
  description: "A swarm of agents working together to provide comprehensive financial advice"
  swarm_type: "SequentialWorkflow"
  max_loops: 2
  task: "Analyze ROTH IRA setup requirements and provide a comprehensive long-term investment strategy"
  autosave: true

Any extra key in swarm_architecture is passed to SwarmRouter as a keyword argument. Use this for router parameters such as rearrange_flow (required for AgentRearrange), output_type, or fallback_swarms:

agents:
  - agent_name: "Drafter"
    system_prompt: "You write a first draft."
  - agent_name: "Reviewer"
    system_prompt: "You review drafts for clarity."
  - agent_name: "Fact-Checker"
    system_prompt: "You check every factual claim."

swarm_architecture:
  name: "Review-Pipeline"
  description: "Draft, then review and fact-check in parallel"
  swarm_type: "AgentRearrange"
  rearrange_flow: "Drafter -> Reviewer, Fact-Checker"
  task: "Write a short brief on solid-state batteries"

Agent Configuration Parameters

Parameter	Type	Required	Default	Description
`agent_name`	string	Yes	-	Unique name for the agent
`system_prompt`	string	Yes	-	System prompt defining agent behavior
`model_name`	string	No	”gpt-5.4” (the `Agent` class default)	LLM model to use
`max_loops`	integer	No	1	Maximum number of execution loops
`autosave`	boolean	No	true	Enable automatic state saving
`dashboard`	boolean	No	false	Enable agent dashboard
`verbose`	boolean	No	false	Enable verbose logging
`dynamic_temperature_enabled`	boolean	No	false	Enable dynamic temperature adjustment
`saved_state_path`	string	No	null	Path to save agent state
`user_name`	string	No	”default_user”	Username associated with agent
`retry_attempts`	integer	No	3	Number of retry attempts on failure
`context_length`	integer	No	100000	Maximum context length
`output_type`	string	No	”str”	Output format, such as “str”, “json”, or “dict”
`auto_generate_prompt`	boolean	No	false	Build the system prompt from the agent’s name, description, and prompt

The autosave, user_name, and context_length defaults above come from the YAML loader and differ from the Agent class defaults. The loader also accepts return_step_meta, artifacts_on, artifacts_file_extension, and artifacts_output_path, but Agent no longer has those parameters, so they have no effect. Any other key, such as temperature or max_tokens, is passed to Agent as a keyword argument; keys Agent does not recognize are silently ignored.

Model Configuration

Model parameters are flat, top-level fields on each agent entry — there is no nested model: block. A model: block is not rejected (extra fields are allowed), but it is silently ignored and has no effect on the agent:

agents:
  - agent_name: "My-Agent"
    system_prompt: "You are a helpful assistant."
    model_name: "gpt-5.4"         # Model identifier
    temperature: 0.1               # Randomness (0.0-2.0)
    max_tokens: 2000              # Maximum tokens per response

Swarm Architecture Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Name of the swarm
`description`	string	Yes	Description of swarm purpose
`swarm_type`	string	Yes	Type of swarm (e.g., “SequentialWorkflow”); any `SwarmRouter` swarm type
`task`	string	Yes, for `run-agents`	The task `run-agents` passes to the swarm
`max_loops`	integer	No	Maximum loops for swarm execution (default 1)
`autosave`	boolean	No	Enable swarm state autosave (default true)
any other key	any	No	Passed to `SwarmRouter`, e.g. `rearrange_flow`, `output_type`, `fallback_swarms`

The loader also accepts flow, return_json, and rules, but SwarmRouter has no such parameters and ignores them. To set an AgentRearrange flow, use rearrange_flow.

Running YAML Configurations

To execute agents from a YAML file:

swarms run-agents --yaml-file agents.yaml

With a custom file path:

swarms run-agents --yaml-file /path/to/my-config.yaml

run-agents hardcodes return_type="run_swarm", so it always builds and runs a SwarmRouter. A YAML file that defines agents but omits swarm_architecture, or a swarm_architecture without a task, will fail — there is currently no standalone-agent mode for this command.

Environment Variables

The Swarms CLI uses environment variables for API keys and configuration.

Required Environment Variables

At least one provider key is required. swarms setup-check looks for one of these four, but any provider LiteLLM supports works for running agents (for example GROQ_API_KEY, XAI_API_KEY, or OPENROUTER_API_KEY):

# OpenAI (most common)
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Google
export GOOGLE_API_KEY="AIza..."

# Cohere
export COHERE_API_KEY="..."

Optional Environment Variables

# Workspace directory for agent state and logs
export WORKSPACE_DIR="./agent_workspace"

# Swarms platform key, needed for --marketplace-prompt-id
export SWARMS_API_KEY="..."

# Opt out of OpenTelemetry tracing, which is on by default
export SWARMS_TELEMETRY_ON="false"

See Telemetry for what tracing captures.

Using .env Files

Create a .env file in your project root:

# .env file
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
WORKSPACE_DIR=./agent_workspace

The Swarms CLI automatically loads the nearest .env file, searching upward from the current directory. swarms init writes one for you.

Environment Variable Priority

Variables already set in your environment, whether exported in the shell or set system-wide, take precedence. The .env file only fills in variables that are not already set.

Workspace Directory

The WORKSPACE_DIR environment variable determines where agents store their outputs:

export WORKSPACE_DIR="/path/to/workspace"

Default behavior:

If not set, importing Swarms sets it to ./agent_workspace and creates the directory
Agent state files are saved under agents/<agent-name>-<id>/
Logs are written to logs/

Directory structure example:

agent_workspace/
├── agents/
│   └── financial-analysis-agent-<id>/
│       └── finance_agent.json
├── logs/
└── swarms/

Not everything lives in the workspace: conversation files saved without an explicit path go to ./conversations/ in the current directory, and ~/.swarms/ only caches MCP OAuth tokens.

Markdown Agent Configuration

You can also define agents using Markdown files with YAML frontmatter.

Markdown Format

---
name: Research Agent
description: Expert research analyst
model_name: gpt-5.4
temperature: 0.1
max_loops: 1
---

You are an expert research analyst with deep knowledge of:
- Scientific literature review
- Data analysis and interpretation
- Trend identification
- Report generation

Provide thorough, well-researched responses backed by evidence.

The markdown loader reads only name, description, model_name (or model), temperature, max_loops, mcp_url, and streaming_on from the frontmatter. Other keys are ignored, and the body becomes the system prompt.

Loading Markdown Agents

Load a single agent:

swarms load-markdown --markdown-path ./agent.md

In Swarms 15.0.3, passing a directory to --markdown-path fails with Unsupported file type. Load one file at a time.

--concurrent defaults to true and there is no --no-concurrent flag to disable it, so this flag is currently always on regardless of whether it’s passed.

Configuration Best Practices

1. API Key Management

Never commit API keys to version control
Use .env files (add to .gitignore)
Rotate keys regularly
Use different keys for development and production

2. Agent Configuration

Start with low temperature (0.1-0.3) for consistent outputs
Use appropriate context lengths based on your use case
Enable autosave for long-running agents
Set retry attempts for production reliability

3. Swarm Configuration

Put collaboration rules in system prompts; the rules key is ignored
Use descriptive names for agents and swarms
Test with max_loops=1 before increasing
Enable verbose mode during development

4. File Organization

project/
├── .env                    # API keys (gitignored)
├── .gitignore             # Ignore .env and workspace
├── agents/
│   ├── research.yaml      # Agent configs
│   └── analysis.yaml
├── swarms/
│   └── financial.yaml     # Swarm configs
└── agent_workspace/       # Outputs (gitignored)

Validation

Check Your Configuration

Verify your environment setup:

swarms setup-check --verbose

This checks:

✓ Python version (3.10+)
✓ Swarms installation
✓ API keys
✓ Dependencies
✓ .env file
✓ WORKSPACE_DIR

Test Agent Configuration

Test a YAML configuration:

swarms run-agents --yaml-file test-config.yaml

Example Configurations

Minimal Agent Config

agents:
  - agent_name: "Simple-Agent"
    system_prompt: "You are a helpful assistant"

swarm_architecture:
  name: "Simple-Swarm"
  description: "A single simple agent"
  swarm_type: "SequentialWorkflow"
  task: "Hello, world!"

Production Agent Config

agents:
  - agent_name: "Production-Agent"
    model_name: "gpt-5.4"
    temperature: 0.2
    max_tokens: 4000
    system_prompt: "You are a production-ready agent with error handling."
    max_loops: 3
    autosave: true
    dashboard: true
    verbose: true
    retry_attempts: 5
    context_length: 8000
    saved_state_path: "prod_agent.json"
    user_name: "production"
    output_type: "json"

swarm_architecture:
  name: "Production-Swarm"
  description: "A single production-ready agent"
  swarm_type: "SequentialWorkflow"
  task: "Process production workload"

Multi-Agent Swarm

agents:
  - agent_name: "Researcher"
    system_prompt: "You gather and analyze information."

  - agent_name: "Writer"
    system_prompt: "You write clear, engaging content."

  - agent_name: "Editor"
    system_prompt: "You review and improve content."

swarm_architecture:
  name: "Content-Creation-Swarm"
  description: "Research, write, and edit content"
  swarm_type: "SequentialWorkflow"
  max_loops: 1
  task: "Write a report on renewable energy adoption"

Troubleshooting

Common Issues

Issue: “No API keys found”

# Solution: Set API key in .env
echo "OPENAI_API_KEY=sk-..." > .env
swarms setup-check

Issue: “YAML file not found”

# Solution: Check file path
ls agents.yaml
swarms run-agents --yaml-file ./path/to/agents.yaml

Issue: “WORKSPACE_DIR not set”

# Solution: Set workspace directory
export WORKSPACE_DIR="./agent_workspace"
mkdir -p $WORKSPACE_DIR

Issue: “Invalid YAML format”

# Solution: Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('agents.yaml'))"

​CLI Configuration

​YAML Configuration

​Basic YAML Structure

​Agent Configuration

​Single Agent Example

​Multiple Agents Example

​Swarm Architecture Configuration

​Agent Configuration Parameters

​Model Configuration

​Swarm Architecture Parameters

​Running YAML Configurations

​Environment Variables

​Required Environment Variables

​Optional Environment Variables

​Using .env Files

​Environment Variable Priority

​Workspace Directory

​Markdown Agent Configuration

​Markdown Format

​Loading Markdown Agents

​Configuration Best Practices

​1. API Key Management

​2. Agent Configuration

​3. Swarm Configuration

​4. File Organization

​Validation

​Check Your Configuration

​Test Agent Configuration

​Example Configurations

​Minimal Agent Config

​Production Agent Config

​Multi-Agent Swarm

​Troubleshooting

​Common Issues

​Next Steps

CLI Overview

Commands Reference

​Resources

CLI Configuration

YAML Configuration

Basic YAML Structure

Agent Configuration

Single Agent Example

Multiple Agents Example

Swarm Architecture Configuration

Agent Configuration Parameters

Model Configuration

Swarm Architecture Parameters

Running YAML Configurations

Environment Variables

Required Environment Variables

Optional Environment Variables

Using .env Files

Environment Variable Priority

Workspace Directory

Markdown Agent Configuration

Markdown Format

Loading Markdown Agents

Configuration Best Practices

1. API Key Management

2. Agent Configuration

3. Swarm Configuration

4. File Organization

Validation

Check Your Configuration

Test Agent Configuration

Example Configurations

Minimal Agent Config

Production Agent Config

Multi-Agent Swarm

Troubleshooting

Common Issues

Next Steps

Resources