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

This page was previously a duplicate of the Streaming Responses guide. It now documents the API’s tool mechanisms, which live under this “Tools” section of the docs.

The Swarms API gives an agent access to tools through three independent mechanisms. They can be combined on the same request.

Mechanism	Field	Where	What it gives the agent
Built-in tools	`tools_enabled`	Top level of the `/v1/agent/completions` request body	Search the web (`auto_search`) and scrape a page (`web_scraper`)
Autonomous looper tools	`selected_tools`	`agent_config` (only used when `agent_config.max_loops` is `"auto"`)	Planning, file, and sub-agent tools for the autonomous execution loop
Custom function tools	`tools_list_dictionary`	`agent_config`	Your own function-calling tools, defined with an OpenAI-style JSON schema

Custom function tools (tools_list_dictionary) and structured JSON output (llm_args.response_format) are documented in full, with worked examples and response parsing, on the Structured Outputs & Function Calling page. This page covers the other two mechanisms: built-in tools and the autonomous looper’s tools.

Built-in tools (`tools_enabled`)

The API ships exactly two built-in tools. Enable them by name in the tools_enabled array on the request body — a sibling of agent_config, not a field inside it:

{
  "agent_config": {
    "agent_name": "Research Assistant",
    "model_name": "gpt-4.1",
    "max_loops": 1
  },
  "tools_enabled": ["auto_search", "web_scraper"],
  "task": "Find the latest release notes for the Swarms Python SDK and summarize the changes."
}

Tool	What it does
`auto_search`	Runs a web search and returns results the agent can reason over.
`web_scraper`	Fetches and formats the content of a URL.

Fetch the live catalog of built-in tool names at any time:

curl -X GET "https://api.swarms.world/v1/tools/available" \
  -H "x-api-key: $SWARMS_API_KEY"

{
  "status": "success",
  "tools": ["auto_search", "web_scraper"]
}

Python
TypeScript
cURL

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"}

payload = {
    "agent_config": {
        "agent_name": "Research Assistant",
        "description": "Researches a topic using live web search",
        "system_prompt": "Use search to find current information before answering.",
        "model_name": "gpt-4.1",
        "max_loops": 1,
        "max_tokens": 4096,
    },
    "tools_enabled": ["auto_search", "web_scraper"],
    "task": "Find the latest release notes for the Swarms Python SDK and summarize the changes.",
}

response = requests.post(
    f"{BASE_URL}/v1/agent/completions",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())

const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";

const payload = {
  agent_config: {
    agent_name: "Research Assistant",
    description: "Researches a topic using live web search",
    system_prompt: "Use search to find current information before answering.",
    model_name: "gpt-4.1",
    max_loops: 1,
    max_tokens: 4096,
  },
  tools_enabled: ["auto_search", "web_scraper"],
  task: "Find the latest release notes for the Swarms Python SDK and summarize the changes.",
};

const response = await fetch(`${BASE_URL}/v1/agent/completions`, {
  method: "POST",
  headers: {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const result = await response.json();
console.log(JSON.stringify(result, null, 2));

curl -X POST "https://api.swarms.world/v1/agent/completions" \
  -H "x-api-key: $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "agent_name": "Research Assistant",
      "description": "Researches a topic using live web search",
      "system_prompt": "Use search to find current information before answering.",
      "model_name": "gpt-4.1",
      "max_loops": 1,
      "max_tokens": 4096
    },
    "tools_enabled": ["auto_search", "web_scraper"],
    "task": "Find the latest release notes for the Swarms Python SDK and summarize the changes."
  }'

Billing

Tool	Cost
`auto_search`	$0.04 per request
`web_scraper`	$0.15 per request

Each built-in tool listed in tools_enabled is charged once per agent completion request, at the moment the request is set up — not per individual search or scrape the agent performs during its run, and regardless of whether the agent ends up calling the tool at all while completing the task. Only enable a tool for requests that actually need it.

Current per-unit prices are also available from GET /v1/usage/costs (usage_pricing.search_cost, usage_pricing.scrape_cost) rather than hardcoding them, since they can change.

Autonomous looper tools (`selected_tools`)

When agent_config.max_loops is set to "auto", the agent runs in an autonomous execution loop backed by its own internal tool set — separate from tools_enabled and tools_list_dictionary. Use agent_config.selected_tools to restrict which of these tools are available; omit it (or pass "all") to allow every tool in the list below.

{
  "agent_config": {
    "agent_name": "Autonomous Coordinator",
    "model_name": "gpt-4.1",
    "max_loops": "auto",
    "selected_tools": ["create_plan", "think", "complete_task", "respond_to_user"]
  },
  "task": "Plan and execute a multi-step research task, reporting back when done."
}

The full set of 12 tools the autonomous loop can use:

Tool	Description
`create_plan`	Create or revise the step-by-step plan for completing the task. Can be called again mid-run to add, split, drop, or reorder steps as the agent learns more.
`think`	Analyze the current situation and decide the next action.
`subtask_done`	Mark a subtask as completed and move to the next step in the plan.
`complete_task`	Mark the main task as complete and provide a comprehensive summary.
`respond_to_user`	Send a message or response to the user — for status updates, questions, or important information.
`create_file`	Create a new file with specified content in the agent’s workspace.
`update_file`	Update an existing file, replacing its contents or appending to it.
`read_file`	Read the contents of a file.
`list_directory`	List files and directories at a given path.
`delete_file`	Delete a file. Irreversible — use with caution.
`create_sub_agent`	Create one or more specialized sub-agents, cached for reuse across task assignments.
`assign_task`	Assign a task to one or more previously created sub-agents; they run asynchronously.

run_bash is not permitted. There is no arbitrary shell-execution tool available through the autonomous loop, regardless of what selected_tools requests — the API filters the tool list down to the 12 above before the agent runs.

create_sub_agent and assign_task power dynamic sub-agent delegation — see Sub-Agent Delegation for a full walkthrough, including how sub-agents inherit the coordinator’s model and tools.

Structured Outputs & Function Calling

tools_list_dictionary custom tools and llm_args.response_format

Sub-Agent Delegation

create_sub_agent / assign_task and the handoffs field

MCP Integration

Connect agents to external MCP servers and their tools

Pricing

Full, current pricing for every billable feature

Getting Started

Clients

Agent Completions

Multi-Agent

Batch

Capabilities

Resources

Swarms Cloud

Tools

Built-in tools (`tools_enabled`)

Billing

Autonomous looper tools (`selected_tools`)

Structured Outputs & Function Calling

Sub-Agent Delegation

MCP Integration

Pricing

​Built-in tools (tools_enabled)

​Billing

​Autonomous looper tools (selected_tools)

​Related resources

Structured Outputs & Function Calling

Sub-Agent Delegation

MCP Integration

Pricing

Built-in tools (`tools_enabled`)

Billing

Autonomous looper tools (`selected_tools`)

Related resources