Skip to main content

Multi-Agent Swarm

A team of AI agents for the jobs people actually do: research, building apps, writing, data analysis, code review, translation, and thousands of small tasks. Every result is checked by something other than the model's opinion.

Command Checked by
Research a question, with citations swarm research "question" quotes matched against the pages read; each cited claim checked against its quotes
Build an app (frontend, backend, CLI) swarm build "description" --out app --allow-execution its own tests, installed and run; failures go to a fixer
Write a long document swarm write "brief" --words 3000 outline, section lengths, an edit pass that must keep every section
Analyze a CSV swarm analyze data.csv "question" --allow-code-execution every number must come from code that ran on your data
Review a codebase swarm review ./repo each finding must quote code that is really in the file
Translate, summarize or rewrite long documents swarm doc translate file.md --to German one glossary for every chunk; length checks
Thousands of small text, code or web tasks swarm run tasks.jsonl exact answers, regexes, tests, or grounded sources

Work is split into parts that run in parallel. The parts share one plan so they fit together, and agents never chat with each other. It runs on Claude or on any OpenAI-compatible model (DeepSeek, Together, OpenRouter, vLLM ...), always with a hard dollar cap. Web search is free through TinyFish. Guides: deep research, build, write, analyze, review, batch tasks.

Deep research

Parallel workers each research one part of your question. They search the web and read the sources themselves. Code then checks every quote a worker cites against the page it actually read, and throws away quotes that don't match. Once the report is written, each cited sentence is checked again against those quotes, and anything unsupported is marked.

CI Python Tests License Docs

pip install "multi-agent-swarm[all]"
export ANTHROPIC_API_KEY=...    # Claude
export TINYFISH_API_KEY=...     # free search + fetch: https://agent.tinyfish.ai/api-keys
swarm research "How do heat pumps compare to gas boilers in cold climates?" --out report.html

Try it with no keys and no cost first: swarm research "any question" --mock --out demo.html.

Features

Free web search TinyFish Search and Fetch as Claude tools: free within a daily allowance (12,000 searches and 1,000 pages per day). Claude's server-side search ($10 per 1,000 searches) is optional.
Checked citations every quote is matched against the retrieved text; every cited claim is checked against its quotes; unsupported claims are marked in the report
Predictable cost an estimate before the run, the actual cost after it, and a hard cap (--max-usd; presets default to $0.75, $2 or $6)
Safe by default web text treated as data, not instructions; findings with injected instructions excluded; reports stripped of images, HTML and unknown links
Your documents PDFs, Markdown, HTML and text files as sources (--docs), alone or alongside the web
Follow-ups --follow-up report.json researches only what's new and rewrites the report
Source filters domain allow/block lists, recency, news or research papers, language
Exports Markdown, JSON, and self-contained HTML with hover-over source quotes
Web UI and REST API swarm serve: live progress, history, downloads, follow-ups; research, write and doc jobs over HTTP
Production-ready server a durable job queue with crash recovery, scalable swarm worker processes, per-user API keys with daily budgets and rate limits, Prometheus metrics, JSON logs; Docker Compose with HTTPS, Kubernetes and systemd setups (docs/deployment.md)
Local cache repeated searches and pages cost nothing and use no quota
Batch tasks swarm run tasks.jsonl: thousands of small text, code or web-lookup tasks, each checked (exact answer, regex, tests run in a sandbox, or grounded sources), retried at higher effort and capped in dollars (docs/tasks.md)
Any model provider Claude, or any OpenAI-compatible API such as DeepSeek, Together, OpenRouter or vLLM (--base-url, --model, --price)

How it works

question ─► cost estimate (refuse if over the cap)
         ─► plan: independent sub-questions, count scaled to the question
         ─► one worker per sub-question, in parallel (a code scheduler, not an LLM manager)
              tools: web_search / web_fetch (TinyFish), search_documents / read_document (your files)
              answer = text + sources with VERBATIM quotes
              code: drop any quote not found in the retrieved text
              gate: ≥ 2 grounded sources from ≥ 2 domains, no injection markers
              weak finding → re-researched at higher effort (low → medium → high)
         ─► synthesis from clean findings only, inline [n] citations
         ─► reference check → claim check (each cited sentence vs. its quotes) → sanitise

The design follows the research summarised in docs/research:

  • Parallel workers on broad questions. Breadth-first research is where multi-agent systems have the strongest evidence: Anthropic's research system scored +90.2% over a single agent.
  • No agent-to-agent chat. Inter-agent misalignment is about a third of failures in the MAST study.
  • Verification in code. Adding verification gave +15.6% in MAST, and self-reported confidence turns out to be a weak signal.

Details are in docs/ARCHITECTURE.md.

Usage

swarm research "question" --estimate                          # what will it cost?
swarm research "question" --preset quick --out r.html          # quick | standard | deep
swarm research "question" --news --recency-days 30             # recent news only
swarm research "question" --papers --include-domains arxiv.org,nature.com
swarm research "question" --docs ./papers ./notes.md           # your files + the web
swarm research "question" --docs ./contracts --docs-only       # your files only
swarm research "and costs?" --follow-up r.json --out r2.html   # build on an earlier report
swarm research "question" --base-url https://host/v1 --model MODEL --price 0.10,0.40
                                                               # any OpenAI-compatible provider
