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.13.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.runs	Launch, preflight, wait, lifecycle	Runs
research.limits.get()	Organization limit snapshot	Limits
research.factories.tag	Factory Tag sessions	Factories
Run handle readouts	Usage, progress, queue, artifacts, logs	Run readouts

Prefer nested readouts on the handle returned from runs.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.runs.check_preflight(
    project_id=project_id,
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)

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

research.runs.wait(project_id, handle.run_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.13.0 for the current hero contract. See CHANGELOG.