AutoAgentBuilder

Overview

The AutoAgentBuilder class turns a plain-English task into a roster of agents. A single builder agent is forced to call one function, build_agents, and must answer with a list of agent configurations rather than prose. Each generated agent carries exactly four fields — the minimum needed to construct an Agent:

name, description, system_prompt, model_name

The builder designs the team and stops there. It does not choose a multi-agent architecture and it does not execute anything, so you decide what runs the roster.

Because the provider enforces the tool schema, there is no markdown fence to strip and no JSON to extract from a paragraph. This is the main behavioral difference from AutoSwarmBuilder, which uses structured output and also selects a swarm_type for you.

Class Definition

from swarms import AutoAgentBuilder

Parameters

str

default:"auto-agent-builder"

Name of this builder instance

str

default:"Generates agent configurations from a task"

What this builder is for

str

default:"gpt-5.4"

Model backing the builder agent itself. This is not the model given to the generated agents — the builder chooses those per agent. Must support function calling

int

default:"5"

Upper bound on roster size. This is a ceiling, not a target — the builder is instructed to prefer the smallest roster that covers the task, so it will routinely return fewer. Must be >= 1

Optional[int]

default:"None"

Exact number of agents to generate. When set, overrides max_agents and the builder’s prefer-fewer guidance, and the count is verified on the result. Must be >= 1

str

default:"AUTO_AGENT_BUILDER_SYSTEM_PROMPT"

Instructions for the builder agent. Override to constrain the roster — force a model tier, require a specific role, or restrict the decomposition strategy

Optional[Dict[str, Any]]

default:"None"

Extra keyword arguments forwarded to every generated Agent, e.g. max_loops or streaming_on. Keys that collide with the four generated fields are ignored. Unused when return_dict is True, since no agent is constructed

bool

default:"False"

When True, run() returns the raw configuration dicts instead of constructed Agent objects. Use this to inspect, serialize, or edit the roster before building anything from it

bool

default:"False"

Whether to log the generated roster

Raises:

ValueError: If max_agents or num_agents is less than 1

Roster size: ceiling vs exact count

This is the setting most likely to surprise you.

Parameter	Meaning	Result for a 3-role task
`max_agents=5`	A ceiling. The builder picks the smallest roster that covers the task	3 agents
`num_agents=5`	A hard requirement. Overrides the prefer-fewer guidance	5 agents

The default system prompt actively pushes the count down — it states that “fewer is almost always better” and that “2–3 agents is the common, correct case for most tasks.” So max_agents=5 returning three agents is the builder working correctly, not a failure.

# Ceiling — the builder decides how many it needs
AutoAgentBuilder(max_agents=5).run(task)

# Exact — the builder must split the work to reach five
AutoAgentBuilder(num_agents=5).run(task)

If the model returns fewer than num_agents, a warning is logged and the shorter roster is returned. Agents cannot be fabricated for a task that does not support them.

Methods

`run()`

def run(self, task: str) -> Union[List[Agent], List[Dict[str, str]]]

Generates the roster in the shape this builder was configured for. Parameters:

str

required

The task the generated team should be able to handle

Returns:

Union[List[Agent], List[Dict[str, str]]]

Configuration dicts when return_dict=True, otherwise constructed Agent objects

Raises:

ValueError: If task is empty, or the builder returns no usable agent configurations

`build_agents()`

def build_agents(self, task: str) -> List[Agent]

Generates configurations and constructs the Agent objects. Ignores return_dict — this is the shape-specific entry point for callers that want agents regardless of how the builder was configured. Returns:

List[Agent]

Constructed agents, ready to run or hand to a multi-agent structure. agent_kwargs is applied to each

`build_configs()`

def build_configs(self, task: str) -> List[Dict[str, str]]

Generates agent configurations for a task, always as dicts. Ignores return_dict. Returns:

List[Dict[str, str]]

One dict per agent with name, description, system_prompt and model_name. Truncated to num_agents or max_agents

`call()`

def __call__(self, task: str) -> Union[List[Agent], List[Dict[str, str]]]

Alias for run(). Follows return_dict.

Output shapes

AutoAgentBuilder().run(task)                  # -> [Agent, Agent, ...]
AutoAgentBuilder(return_dict=True).run(task)  # -> [{...}, {...}, ...]

builder.build_agents(task)                    # always Agent objects
builder.build_configs(task)                   # always configuration dicts

One LLM call per method

Every public method triggers a fresh call, and the builder is not deterministic. Calling build_configs() and then build_agents() designs two different rosters — so what you printed may not be what you ran. Generate once and reuse the result:

configs = builder.build_configs(task)

agents = [
    Agent(
        agent_name=c["name"],
        agent_description=c["description"],
        system_prompt=c["system_prompt"],
        model_name=c["model_name"],
        max_loops=1,
    )
    for c in configs
]

Validation behavior

The builder filters the model’s output before returning it:

