Python SDK Reference

SynthClient().research namespaces, install, and launch patterns.

Install synth-ai[research] once. Use SynthClient().research for Managed Research and Research Factory.

uv add "synth-ai[research]==0.16.0"
export SYNTH_API_KEY="sk_..."

from synth_ai import SynthClient

research = SynthClient().research

• Python SDK Quickstart — first run end-to-end
• Auto-generated API reference — exhaustive method list from docstrings
• MCP Tool Reference — agent-client parity

Research namespace layout

Member	Role	API reference
research.projects	Create, list, archive projects; setup and workspace	Projects
research.swarms	Launch, preflight, wait, lifecycle	Swarms
research.limits.get()	Organization limit snapshot	Limits
research.factories.tag	Factory Tag sessions	Factories
Swarm handle readouts	Usage, progress, queue, artifacts, logs	Swarm readouts

Prefer nested readouts on the handle returned from swarms.get: handle.usage.get(), handle.snapshots.get(), handle.message_queue.messages.send(...).

Typical run flow (hero API)

from synth_ai import SynthClient

research = SynthClient().research

project = research.projects.create({"name": "Improve eval reliability", "work_mode": "directed_effort"})
project_id = project.project_id

research.projects.setup.prepare(project_id)

preflight = research.swarms.check_preflight(
    project_id=project_id,
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)

handle = research.swarms.create(
    project_id,
    objective="Kickoff message …",
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)

research.swarms.wait(project_id, handle.swarm_id)
print(handle.progress.get())

Launch fields

Common launch fields are documented in Launch Fields. Backend preflight remains authoritative.

Errors

Launch-time denials raise typed exceptions. See Errors and Preflight and Errors.

Versioning

Pin synth-ai[research]==0.16.0 for the current hero contract. The Research SDK, models, and MCP server ship from synth-ai; the standalone managed-research package is a deprecated compatibility shim. See SDK & CLI Changelog.