Synth Swarms Python Toolkit
Launch Synth-managed research runs from Python, the terminal, or MCP, then collect answers, sources, and charges.
- Source repo
- synth-laboratories/synth-ai
- Stars
- ★ 81
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Python
- FA score
- 63/100 · Some gaps
At a glance
- How it runs
- Works with
- Platform-specific
- Setup effort
- Low · running in minutes
- You'll need
- 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.
- Developers who need to submit budgeted Synth Swarms runs from Python research scripts and capture answers, sources, and charges.
- Researchers who want to sign in, choose a run profile, launch a task, and wait for completion in a terminal.
- Teams that need to upload a Markdown, text, or JSON task file and attach it as run input.
- API users who need to inspect published profile descriptions, revisions, routing support, and caller-specific availability.
- 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-aipip install 'synth-ai[mcp]'
- Environment variables
SYNTH_API_KEYSYNTH_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 loginHow 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 --waitSet 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?
- 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.
- 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?
Why each dimension lost points
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.
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.
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.
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.
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.
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.
- 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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
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 ↗ -
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 ↗ -
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?
Do I need an API key?
SYNTH_API_KEY to call the Synth API. SYNTH_API_BASE_URL is optional.Can I use my own run profile?
What are the upload limits?
upload_text and MCP swarms_upload_file accept up to 32 KiB inline.Does MCP support mean hosted OAuth is available?
Is Synth Swarms Python Toolkit open source?
Is Synth Swarms Python Toolkit safe to use?
Is Synth Swarms Python Toolkit still maintained?
Who makes Synth Swarms Python Toolkit?
What is Synth Swarms Python Toolkit's official website?
Thanks — we use this to improve the page.