Condition	Behavior
Entry missing any of the four fields	Dropped, warning logged
Duplicate `name`	Dropped, warning logged. `Agent` memory is keyed on `agent_name`, so duplicates would corrupt each other’s state
More agents than the limit	Truncated to `num_agents` or `max_agents`, warning logged
Fewer than `num_agents`	Returned as-is, warning logged
No usable entries at all	Raises `ValueError`
Malformed or non-JSON tool output	Raises `ValueError`

Tool calls are parsed from all shapes providers return: a plain dict, a list-wrapped dict, or an attribute-style object such as litellm’s ChatCompletionMessageToolCall.

Usage Examples

Inspect the roster before building

from swarms import AutoAgentBuilder

builder = AutoAgentBuilder(model_name="gpt-5.4", max_agents=3, return_dict=True)

for config in builder.run("Analyze why SaaS churn increased last quarter."):
    print(f"{config['name']} [{config['model_name']}]")
    print(f"  {config['description']}")

Build and run in sequence

from swarms import AutoAgentBuilder, SequentialWorkflow

agents = AutoAgentBuilder(num_agents=3, agent_kwargs={"max_loops": 1}).run(task)

result = SequentialWorkflow(agents=agents, max_loops=1).run(task)

Compose with SwarmRouter

The builder answers who is on the team; SwarmRouter answers how they run.

from swarms import AutoAgentBuilder, SwarmRouter

agents = AutoAgentBuilder(max_agents=4).run(task)

router = SwarmRouter(agents=agents, swarm_type="ConcurrentWorkflow", max_loops=1)
result = router.run(task)

Since the roster is just a list of agents, it also drops into MixtureOfAgents, HierarchicalSwarm, GroupChat, or anything else that accepts one.

Constrain the roster with a custom prompt

from swarms.prompts.auto_agent_builder_prompt import (
    AUTO_AGENT_BUILDER_SYSTEM_PROMPT,
)

CONSTRAINED = AUTO_AGENT_BUILDER_SYSTEM_PROMPT + """

ADDITIONAL CONSTRAINTS:
- Every agent must use model_name "gpt-5.4-mini".
- Include exactly one agent whose sole job is to verify the others' output.
"""

builder = AutoAgentBuilder(system_prompt=CONSTRAINED, num_agents=4)

The builder system prompt

The default prompt is exported and can be imported, extended, or replaced:

from swarms import AUTO_AGENT_BUILDER_SYSTEM_PROMPT

It instructs the builder to:

Area	Guidance
Decomposition	Split by stage, domain, source, or perspective — and pick one seam rather than mixing them
Sizing	Prefer the smallest roster; a single agent is a valid answer. An explicit exact count overrides this
Merge test	Merge any two agents where one competent specialist could do both jobs
Coverage test	Confirm every part of the task has an owner; gaps are worse than redundancy
`system_prompt` field	Several paragraphs covering identity, responsibility, method, output, and standards — the generated agent never sees the builder prompt or its teammates’ prompts, so each must stand alone
`model_name` field	Match the model to cognitive load, not to the agent’s importance. Mixing tiers is a sign of good design

Comparison with AutoSwarmBuilder

	`AutoAgentBuilder`	`AutoSwarmBuilder`
Output	Agent roster only	Roster plus `swarm_type` and optional execution
Structured output method	Forced function call	`response_format`
Fields per agent	4	10+ (`max_tokens`, `temperature`, `role`, `goal`, …)
Picks architecture	No	Yes
Executes the task	No	Optionally

Use AutoAgentBuilder when you want the roster and full control over what runs it. Use AutoSwarmBuilder when you want the whole pipeline decided for you.

Requirements

The builder needs a model that supports function calling, plus a provider key:

export OPENAI_API_KEY=sk-...

Generated agents may name a different provider than the builder — it chooses a model per agent and deliberately mixes tiers. If a roster references a provider you have no key for, set that key or edit model_name on the configs before constructing.

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

AutoAgentBuilder

Overview

Class Definition

Parameters

Roster size: ceiling vs exact count

Methods

`run()`

`build_agents()`

`build_configs()`

`call()`

Output shapes

One LLM call per method

Validation behavior

Usage Examples

Inspect the roster before building

Build and run in sequence

Compose with SwarmRouter

Constrain the roster with a custom prompt

The builder system prompt

Comparison with AutoSwarmBuilder

Requirements

Source Code

​Overview

​Class Definition

​Parameters

​Roster size: ceiling vs exact count

​Methods

​run()

​build_agents()

​build_configs()

​__call__()

​Output shapes

​One LLM call per method

​Validation behavior

​Usage Examples

​Inspect the roster before building

​Build and run in sequence

​Compose with SwarmRouter

​Constrain the roster with a custom prompt

​The builder system prompt

​Comparison with AutoSwarmBuilder

​Requirements

​Source Code

Overview

Class Definition

Parameters

Roster size: ceiling vs exact count

Methods

`run()`

`build_agents()`

`build_configs()`

`call()`

Output shapes

One LLM call per method

Validation behavior

Usage Examples

Inspect the roster before building

Build and run in sequence

Compose with SwarmRouter

Constrain the roster with a custom prompt

The builder system prompt

Comparison with AutoSwarmBuilder

Requirements

Source Code