Swarms v15

​

Overview

​

Highlights

• Typed chat turns everywhere (15.0.0): shared context arrives as labelled turns, and each agent contributes its answer, not its transcript.
• Token usage (15.0.1, 15.0.2): agent.usage and router.usage report provider token counts, including streaming runs and reasoning tokens. agent.input_tokens estimates the next request.
• Fallback swarms (15.0.1): SwarmRouter(fallback_swarms=[...]) tries the next architecture when one fails.
• MCPDeployer (15.0.3): serve any agent, swarm or callable as an MCP tool behind API keys, a token verifier or your own auth.
• Conversations from prior turns (15.0.3): pass chat-format messages to Agent or run().
• Model catalogue (15.0.3): is_model_available, model_count and get_available_models check names against LiteLLM and OpenRouter.
• Leaner autonomous loop (15.0.1): a glob tool, tool output capped by token budget, and context compression between subtasks.

​

Unreleased

​

New features

• TreeOfThoughts: a reasoning agent that grows a tree of partial solutions, scores and prunes them, and answers from the best path. Every model output is a validated function call. See Tree of Thoughts.
• DecisionModel: a client that asks choice, score and yes/no (noul) questions about a state in one request and returns typed answers with calibrated probabilities. It defaults to TypeSafe’s jev-latest, and model_name="clef" or "clef-flash" uses Cloudflare Workers AI. get_decision_models() lists the available names. See DecisionModel.
• More usage totals: GraphWorkflow.usage sums every node and subgraph, and HeavySwarm.usage includes question generation. See Token usage.
• Autonomous loop budgets: Agent takes max_planning_attempts (default 5), max_subtask_iterations (default 100) and max_subtask_loops (default 20). Each must be at least 1. See Autonomous mode.
• Several skill directories: skills_dir accepts a list of paths. When two directories hold a skill with the same name, the later one wins.
• ToolManager: tool handling moved out of agent.py into a ToolManager built once per agent as agent.tool_manager. Context compression also stops tokenizing the history while its byte size is under budget, which cuts a tool turn from about 770 µs to 162 µs. See ToolManager.

​

Fixes

• Agent.run() raises AgentLLMError once every retry has failed, instead of returning an empty string. fallback_models are now tried, because the error reaches the fallback chain. See Production best practices.
• Selected skills reach the model on every call. They were appended to system_prompt after the LLM was built, so the model never saw them.
• run_stream and arun_stream with max_loops="auto" enter the autonomous loop instead of calling the model without a plan.
• Interactive follow-up input is sent to the model again.
• An agent with tools that answers in plain text no longer records "[] (empty list)" or a tool summary as its answer.
• A failing tool batch runs once per tool_retry_attempts attempt, not twice.
• Agent.run(n=...) passes every input to each sample.
• ConcurrentWorkflow.run, GroupChat’s async run, ReasoningDuo and MajorityVoting.run_concurrently start each run or task from an empty conversation.
• ConcurrentWorkflow returns results in agent order and records each agent’s answer. RoundRobinSwarm records answers too.
• SelfConsistencyAgent gives each sample its own agent, so samples are independent.
• router(task) and router.batch_run(tasks) work for every swarm type. They passed imgs=None, which most swarms rejected.
• CouncilAsAJudge runs its judges on model_name when judge_agent_model_name is unset.
• ModelRouter parses the routing reply before reading it, and CronJob waits for the next interval after a failed run instead of retrying every second.
• MCPDeployer enforces timeout for blocking targets.
• Conversation no longer creates ~/.swarms/conversations, which crashed Agent() on a read-only home directory. It seeds the system prompt only when no history was restored.
• batch_agent_execution works again and returns results in agent order. aggregate() defaults to a live model.
• The CLI help states the real HeavySwarm model default, gpt-5.4.

​

Changed defaults and removals

• temperature defaults to None (was 0.5), so it is left out of the request and the provider’s default applies. Current Claude models rejected the old default.
• dynamic_tools defaults to False (was True). Pass dynamic_tools=True to keep tool schemas behind tool_search.
• The "xml" output type and swarms/utils/xml_utils.py were removed. output_type="xml" now raises ValueError.
• LLMCouncil.run() dropped the query alias. Call run(task), which rejects an empty task.
• swarms/utils/swarm_autosave.py was deleted in favor of WorkspaceManager, and the unused HierarchicalOrderRearrange schema was removed.
• Tool methods moved from Agent to agent.tool_manager, including execute_tools, tool_execution_retry, setup_tools, setup_dynamic_tools, mcp_tool_handling and parse_llm_output. Agent keeps add_tool, add_tools, remove_tool, remove_tools and mcp_enabled.

​

New features

​

Fallback swarms (15.0.1)

from swarms import Agent, SwarmRouter

agents = [
    Agent(agent_name="Researcher", model_name="gpt-5.4", max_loops=1),
    Agent(agent_name="Writer", model_name="gpt-5.4", max_loops=1),
]

router = SwarmRouter(
    agents=agents,
    swarm_type="HierarchicalSwarm",
    fallback_swarms=["SequentialWorkflow", "ConcurrentWorkflow"],
)
result = router.run("Assess whether we should adopt usage-based pricing.")
print(router.active_swarm_type, router.fallback_attempts)

​

Token usage (15.0.1, 15.0.2)

from swarms import Agent