swarm run examples/tasks/mixed.jsonl --allow-code-execution    # batch: text, code (tested), web (cited)
swarm serve                                                    # web UI on http://127.0.0.1:8000
swarm doctor --online                                          # check keys and setup
swarm eval --estimate                                          # known-answer evaluation vs a single agent

The full flag reference is in docs/cli.md; config files and environment variables are in docs/configuration.md; the web UI and REST API are in docs/web-api.md.

Deploy

cp deploy/.env.example deploy/.env    # your domain and keys
docker compose -f deploy/compose.yaml up -d --build
docker compose -f deploy/compose.yaml exec api swarm keys create --name alice --daily-usd 5

That gives you HTTPS through Caddy, an API process, workers you can scale, and jobs that survive restarts. Kubernetes and systemd setups are in deploy/; the full guide is docs/deployment.md.

Costs and privacy

  • TinyFish search and fetch: free within the daily allowance.
  • Claude: charged per token. For example, claude-opus-5-5 costs $4 per million input tokens and $20 per million output tokens; --worker-model claude-sonnet-5-5 makes the workers cheaper.
  • Data flow: your question and retrieved text go to Anthropic, and search queries go to TinyFish. Caches stay on your machine. There is no telemetry. See docs/privacy.md.

Engine

Under the research layer sits a general cost-aware, fault-tolerant scheduler for large LLM workloads (swarm run, swarm bench). It has:

  • a pull-based queue sized to the fewest agents that still finish fast;
  • multi-task batching, with batch size and effort learned online by Thompson sampling;
  • effort escalation for failed tasks only;
  • an AIMD rate limiter that understands Anthropic's 429 types;
  • a circuit breaker, request hedging, a token budget and a write-ahead journal;
  • a Batches API backend at half price.

On a simulated hostile endpoint it is 7.5–11× cheaper per task and 2.7–4.6× faster than a naive swarm, with 4–4.6× fewer agents. These are the ranges over 18 runs (3 endpoint profiles × 6 seeds, 500 tasks each). Against the hand-tuned v1 rules it is roughly even (0.87–1.17× the cost, 0.83–1.42× the speed); its gain there is reliability. Wall time is measured in real time, so small runs (--n 120) vary much more.

Cost vs time

Development

pip install -e '.[dev]'
make lint test        # ruff, mypy, 136 tests (all offline: no keys, no cost)
make bench chart      # engine benchmark + charts

See CONTRIBUTING.md. Report vulnerabilities privately: see SECURITY.md.

swarm/
  research.py   deep research: planner, tool-using workers, quote grounding, synthesis, claim check
  search/       TinyFish (free), local documents (BM25), disk cache, mock
  app.py        options → configured run (shared by CLI and server)
  server.py     REST API + web UI (web/index.html), job store, SSE progress
  export.py     Markdown / JSON / safe self-contained HTML
  safety.py     prompt-injection detection, report sanitising
  pricing.py    list prices, run cost, estimates
  evaluate.py   known-answer evaluation vs a compute-matched single agent
  orchestrator.py, policy.py, reliability.py, limiter.py, backends.py   the scheduling engine

Roadmap

  • Publish swarm eval results on live search, then scale to a BrowseComp-style set.
  • Semantic (meaning-based) matching of quotes and claims, alongside exact matching.
  • Per-message effort escalation, so the prompt cache survives across effort levels.
  • More search providers, and OpenTelemetry traces.

MIT licensed. Not affiliated with Anthropic or TinyFish.

Metadata

Release files for multi-agent-swarm 3.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for multi-agent-swarm 3.3.2
File Size Uploaded Provenance Actions
multi_agent_swarm-3.3.2.tar.gz 158.3 kB With provenance Details for multi_agent_swarm-3.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for multi-agent-swarm 3.3.2
File Interpreter ABI Platform Actions
multi_agent_swarm-3.3.2-py3-none-any.whl Python 3 none any Details for multi_agent_swarm-3.3.2-py3-none-any.whl

Total release size: 304.0 kB

Release files / multi_agent_swarm-3.3.2.tar.gz

Download URL multi_agent_swarm-3.3.2.tar.gz
Size 158.3 kB
Tags Source
SHA-256 checksum
How to use checksums
41dda03051216a7d841dd14fa1588477ba20c33e0a547c32976572bd6235939b
BLAKE2b-256 checksum
How to use checksums
b3257eb0a429037985e2a162a65e6eb97d8273ac2ca3e2c683bbf750c8ad524d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / multi_agent_swarm-3.3.2-py3-none-any.whl

Download URL multi_agent_swarm-3.3.2-py3-none-any.whl
Size 145.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
31c64de78956e75ae677ac36fb0d3247ee848043e753c4db57bfc35a345e0a4b
BLAKE2b-256 checksum
How to use checksums
a3622823f4760dd3aae91de0030cb7b9ea2e95ded75f369d3b5bc488a8c4f4c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for multi-agent-swarm 3.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for multi_agent_swarm-3.3.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page