Swarms API Documentation - Build AI Agents & Multi-Agent Systems

What This Example Shows

How to pass tools_list_dictionary on a per-agent basis inside a swarm
How the same tool schema can be shared across multiple worker agents
A ConcurrentWorkflow of two financial analysts that both call a structured search_topic tool

Every multi-agent architecture on Swarms accepts the same per-agent tools_list_dictionary. The pattern below works identically for SequentialWorkflow, HierarchicalSwarm, AgentRearrange, GroupChat, MixtureOfAgents, and the rest — only the swarm_type changes.

Step 1: Setup

import json
import os

import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

Step 2: Define a Shared Tool Schema

Tools follow the OpenAI function-call schema. Define it once and reuse across agents.

SEARCH_TOOL = {
    "type": "function",
    "function": {
        "name": "search_topic",
        "description": (
            "Conduct an in-depth search on a specified topic, generating a "
            "comprehensive array of highly detailed search queries."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "depth": {
                    "type": "integer",
                    "description": (
                        "Level of thoroughness, 1 (superficial) to 3 (deep)."
                    ),
                },
                "detailed_queries": {
                    "type": "array",
                    "description": "Specific search queries for the topic.",
                    "items": {"type": "string"},
                },
            },
            "required": ["depth", "detailed_queries"],
        },
    },
}

Step 3: Build the Swarm

Two analysts run concurrently, each equipped with the same tool. Each agent independently decides when to call search_topic.

def run_financial_swarm() -> dict:
    payload = {
        "name": "Financial Analysis Swarm",
        "description": "Two analysts research markets in parallel using a shared search tool.",
        "swarm_type": "ConcurrentWorkflow",
        "max_loops": 1,
        "task": "What are the best ETFs and index funds for AI and tech?",
        "agents": [
            {
                "agent_name": "Market Analyst",
                "description": "Analyzes market trends.",
                "system_prompt": "You are a financial analyst expert.",
                "model_name": "openai/gpt-4.1",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "tools_list_dictionary": [SEARCH_TOOL],
            },
            {
                "agent_name": "Economic Forecaster",
                "description": "Predicts economic trends.",
                "system_prompt": "You are an expert in economic forecasting.",
                "model_name": "gpt-4.1",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "tools_list_dictionary": [SEARCH_TOOL],
            },
        ],
    }

    response = requests.post(
        f"{BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=payload,
        timeout=300,
    )
    return response.json()

Step 4: Run It

result = run_financial_swarm()
print(json.dumps(result, indent=2))

Tools are scoped per-agent, not per-swarm. You can give each worker its own toolset — for example, the Market Analyst could get a search_topic tool while the Economic Forecaster gets a different fetch_macro_data tool. The swarm orchestrator does not need to know about either.

Reuse the Pattern

To switch to a different swarm topology, only swarm_type changes:

Goal	`swarm_type`
Run analysts in parallel	`ConcurrentWorkflow`
Chain them one after the other	`SequentialWorkflow`
Have a director synthesize their output	`HierarchicalSwarm`
Route the task to whichever analyst fits	`MultiAgentRouter`
Vote on the best answer	`MajorityVoting`

The tools_list_dictionary on each agent stays exactly the same.

Getting Started

MCP Server Tutorials

Agent Capabilities

Multi-Agent Architectures

Finance & Investing

Healthcare & Life Sciences

Legal, M&A & Diligence

Customer Operations

Defense, Gov & Supply Chain

Marketing, Content & Founder Tools

API Utilities

Migration Guides

Resources

Production

Compatibility & Benchmarks

Tutorials & Integrations

Function Tools in Multi-Agent Swarms

What This Example Shows

Step 1: Setup

Step 2: Define a Shared Tool Schema

Step 3: Build the Swarm

Step 4: Run It

Reuse the Pattern

​What This Example Shows

​Step 1: Setup

​Step 2: Define a Shared Tool Schema

​Step 3: Build the Swarm

​Step 4: Run It

​Reuse the Pattern

What This Example Shows

Step 1: Setup

Step 2: Define a Shared Tool Schema

Step 3: Build the Swarm

Step 4: Run It

Reuse the Pattern