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

Overview

The Auto Agent Builder generates agent configurations from a task. You describe what you want accomplished; a single builder agent designs the smallest team that covers it and returns each agent’s name, description, system prompt, and model choice as ready-to-use AgentSpec entries. Two things to know up front:

It designs, it does not run. The response contains agent configurations only — no agents are constructed or executed, and nothing beyond the single builder call is billed. Pipe the returned roster into /v1/swarm/completions (or any multi-agent endpoint) to actually run it.
Available on all tiers. Unlike its siblings Graph Workflow and Batched Grid Workflow, this endpoint is not premium-gated. It is billable, so your account needs a credit balance above $1.00.

Endpoint: POST /v1/auto-agent-builder/completions Base URL: https://api.swarms.world (production) or your custom deployment URL

Architecture

The builder only designs the roster. Running it is a separate call you make yourself, shown dashed above.

Authentication

All requests require an API key passed in the x-api-key header:

headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

Input Parameters

AutoAgentBuilderInput Schema

Parameter	Type	Required	Default	Description
`task`	`string`	Yes	-	The task the generated team should be able to handle. An empty string returns `422`; a task of only whitespace returns `400`.
`name`	`string`	No	`"auto-agent-builder"`	Name for this builder run.
`description`	`string`	No	`"Generates agent configurations from a task"`	Description of the run.
`model_name`	`string`	No	builder default	Model backing the builder agent itself — not the generated agents; the builder chooses each generated agent’s model. Ollama models are rejected with a 400.
`max_agents`	`integer`	No	`5`	Ceiling on roster size (1-100). The builder prefers the smallest roster that covers the task.
`num_agents`	`integer`	No	`null`	Exact roster size (1-100). When set, overrides `max_agents` and the prefer-fewer guidance.
`system_prompt`	`string`	No	builder default	Custom instructions for the builder agent (not the generated agents).
`agent_kwargs`	`dict`	No	`null`	Accepted, but currently has no effect on the response: the returned roster does not carry these keys. Set fields such as `max_loops` or `max_tokens` on each returned agent yourself before running the roster.

Output Parameters

AutoAgentBuilderOutput Schema

Parameter	Type	Description
`job_id`	`string`	Unique job identifier, prefixed `auto-agent-builder-`.
`name`	`string`	Run name from the input (or the default).
`description`	`string`	Run description from the input (or the default).
`status`	`string`	`"success"` on completion.
`agents`	`List[AgentSpec]`	The generated roster. Each entry is a complete `AgentSpec`; see below.
`usage`	`Usage`	Token counts and cost for the builder call.
`timestamp`	`string`	ISO 8601 UTC timestamp.

Generated agent entries

Each entry in agents is a complete AgentSpec. The builder writes these four fields:

Field	Type	Description
`agent_name`	`string`	Name the builder chose for the agent.
`description`	`string`	What the agent is responsible for.
`system_prompt`	`string`	Full system prompt the builder wrote for the agent.
`model_name`	`string`	Model the builder selected for the agent.

Every other AgentSpec field with a non-null default is also present at that default, e.g. max_tokens: 16000, max_loops: 1 and role: "worker". Fields whose default is null are left out.

Usage Schema

Field	Type	Description
`input_tokens`	`integer`	Tokens in your task (plus `system_prompt` if provided).
`output_tokens`	`integer`	Tokens in the generated roster.
`total_tokens`	`integer`	Sum of the above.
`total_cost`	`float`	Total credits charged for this call.
`cost_per_agent`	`float`	Flat fee for the single builder agent ($0.01). Not multiplied by roster size.
`flash_sale_applied`	`boolean`	Whether the tokens were billed at the flash sale price.

Cost Calculation

The endpoint bills one builder-agent call:

Input and output tokens: priced at the builder’s model (model_name, or the builder default) plus a 15% service fee
Flat builder-agent fee: $0.01 per request, however many agents it generates

total_cost = input_cost + output_cost + cost_per_agent. No night-time discount applies. The generated agents cost nothing until you run them. See Pricing to look up a model’s current price.

Error Responses

Status	Meaning
`400`	A `task` of only whitespace, an Ollama `model_name`, or the builder produced no usable configs.
`401`	Missing or invalid API key.
`402`	Account credit balance at or below $1.00.
`422`	Request failed schema validation (e.g. an empty `task`, or `max_agents` outside 1-100).
`429`	Rate limit exceeded.
`500`	Unexpected server error.

Examples

Minimal request

curl -X POST "https://api.swarms.world/v1/auto-agent-builder/completions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Research the EV battery market and produce an investment memo",
    "max_agents": 3
  }'

Example response:

