Swarms API Documentation - Build AI Agents & Multi-Agent Systems

Overview

The autonomous agent mode (max_loops="auto") lets an agent plan, execute, and summarize complex multi‑step tasks without you having to manually specify the number of loops. When max_loops="auto", the agent:

Plans the work as a set of structured subtasks
Executes each subtask using tools (search, file I/O, etc.)
Summarizes the results into a clear final answer

This page walks through a fully autonomous medical diagnosis agent that analyzes blood work results using the Swarms Python client.

How Autonomous Mode Works

Phase 1: Planning

The agent analyzes the main task and calls an internal planning tool (e.g., create_plan)
It produces a list of subtasks with:
- step_id: unique identifier
- description: what to do
- priority: critical, high, medium, or low
- dependencies: other steps that must complete first

Phase 2: Execution

For each subtask, the agent loops through:

Think: Optional short reasoning step (e.g., with a think tool)
Act: Calls tools (search, file, APIs, etc.)
Observe: Reads tool outputs and updates its plan state
Complete: Marks the subtask done when satisfied (e.g., via subtask_done)

Dependencies are respected — subtasks only run when their prerequisites are complete.

Phase 3: Summary

Once all subtasks are complete, the agent:

Generates a final structured summary
Optionally calls a completion tool (e.g., complete_task)
Returns the final result to your application

Tool Selection

By default, autonomous agents have access to all safe built-in tools. You can restrict which tools are available using the selected_tools parameter in agent_config:

payload = {
    "agent_config": {
        "agent_name": "My Agent",
        "model_name": "gpt-4.1",
        "max_loops": "auto",
        "selected_tools": ["create_plan", "think", "subtask_done", "complete_task", "read_file"],
    },
    "task": "Your task here",
}

Available tools: create_plan, think, subtask_done, complete_task, respond_to_user, create_file, update_file, read_file, list_directory, delete_file, create_sub_agent, assign_task.

run_bash is not available via the API for security reasons.

Complete Example: Autonomous Medical Diagnosis Agent

This example shows an autonomous agent that:

Uses the Swarms Python client to call the Agent Completions API
Analyzes blood work results as an expert doctor
Runs until it decides the task is complete using max_loops="auto"

Environment Setup

Create a .env file:

SWARMS_API_KEY=your_swarms_api_key_here

Install dependencies:

pip install swarms-client python-dotenv

Code Example

Python
TypeScript
Rust

import os
from dotenv import load_dotenv
import json
from swarms_client import SwarmsClient

load_dotenv()


client = SwarmsClient(
    api_key=os.getenv("SWARMS_API_KEY"),
    base_url="https://api.swarms.world",
    timeout=1000,
)


result = client.agent.run(
    agent_config={
        "agent_name": "Bloodwork Diagnosis Expert",
        "description": "An expert doctor specializing in interpreting and diagnosing blood work results.",
        "system_prompt": (
            "You are an expert medical doctor specializing in the interpretation and diagnosis of blood work. "
            "Your expertise includes analyzing laboratory results, identifying abnormal values, "
            "explaining their clinical significance, and recommending next diagnostic or treatment steps. "
            "Provide clear, evidence-based explanations and consider differential diagnoses based on blood test findings."
        ),
        "model_name": "gpt-4.1",
        "max_loops": "auto",  # <— enables fully autonomous multi-step reasoning
        "max_tokens": 1000,
        "temperature": 0.5,
    },
    task=(
        "A patient presents with the following blood work results: "
        "Hemoglobin: 10.2 g/dL (low), WBC: 13,000 /µL (high), Platelets: 180,000 /µL (normal), "
        "ALT: 65 U/L (high), AST: 70 U/L (high). "
        "Please provide a detailed interpretation, possible diagnoses, and recommended next steps."
    ),
)

print(json.dumps(result, indent=4))

import 'dotenv/config'

const API_KEY = process.env.SWARMS_API_KEY
const BASE_URL = 'https://api.swarms.world'

if (!API_KEY) {
  throw new Error('SWARMS_API_KEY is not set')
}

