Multi-Agent Swarm
Ask a question; get a cited research report you can check.
Parallel Claude workers each research one part of your question. They search the web for free through TinyFish 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.
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; Docker image |
| Local cache | repeated searches and pages cost nothing and use no quota |
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 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.
Costs and privacy
- TinyFish search and fetch: free within the daily allowance.
- Claude: charged per token. For example,
claude-opus-5-5costs $4 per million input tokens and $20 per million output tokens;--worker-model claude-sonnet-5-5makes 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 9–12× cheaper per task and about 3–4× faster than a naive swarm, with about 4× fewer agents:
Development
pip install -e '.[dev]'
make lint test # ruff, mypy, 61 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 evalresults 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.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| multi_agent_swarm-3.0.0.tar.gz | 81.1 kB | With provenance | Details for multi_agent_swarm-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| multi_agent_swarm-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for multi_agent_swarm-3.0.0-py3-none-any.whl |
Total release size: 160.0 kB
Release files / multi_agent_swarm-3.0.0.tar.gz
| Download URL | multi_agent_swarm-3.0.0.tar.gz |
|---|---|
| Size | 81.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
08417f40df6dd5ba50d707de8a4aaba9d500842a78828899c8640b7007601dfc
|
|
BLAKE2b-256 checksum How to use checksums |
4b1a602f2dd69fd5aeb14e54907e995399b679e814f3034af61799c814872c5f
|
| 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 logRelease files / multi_agent_swarm-3.0.0-py3-none-any.whl
| Download URL | multi_agent_swarm-3.0.0-py3-none-any.whl |
|---|---|
| Size | 78.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
71bf55a6a34d6d215e32adba2fe481e9a62e292944eeda70b41f71b59c46c006
|
|
BLAKE2b-256 checksum How to use checksums |
33a05fa8fe6901434fbd4aa49ec67960c0a7045de114ceb2f3d005fe3873bd95
|
| 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 logSecurity for multi-agent-swarm 3.0.0
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.
Attestation for multi_agent_swarm-3.0.0.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 logA 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.