Synth Swarms Python Toolkit

Launch Synth-managed research runs from Python, the terminal, or MCP, then collect answers, sources, and charges.

Stars
★ 81
Last updated
1d ago
License
MIT
Primary language
Python

At a glance

How it runs
Library / SDKCLIMCP server
Works with
Platform-specific
Setup effort
Low · running in minutes
You'll need
Python 3.11+Synth public API v1SYNTH_API_KEYShell / CLINetwork accessLocal filesystemMCP Server
Typical use
Developers who need to submit budgeted Synth Swarms runs from Python research scripts and capture answers, sources, and charges.
Not a fit if
  • Teams that need fully offline execution
  • Teams that need a self-hosted research execution service
Website
docs.usesynth.ai/intro ↗ set on GitHub
Maintenance
Commits in the last 30 dayslast commit 2026-11-20latest release v0.23.9 (2026-10-26)
Source review
63/100 · Some gaps

What does this agent do, and when should you use it?

Synth AI is a typed Python 3.11+ client for Synth public API v1, with an SDK, the synth CLI, and an optional stdio MCP server. Users submit a task, budget, and optionally a published run profile and input files; the Swarms API executes the run, and the client can wait for the result and retrieve its answer, source, and charge. The SDK offers both SynthClient and AsyncSynthClient. Runs require SYNTH_API_KEY and can optionally use SYNTH_API_BASE_URL, so execution depends on the Synth API rather than a locally hosted service. The docs support only the latest release; the README identifies the current published release as 0.34.0.

Python code uses SynthClient or AsyncSynthClient to call client.swarms.run(...), submit a research task and budget to the Synth API, and wait for results. client.swarms.profiles() lists available run profiles; research profiles can specify a published task and require its approval. upload_file accepts UTF-8 text, Markdown, or JSON, and the run can reference the upload by immutable file ID, revision ID, and SHA-256 digest. The CLI includes operations such as synth login, synth run, synth profiles, synth logs, synth download, and synth upload. Installing synth-ai[mcp] adds the synth-ai-mcp stdio server, whose MCP tools expose Swarms operations.

  1. Developers who need to submit budgeted Synth Swarms runs from Python research scripts and capture answers, sources, and charges.
  2. Researchers who want to sign in, choose a run profile, launch a task, and wait for completion in a terminal.
  3. Teams that need to upload a Markdown, text, or JSON task file and attach it as run input.
  4. API users who need to inspect published profile descriptions, revisions, routing support, and caller-specific availability.
  5. Developers who need to connect Synth Swarms operations to a client that consumes stdio MCP servers.

Key setup facts

Pulled from the install and usage notes below. The project README has the current values.

Install / run
  • pip install synth-ai
  • pip install 'synth-ai[mcp]'
Environment variables
SYNTH_API_KEY SYNTH_API_BASE_URL
Runtime
Python 3.11+

How do you install or deploy this agent?

Requires Python 3.11+. Install the SDK and CLI; install the extra for MCP use. Configure the API key and sign in to the CLI:

pip install synth-ai
pip install 'synth-ai[mcp]'
export SYNTH_API_KEY="your-api-key"
synth login

How do you use this agent?

Launch a run and retrieve its result from Python:

from synth_ai import SynthClient

with SynthClient() as client:
    run = client.swarms.run("Compare retrieval methods", budget="2.00")
    print(run.run_id, run.state)
    result = client.swarms.result(run)
    print(result.answer)

Or launch and wait from the terminal:

synth run "Solve this task" --budget 2.00 --profile swarms-v2 --wait

Set SYNTH_API_KEY; set SYNTH_API_BASE_URL if you need a custom API address. Async applications can use AsyncSynthClient with await.

What are this agent's strengths and limitations?

Pros
  • One package provides a typed Python SDK, CLI, and optional stdio MCP server.
  • The result interface includes the final answer, source, and charge for downstream script handling.
  • Supports uploads with immutable revision and digest references; files and launches allow up to 32 MiB, with up to 32 file references.
  • The run profile catalog reports descriptions, revisions, routing support, and caller-specific availability.
Limitations
  • Runs depend on Synth public API v1 and an API key; the README documents no offline or local execution mode.
  • Only the latest published release is supported, which may require migration for older-version users.
  • Uploads are limited to UTF-8 text, Markdown, and JSON; inline uploads are capped at 32 KiB.
  • The documented qualification smoke flow incurs charges and explicitly does not establish hosted MCP OAuth, provider-invoice finality, or load and capacity acceptance.

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
Synth Swarms Python Toolkit This agent 63 · Some gaps Library / SDK ★ 81 1d ago Python —
NotebookLM Python Automation 76 · Good CLIFree + model costs ★ 20k 1d ago Python Codex · Claude Code · Claude.ai
Taisly Video Publishing Kit 71 · Some gaps CLIFreemium ★ 211 1mo ago JavaScript Codex · Claude Code
mcp-agent 60 · Some gaps FrameworkFree + model costs ★ 8.6k 9mo ago Python Claude.ai · OpenAI API · Claude API

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Some gaps
63/ 100 5-point scale 3.2 / 5
Trust 16/29
Reliability 8/14
Adaptability 12/18
Convention 13/18
Effectiveness 9/13
Verifiability 5/8
Why each dimension lost points
Trust16 / 29 · 2.8/5

The SDK, CLI, and MCP expose operations against the public API; runs require a budget, mutations require idempotency keys, and the docs describe pause, resume, and cancel. Uploads, runs, and billing have external effects, but the packet does not show fine-grained permissions or a general confirmation flow. The MCP example places the API key in an environment variable without showing broader secret-protection controls. Dependencies have version ranges but no security audit evidence. Publisher identity is unverified; the license attribution alone does not establish publisher ownership.