agent = Agent(agent_name="Analyst", model_name="gpt-5.4", max_loops=1)
print(agent.input_tokens)

agent.run("Summarize the main risks of a rate hike.")
print(agent.usage)

​

MCPDeployer (15.0.3)

from swarms import Agent, MCPDeployer

researcher = Agent(
    agent_name="Researcher",
    agent_description="Answers research questions with a short summary.",
    model_name="gpt-5.4",
    max_loops=1,
)

# Serves http://127.0.0.1:8000/mcp as the tool "researcher"
MCPDeployer(researcher, api_keys=["sk-local-dev"], port=8000).run()

​

Conversations from prior turns (15.0.3)

from swarms import Agent

agent = Agent(agent_name="Assistant", model_name="gpt-5.4", max_loops=1)

history = [
    {"role": "user", "content": "Name three primes."},
    {"role": "assistant", "content": "2, 3 and 5."},
]
agent.run("And what did I just ask you?", messages=history)

​

Model catalogue check (15.0.3)

from swarms import get_available_models, is_model_available, model_count

print(is_model_available("claude-sonnet-4-6", include_openrouter=False))
print(model_count(include_openrouter=False, exclude_keywords=["embedding"]))

catalogue = get_available_models()
print(catalogue["count"])

​

Point-to-point patterns (15.0.3)

from swarms import Agent, OneToOne

drafter = Agent(agent_name="Drafter", model_name="gpt-5.4", max_loops=1)
critic = Agent(agent_name="Critic", model_name="gpt-5.4-mini", max_loops=1)

result = OneToOne(sender=drafter, receiver=critic).run("Draft a launch tweet.", max_loops=2)

​

Autonomous loop upgrades (15.0.1)

​

HierarchicalSwarm shows its plan (15.0.0)

​

Wider tracing (15.0.3)

​

Package version (15.0.1)

import swarms

print(swarms.__version__)

​

Improvements

​

Bug fixes

• AutoAgentBuilder accepts agent_kwargs without raising TypeError (15.0.0).
• tools=[] no longer enables the deferred-tool machinery with an empty catalog (15.0.0).
• A reused autonomous agent no longer grows its system prompt by a handoff block on every run (15.0.0).
• A caller-supplied saved_state_path is no longer overwritten (15.0.0).
• AgentRearrange.remove_agent removes by name instead of always raising (15.0.0).
• SwarmRouter(list_all_agents=True) no longer raises at construction (15.0.0).
• GraphWorkflow fan-in labels each predecessor’s output correctly when one is missing (15.0.0).
• GroupChat can seat a speaker again: bids returned as strings scored 0.0 for every agent (15.0.0).
• DebateWithJudge, one_on_one_debate and the expert panel pass each speaker’s answer, with names, rather than transcripts or a Python list repr (15.0.0).
• The hierarchical structured-communication evaluator’s score is parsed instead of hard-coded, so its early stop can fire (15.0.0).
• MixtureOfAgents labels each worker contribution with its layer (15.0.1).
• Failed MCP tool calls are reported as failures under mcp 2.x (15.0.1).
• return_all_except_first_string drops one message, not two (15.0.1), and "all-except-first" output no longer drops a swarm’s first agent answer (15.0.3).
• Wrapped Args: lines in docstrings no longer truncate tool-schema descriptions (15.0.1).
• HierarchicalSwarm raises when every loop failed, instead of returning a normal-looking transcript (15.0.3).
• Conversation.add_multiple_messages works on machines with fewer than four CPUs and returns what it added, in order (15.0.3).
• The HeavySwarm default variant no longer crashes, the medium variant gets the right questions, and HeavySwarm runs on Claude. The question decomposer also sees the image (15.0.3).
• In auto mode, agent.run() shapes its result by output_type on every exit path (15.0.3).
• Over-length run_bash file writes point the model at create_file (15.0.3).

​

Removals and breaking changes

• The deprecated AOP module (swarms/structs/aop.py) and its examples were deleted (15.0.0). To serve agents over MCP, use MCPDeployer.
• The HierarchicalSwarm live dashboard was removed (15.0.0). interactive still prompts for a task when run() gets none. HierarchicalSwarm.arun, arun_stream and run_stream were removed too.
• "auto" and "BatchedGridWorkflow" are no longer SwarmRouter swarm types (15.0.0). Neither could run. BatchedGridWorkflow still works on its own.
• reasoning_effort defaults to None again (was "medium" in v14), so tool calls work on OpenAI reasoning models by default (15.0.0).
• Conversation.return_messages_as_list returns message dicts. The "role: content" strings moved to return_messages_as_strings (15.0.0).
• SocialAlgorithms retired enable_communication_logging, parallel_execution and max_workers. Old arguments are still accepted and ignored (15.0.0).
• ReasoningDuo’s internal agents are named <agent_name>-reasoning and <agent_name>-main (15.0.0).
• The Artifact class and swarms.artifacts package were removed (15.0.1).
• various_alt_swarms.py was split into one_to_one.py, broadcast.py and one_to_three.py (15.0.3).
• Four helpers with no callers were deleted: query_ragent, find_multiple_agents_by_name, track_history and coordinate_workflow (15.0.3). MultiAgentRouter.get_agent_response_schema went in 15.0.0.
• An unnamed Conversation is named conversation-<8 hex> instead of conversation-test (15.0.3).

​

Conclusion