async function runAutonomousAgent() {
  const payload = {
    agent_config: {
      agent_name: 'Research-Report-Agent',
      description: 'Creates comprehensive research reports',
      system_prompt:
        'You are an expert research analyst. ' +
        'Create detailed, well-structured reports and save work to files when appropriate.',
      model_name: 'gpt-4.1',
      max_loops: 'auto', // enable autonomous loop mode
      dynamic_temperature_enabled: true,
    },
    task: `
      Create a comprehensive research report on quantum computing:
      1. Research current quantum computing technologies.
      2. Identify major companies and research institutions.
      3. Analyze recent breakthroughs.
      4. Predict future trends.
      5. Create a detailed markdown-style outline.
    `,
  }

  const res = await fetch(`${BASE_URL}/v1/agent/completions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify(payload),
  })

  if (!res.ok) {
    const text = await res.text()
    throw new Error(`HTTP ${res.status}: ${text}`)
  }

  const json = await res.json()
  console.log(JSON.stringify(json, null, 2))
}

void runAutonomousAgent().catch(console.error)

use std::env;

use reqwest::blocking::Client;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key =
        env::var("SWARMS_API_KEY").expect("SWARMS_API_KEY environment variable is required");

    let client = Client::new();

    let payload = json!({
        "agent_config": {
            "agent_name": "Research-Report-Agent",
            "description": "Creates comprehensive research reports",
            "system_prompt": "You are an expert research analyst. \
                Create detailed, well-structured reports and save work to files when appropriate.",
            "model_name": "gpt-4.1",
            "max_loops": "auto",
            "dynamic_temperature_enabled": true
        },
        "task": "\
            Create a comprehensive research report on quantum computing:\n\
            1. Research current quantum computing technologies.\n\
            2. Identify major companies and research institutions.\n\
            3. Analyze recent breakthroughs.\n\
            4. Predict future trends.\n\
            5. Create a detailed markdown-style outline.\n\
        "
    });

    let res = client
        .post("https://api.swarms.world/v1/agent/completions")
        .header("x-api-key", api_key)
        .header("Content-Type", "application/json")
        .json(&payload)
        .send()?;

    res.error_for_status_ref()?;

    let body = res.text()?;
    println!("{body}");

    Ok(())
}

Best Practices

Clear tasks: Give specific, outcome‑oriented instructions (what to produce, how many steps)
Tooling: Provide tools that match the work (search, scraping, file I/O, custom APIs)
Bounded scope: Ask for a concrete deliverable (e.g., “single markdown report”, “CSV summary”)

Key Takeaways

Set max_loops="auto" to let the agent decide how many reasoning/action loops are required
Combine planning, tools, and file operations to tackle complex research and analysis workflows
Prefer clear, structured tasks so the planner can create good subtasks and dependencies

For a minimal REST‑only example using /v1/agent/completions, see “Single Agent Completion (REST)” in the examples section.

Getting Started

Agent Capabilities

Multi-Agent Architectures

Finance & Investing

Healthcare & Life Sciences

Legal, M&A & Diligence

Customer Operations

Defense, Gov & Supply Chain

Marketing, Content & Founder Tools

API Utilities

Migration Guides

Resources

Production

Compatibility & Benchmarks

Tutorials & Integrations

Fully Autonomous Agent Loop

Overview

How Autonomous Mode Works

Phase 1: Planning

Phase 2: Execution

Phase 3: Summary

Tool Selection

Complete Example: Autonomous Medical Diagnosis Agent

Environment Setup

Code Example

Best Practices

Key Takeaways

​Overview

​How Autonomous Mode Works

​Phase 1: Planning

​Phase 2: Execution

​Phase 3: Summary

​Tool Selection

​Complete Example: Autonomous Medical Diagnosis Agent

​Environment Setup

​Code Example

​Best Practices

​Key Takeaways

Overview

How Autonomous Mode Works

Phase 1: Planning

Phase 2: Execution

Phase 3: Summary

Tool Selection

Complete Example: Autonomous Medical Diagnosis Agent

Environment Setup

Code Example

Best Practices

Key Takeaways