Swarm

Lets your agent spin up a team of specialised sub-agents that collaborate autonomously via handoffs to solve a complex task. This is a meta-agent tool where the model defines each agent’s name and role; the tool resolves those specs through an authority-mode system, builds the agents, runs the swarm, and returns a consolidated result.

Use the factory to control safety limits, lock down instructions or tools with axis policies, or supply named presets the model can select from.

Supported in: Python, TypeScript (Node.js, browsers).

Example:

TypeScript

import { Agent } from '@strands-agents/sdk'
import { swarm } from '@strands-agents/sdk/vended-tools/swarm'

const agent = new Agent({ tools: [swarm] })
await agent.invoke(
  'Research the pros and cons of microservices vs monoliths and write a summary'
)

Custom configuration with makeSwarm. maxAgents caps agents per call; the other limits pass through to Swarm: maxSteps caps total agent executions, and timeout and nodeTimeout are in milliseconds.

import { Agent } from '@strands-agents/sdk'
import { Choice, Fixed, Inherit, Preset } from '@strands-agents/sdk/multiagent'
import { makeSwarm } from '@strands-agents/sdk/vended-tools/swarm'
import { httpRequest } from '@strands-agents/sdk/vended-tools/http-request'
import { webFetch } from '@strands-agents/sdk/vended-tools/web-fetch'

const swarm = makeSwarm({
  presets: {
    researcher: new Preset({
      instructions: 'You search for and synthesise information.',
      tools: ['http_request', 'web_fetch'],
      description: 'Gathers raw information from the web.',
    }),
    writer: new Preset({
      instructions: 'You write clear, engaging prose.',
      description: 'Turns research into polished text.',
    }),
  },
  defaultPreset: 'researcher',
  instructions: new Choice([
    'You are a researcher.',
    'You are a writer.',
    'You are an editor.',
  ]),
  tools: new Inherit(),
  model: new Fixed('us.amazon.nova-pro-v1:0'),
  maxAgents: 5,
  maxSteps: 15,
  timeout: 300_000,
  nodeTimeout: 120_000,
  repetitiveHandoffDetectionWindow: 6,
  repetitiveHandoffMinUniqueAgents: 3,
})
const agent = new Agent({ tools: [swarm, httpRequest, webFetch] })
await agent.invoke('Write a blog post about AI agents')

Python

from strands import Agent
from strands.vended_tools import swarm

agent = Agent(tools=[swarm])
agent("Research the pros and cons of microservices vs monoliths and write a summary")

Custom configuration with make_swarm. max_agents caps agents per call; the other limits pass through to Swarm: max_handoffs and max_iterations cap handoffs and agent executions separately, and execution_timeout and node_timeout are in seconds.

from strands import Agent
from strands.multiagent.spec import Choice, Fixed, Inherit, Preset
from strands.vended_tools import make_swarm
from strands.vended_tools import http_request, web_fetch

swarm = make_swarm(
    presets={
        "researcher": Preset(
            instructions="You search for and synthesise information.",
            tools=["http_request", "web_fetch"],
            description="Gathers raw information from the web.",
        ),
        "writer": Preset(
            instructions="You write clear, engaging prose.",
            description="Turns research into polished text.",
        ),
    },
    default_preset="researcher",
    instructions=Choice(["You are a researcher.", "You are a writer.", "You are an editor."]),
    tools=Inherit(),
    model=Fixed("us.amazon.nova-pro-v1:0"),
    max_agents=5,
    max_handoffs=10,
    max_iterations=15,
    execution_timeout=300.0,
    node_timeout=120.0,
    repetitive_handoff_detection_window=6,
    repetitive_handoff_min_unique_agents=3,
)
agent = Agent(tools=[swarm, http_request, web_fetch])
agent("Write a blog post about AI agents")

Full API reference: TypeScript

Tags

tool-authoring26