> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto Agent Builder

> The Auto Agent Builder API generates a ready-to-run roster of agent configurations from a plain-language task description. A single builder agent analyzes your task and designs the team — names, descriptions, system prompts, and model choices — returning JSON configs you can post directly to the multi-agent endpoints. It never executes the generated agents.

## 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`](/docs/documentation/multi-agent/overview) (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 minimum credit balance of \$1.00.

**Endpoint:** `POST /v1/auto-agent-builder/completions`

**Base URL:** `https://api.swarms.world` (production) or your custom deployment URL

## Architecture

```mermaid theme={null}
flowchart LR
    T["Task description"] --> B["Builder agent"]
    B --> S["AgentSpec roster"]
    S -.->|"you run it"| W["/v1/swarm/completions"]
```

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:

```python theme={null}
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. Must be non-empty. |
| `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` | Extra fields applied to every generated agent (e.g. `max_loops`, `streaming_on`). Keys the builder itself produces (`agent_name`, `description`, `system_prompt`, `model_name`) cannot be overridden and are ignored. |

## 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. See the note below on which fields are populated. |
| `usage` | `Usage` | Token counts and cost for the builder call. |
| `timestamp` | `string` | ISO 8601 UTC timestamp. |

### Generated agent entries

Each entry in `agents` is an `AgentSpec`, but the builder populates only these fields — do not expect the full AgentSpec surface (e.g. `max_tokens`, `tools_list_dictionary`) unless you supplied it via `agent_kwargs`:

| 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. |

### 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. |

## Cost Calculation

The endpoint bills one builder-agent call:

* Input tokens: \$6.50 per 1M tokens
* Output tokens: \$18.50 per 1M tokens
* Flat builder-agent fee: \$0.01

`total_cost = input_cost + output_cost + cost_per_agent`. The generated agents cost nothing until you run them. See [Pricing](/docs/documentation/resources/pricing) for current rates.

## Error Responses

| Status | Meaning |
| - | - |
| `400` | Empty or invalid `task`, an Ollama `model_name`, or the builder produced no usable configs. |
| `401` | Missing or invalid API key. |
| `402` | Account credit balance below the \$1.00 minimum for billable endpoints. |
| `422` | Request failed schema validation (e.g. `max_agents` outside 1-100). |
| `429` | Rate limit exceeded. |
| `500` | Unexpected server error. |

## Examples

### Minimal request

```bash theme={null}
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:

```json theme={null}
{
  "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"
    },
    {
      "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"
    },
    {
      "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"
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 612,
    "total_tokens": 626,
    "total_cost": 0.021413,
    "cost_per_agent": 0.01
  },
  "timestamp": "2026-08-13T12:00:00.000000+00:00"
}
```

### Exact roster size with shared agent settings

```python theme={null}
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,
        "agent_kwargs": {"max_loops": 1, "max_tokens": 4000},
    },
    timeout=120,
)
roster = response.json()["agents"]
```

### Build a team, then run it

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

```python theme={null}
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.
* **Use `agent_kwargs` for runtime settings.** Fields like `max_loops`, `max_tokens`, or `streaming_on` applied via `agent_kwargs` land on every generated agent; the builder's own choices (`agent_name`, `description`, `system_prompt`, `model_name`) always win over colliding keys.
* **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](/docs/documentation/resources/ratelimits).

## Support

* Documentation: [https://docs.swarms.ai](https://docs.swarms.ai)
* Email: [kye@swarms.world](mailto:kye@swarms.world)
* Community: [https://discord.gg/EamjgSaEQf](https://discord.gg/EamjgSaEQf)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.