{
  "job_id": "auto-agent-builder-8f3a1c2e9b",
  "name": "auto-agent-builder",
  "description": "Generates agent configurations from a task",
  "status": "success",
  "agents": [
    {
      "agent_name": "MarketResearchAnalyst",
      "description": "Researches EV battery market trends, key players, and supply chains.",
      "system_prompt": "You are an expert market research analyst specializing in the EV battery industry...",
      "model_name": "gpt-4.1",
      "auto_generate_prompt": false,
      "max_tokens": 16000,
      "role": "worker",
      "max_loops": 1,
      "streaming_on": false,
      "dynamic_temperature_enabled": false,
      "tool_call_summary": true,
      "reasoning_enabled": false,
      "publish_to_marketplace": false,
      "is_free": true
    },
    {
      "agent_name": "FinancialAnalyst",
      "description": "Builds valuation models and financial projections for EV battery companies.",
      "system_prompt": "You are a financial analyst specializing in investment memos...",
      "model_name": "gpt-4.1",
      "auto_generate_prompt": false,
      "max_tokens": 16000,
      "role": "worker",
      "max_loops": 1,
      "streaming_on": false,
      "dynamic_temperature_enabled": false,
      "tool_call_summary": true,
      "reasoning_enabled": false,
      "publish_to_marketplace": false,
      "is_free": true
    },
    {
      "agent_name": "InvestmentMemoWriter",
      "description": "Synthesizes research and analysis into a polished investment memo.",
      "system_prompt": "You are an investment memo writer...",
      "model_name": "claude-sonnet-5",
      "auto_generate_prompt": false,
      "max_tokens": 16000,
      "role": "worker",
      "max_loops": 1,
      "streaming_on": false,
      "dynamic_temperature_enabled": false,
      "tool_call_summary": true,
      "reasoning_enabled": false,
      "publish_to_marketplace": false,
      "is_free": true
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 612,
    "total_tokens": 626,
    "total_cost": 0.021413,
    "cost_per_agent": 0.01,
    "flash_sale_applied": false
  },
  "timestamp": "2026-08-13T12:00:00.000000+00:00"
}

Exact roster size

import os
import requests

BASE_URL = "https://api.swarms.world"
headers = {"x-api-key": os.getenv("SWARMS_API_KEY"), "Content-Type": "application/json"}

response = requests.post(
    f"{BASE_URL}/v1/auto-agent-builder/completions",
    headers=headers,
    json={
        "task": "Design, write, and edit a technical blog post about vector databases",
        "num_agents": 3,
    },
    timeout=120,
)
roster = response.json()["agents"]

# Apply shared runtime settings yourself before running the roster
for agent in roster:
    agent.update({"max_loops": 1, "max_tokens": 4000})

Build a team, then run it

The returned roster round-trips unmodified into the swarm endpoint:

import os
import requests

BASE_URL = "https://api.swarms.world"
headers = {"x-api-key": os.getenv("SWARMS_API_KEY"), "Content-Type": "application/json"}

task = "Audit this Python package for security issues and write a findings report"

# 1. Design the team
built = requests.post(
    f"{BASE_URL}/v1/auto-agent-builder/completions",
    headers=headers,
    json={"task": task, "max_agents": 4},
    timeout=120,
).json()

# 2. Run it
result = requests.post(
    f"{BASE_URL}/v1/swarm/completions",
    headers=headers,
    json={
        "name": "auto-built-audit-team",
        "swarm_type": "SequentialWorkflow",
        "task": task,
        "agents": built["agents"],
    },
    timeout=600,
).json()

print(result["output"])

Best Practices

Let the builder decide the size. max_agents is a ceiling, not a target — the builder prefers the smallest team that covers the task. Reach for num_agents only when you need an exact count.
Set runtime settings on the returned roster. agent_kwargs does not reach the response, so set fields like max_loops or max_tokens on each returned agent before posting the roster.
Review before running. The roster is plain JSON — inspect or edit the system prompts and model choices before posting them to a completions endpoint, especially for cost-sensitive workloads.

Rate Limits

Standard tier-based rate limits apply. See Rate Limits.

Support

Documentation: https://docs.swarms.ai
Email: kye@swarms.world
Community: https://discord.gg/EamjgSaEQf

Getting Started

Clients

Agent Completions

Decision Models

Multi-Agent

Batch

Capabilities

Resources

Swarms Cloud

Auto Agent Builder

Overview

Architecture

Authentication

Input Parameters

AutoAgentBuilderInput Schema

Output Parameters

AutoAgentBuilderOutput Schema

Generated agent entries

Usage Schema

Cost Calculation

Error Responses

Examples

Minimal request

Exact roster size

Build a team, then run it

Best Practices

Rate Limits

Support

​Overview

​Architecture

​Authentication

​Input Parameters

​AutoAgentBuilderInput Schema

​Output Parameters

​AutoAgentBuilderOutput Schema

​Generated agent entries

​Usage Schema

​Cost Calculation

​Error Responses

​Examples

​Minimal request

​Exact roster size

​Build a team, then run it

​Best Practices

​Rate Limits

​Support

Overview

Architecture

Authentication

Input Parameters

AutoAgentBuilderInput Schema

Output Parameters

AutoAgentBuilderOutput Schema

Generated agent entries

Usage Schema

Cost Calculation

Error Responses

Examples

Minimal request

Exact roster size

Build a team, then run it

Best Practices

Rate Limits

Support