Reliability8 / 14 · 2.9/5

The docs provide an error guide, shared error codes, CLI exit codes, and timeout semantics, and dependencies have version constraints. However, README claims release 0.34.0 while pyproject.toml specifies 0.38.0, a direct version inconsistency.

Adaptability12 / 18 · 3.3/5

The packet covers Python SDK, CLI, and MCP entry points, including sync and async use, run configuration, and research-task requirements. It describes some scope and file limits, but does not show a full scenario matrix or all environment boundaries.

Convention13 / 18 · 3.6/5

The documentation structure and entry points are clear, with substantial installation, quickstart, and limitation guidance. The MIT license is explicit, and examples cover SDK, CLI, MCP, and uploads. Conflicting version numbers, no changelog in the packet, and no clear maintenance owner lower naming stability, version tracking, and responsibility scores.

Effectiveness9 / 13 · 3.5/5

The product offers a typed API, run lifecycle controls, result and charge lookup, and CLI and MCP access. Budgets and output guidance support practical use, but the evidence does not quantify relative value or user cost, so these scores remain moderate.

Verifiability5 / 8 · 3.1/5

Usage, installation, and limitations can be traced across the README, quickstart, project configuration, and source. CI lists checks, but this static review did not execute or independently verify them. Multiple files support the main interface descriptions, while the release-version conflict weakens consistency. Some limitations are explicit, but the packet does not systematically label facts versus inferences.

Risks and how to mitigate them
  • README and pyproject.toml list release versions 0.34.0 and 0.38.0 respectively; verify the intended package version and contract before installing or upgrading.
  • Runs, uploads, and billing lookups can incur charges or transfer data externally. The examples require an API key; manage it carefully and review budgets and upload contents.
Evidence confidence: Low Reviewed Nov 11, 2026 Reviewed revision 196c892be335 New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/synth-ai.svg)](https://followagents.com/en/agents/synth-ai)
<a href="https://followagents.com/en/agents/synth-ai"><img src="https://followagents.com/badge/synth-ai.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. sdk-qualification-0.24.0-32d61d0c-20261103 SDK 0.24.0 qualified artifact Pre-release
    Release notes excerpt
    Qualified exact SDK 0.24.0 wheel bytes (sha256 64f72a75...) for trusted publication. Source 32d61d0c = dev 3e98a9a6 plus the 0.24.0 version bump; contracts core.v1 b33b2bee, index.v1 72816159, swarms.v1 a1a1c821 match the backend candidate dc8239887d serving staging (staging capability negotiation with these bytes passed). Native Index/Monitor/Swarms E2E are owner-waived in the reviewed release policy for 0.24.0.
    View on GitHub ↗
  2. v0.23.9 SDK 0.23.9
    Release notes excerpt
    Synth AI 0.23.9 retries a hosted Swarms run create refused with the retryable owner_unavailable readiness refusal (503, Retry-After) under a fresh idempotency key, like launch_admission_busy; exhaustion keeps the refusal code and cause. Otherwise identical to 0.23.8: ProjectTemplate.CODE_NATIVE, typed CodeValidation, shipped contract schemas (index.v1, swarms.v1) match the deployed v0.23.2 backend. Install with python -m pip install 'synth-ai==0.23.9'. …
    View on GitHub ↗
  3. v0.23.8 SDK 0.23.8
    Release notes excerpt
    Synth AI 0.23.8 adds ProjectTemplate.CODE_NATIVE and typed CodeValidation for hosted code projects. Verified code publications appear in public Swarms results; repository handles retrieve the graded commit and archive. Shipped contract schemas (index.v1, swarms.v1) match the deployed v0.23.2 backend. Install with python -m pip install 'synth-ai==0.23.8'. Qualified source: a6320c1c7df02531173e02268f09d95fd1785b2a. Wheel SHA256: 93c04fce1bb28e43997bdea576bc57d9a101c0b8eabf581e67aec2cd322839b7.
    View on GitHub ↗

FAQ

How much do runs cost?
The README gives no price list. Runs take a budget parameter and results include the charge; the qualification smoke flow has three $4 run caps, for a $12 aggregate.
Do I need an API key?
Yes. Set SYNTH_API_KEY to call the Synth API. SYNTH_API_BASE_URL is optional.
Can I use my own run profile?
Runs can select published profiles. Research profiles also require a published, approved research task. The README says arbitrary actor overrides are not part of the public API.
What are the upload limits?
Files must be UTF-8 text, Markdown, or JSON. Each file and launch allows up to 32 MiB, with at most 32 file references. upload_text and MCP swarms_upload_file accept up to 32 KiB inline.
Does MCP support mean hosted OAuth is available?
The README documents an optional stdio MCP server and explicitly says the qualification smoke flow does not verify hosted MCP OAuth.
Is Synth Swarms Python Toolkit open source?
Yes. The source code is on GitHub (synth-laboratories/synth-ai) under the MIT licence.
Is Synth Swarms Python Toolkit safe to use?
FollowAgents' FARS review (Nov 11, 2026) scored Synth Swarms Python Toolkit 16/29 on trust and safety. None of the eight safety controls the review checks for was missing outright. The repository has changed since that review.
Is Synth Swarms Python Toolkit still maintained?
Yes. The latest commit on GitHub is from 2026-11-20, within the last 30 days. The latest release is v0.23.9 (2026-10-26).
Who makes Synth Swarms Python Toolkit?
Synth Swarms Python Toolkit is published on GitHub by the account synth-laboratories. FollowAgents has not verified which person or company is behind that account.
What is Synth Swarms Python Toolkit's official website?
The project's GitHub repository lists https://docs.usesynth.ai/intro as its website. That link is set by the repository owner; the source code itself is on GitHub (synth-laboratories/synth-ai).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts