AdvisorSwarm

Overview

The AdvisorSwarm implements the advisor strategy described in Anthropic’s research (April 2026). It pairs a cheaper executor model that drives the task end-to-end with a powerful advisor model consulted on-demand between executor turns. The executor runs every turn. The advisor is on-demand — consulted between executor turns when budget allows. Both agents read from and write to the same shared conversation context. The advisor never calls tools or produces user-facing output. This is provider-agnostic: any model supported by LiteLLM works for either role. The swarm follows this workflow:

The shared conversation is cleared, then the user task is added to it
Before each executor turn, the advisor reads the full shared context and provides guidance (if budget allows)
The executor reads the full shared context (including any advisor guidance) and produces output
Both advisor guidance and executor output are added to the shared conversation
Repeat for max_loops executor turns

Installation

pip install -U swarms

Key Features

Feature	Description
Executor-Driven Loop	The executor runs every turn — it’s the main driver
On-Demand Advisor	Advisor is consulted between turns, not in a fixed sequence
Shared Context	Both agents read from and write to the same conversation
Budget Control	`max_advisor_uses` caps advisor consultations per run
Provider-Agnostic	Any LiteLLM-supported model works for either role
Custom Agents	Pass pre-configured agents with tools, MCP, or any Agent settings

Attributes

str

default:"None"

Unique identifier for this swarm instance. Auto-generated via generate_id("advisor-swarm") if not provided, producing advisor-swarm-<32 hex chars>.

str

default:"AdvisorSwarm"

Human-readable name

str

default:"An executor-advisor swarm..."

Description of the swarm’s purpose

str

default:"claude-sonnet-4-6"

Model for the executor agent

str

default:"claude-opus-4-6"

Model for the advisor agent

str

default:"Built-in"

System prompt for the executor

str

default:"Built-in"

System prompt for the advisor

int

default:"3"

Max advisor consultations per run(). 0 = executor runs alone.

int

default:"1"

Number of executor turns

OutputType

default:"dict-all-except-first"

Format for the returned conversation history, such as "dict", "str", "list", "final", "json" or "yaml"

bool

default:"False"

Enable detailed logging

Agent

default:"None"

Pre-configured Agent for execution (e.g., with tools or MCP). When set, executor_model_name, executor_system_prompt and tools are not applied to it

Agent

default:"None"

Pre-configured Agent for advising. When set, advisor_model_name and advisor_system_prompt are not applied to it

List[Callable]

default:"None"

Tools for the built-in executor agent only. The built-in advisor never gets tools

Raises:

Exception	Condition
`ValueError`	If `max_advisor_uses < 0`, `max_loops < 1`, or model names are empty

Methods

run()

Execute the advisor-executor orchestration flow.

def run(
    self,
    task: Optional[str] = None,
    img: Optional[str] = None,
    imgs: Optional[List[str]] = None,
    *args,
    **kwargs,
) -> Any

Parameters:

task (str): The task to accomplish. Required; an empty or missing task raises ValueError("A task is required")
img (str, optional): Optional single image input, passed to the executor
imgs (List[str], optional): Optional list of image inputs, passed to the executor

Returns: Formatted conversation history according to output_type Each call clears the shared conversation first, so reusing one swarm for several tasks does not carry the previous task’s transcript forward.

batched_run()

Run the swarm on multiple tasks, one after another.

def batched_run(self, tasks: List[str], *args, **kwargs) -> List[Any]

Parameters:

tasks (List[str]): List of task strings

Returns: List of results, one per task, in task order

`call()`

Calling the swarm instance runs run(task=task).

result = swarm("Write a Python function to merge two sorted lists")

Usage Examples

Basic Usage

from swarms import AdvisorSwarm

swarm = AdvisorSwarm(
    executor_model_name="claude-sonnet-4-6",
    advisor_model_name="claude-opus-4-6",
    max_advisor_uses=3,
    max_loops=1,
    verbose=True,
)

result = swarm.run(
    "Write a Python function that implements binary search on a sorted list. "
    "Include proper error handling, type hints, and edge cases."
)

print(result)

Multi-Turn with Advisor Guidance

Run the executor for multiple turns, with the advisor providing guidance before each:

from swarms import AdvisorSwarm

swarm = AdvisorSwarm(
    executor_model_name="claude-sonnet-4-6",
    advisor_model_name="claude-opus-4-6",
    max_advisor_uses=3,
    max_loops=3,
)

result = swarm.run("Design and implement a REST API rate limiter in Python")

Custom Executor with Tools

Pass a pre-configured executor agent with tools while keeping the advisor tool-free:

from swarms import Agent, AdvisorSwarm


def write_file(filename: str, content: str) -> str:
    """Write content to a file."""
    with open(filename, "w") as f:
        f.write(content)
    return f"Written: {filename}"


executor = Agent(
    agent_name="Executor",
    model_name="claude-sonnet-4-6",
    max_loops=1,
    tools=[write_file],
)

swarm = AdvisorSwarm(
    executor_agent=executor,
    advisor_model_name="claude-opus-4-6",
)

result = swarm.run("Create a Python module for string manipulation utilities")

Executor Only (No Advisor)

Set max_advisor_uses=0 to run the executor alone:

from swarms import AdvisorSwarm

swarm = AdvisorSwarm(
    executor_model_name="claude-sonnet-4-6",
    advisor_model_name="claude-opus-4-6",
    max_advisor_uses=0,
    max_loops=1,
)

result = swarm.run("Simple task that doesn't need advisor guidance")

Different Providers

The swarm is provider-agnostic. Use any models LiteLLM supports:

from swarms import AdvisorSwarm

# OpenAI models
swarm = AdvisorSwarm(
    executor_model_name="gpt-5.4-mini",
    advisor_model_name="gpt-5.4",
)

# Mix providers
swarm = AdvisorSwarm(
    executor_model_name="gpt-5.4-mini",
    advisor_model_name="claude-opus-4-6",
)

Architecture Details

Shared Context

Both agents read from and write to the same Conversation object. This mirrors the Anthropic diagram where the advisor reads the same context as the executor. The conversation reaches each agent as typed chat turns, not as one pasted string: the agent’s own earlier messages arrive as assistant turns, and everyone else’s arrive as user turns labelled with the speaker’s name (for example Executor: ...). On each turn:

The advisor receives the shared conversation as turns — it sees everything so far
The advisor’s final answer is added to the conversation under the Advisor role
The executor receives the shared conversation as turns — the task, any prior output, and the advisor’s guidance
The executor’s final answer is added to the conversation under the Executor role

Only each agent’s final message is recorded, not the full transcript that Agent.run returns for its output_type.

Advisor Budget

The max_advisor_uses parameter controls how many times the advisor is consulted:

`max_advisor_uses`	`max_loops`	Behavior
`0`	`1`	Executor runs alone — no advisor
`1`	`1`	Advisor guides once, executor runs once
`3`	`3`	Advisor guides before each of 3 executor turns
`1`	`3`	Advisor guides first turn only, executor runs 3 turns

Multi-Turn Execution

When max_loops > 1, the executor runs multiple turns. Each turn, it reads the full conversation — including its own previous output and any advisor guidance — so it can build on prior work. The advisor’s budget is distributed across turns: it is consulted before each executor turn until the budget is exhausted.

Source Code

View the source code on GitHub

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

Overview

Installation

Key Features

Attributes

Methods

run()

batched_run()

`call()`

Usage Examples

Basic Usage

Multi-Turn with Advisor Guidance

Custom Executor with Tools

Executor Only (No Advisor)

Different Providers

Architecture Details

Shared Context

Advisor Budget

Multi-Turn Execution

Source Code

​Overview

​Installation

​Key Features

​Attributes

​Methods

​run()

​batched_run()

​__call__()

​Usage Examples

​Basic Usage

​Multi-Turn with Advisor Guidance

​Custom Executor with Tools

​Executor Only (No Advisor)

​Different Providers

​Architecture Details

​Shared Context

​Advisor Budget

​Multi-Turn Execution

​Source Code

Overview

Installation

Key Features

Attributes

Methods

run()

batched_run()

`call()`

Usage Examples

Basic Usage

Multi-Turn with Advisor Guidance

Custom Executor with Tools

Executor Only (No Advisor)

Different Providers

Architecture Details

Shared Context

Advisor Budget

Multi-Turn Execution

Source Code