Managed Research Quickstart

This quickstart starts a one-off Managed Research run and reads back the evidence it leaves behind. Use MCP when an agent client is driving the workflow. Use Python when you want a repeatable script. Install once: synth-ai[research] with SynthClient().research. Managed Research and Research Factory share that surface.

Prerequisites

A Synth account.
A SYNTH_API_KEY.
A repo or research target the worker can inspect.

Start a one-off run

MCP
Python

codex mcp add managed-research --url https://api.usesynth.ai/mcp

Ask your MCP client:

Start a Managed Research one-off run with directed effort mode.
Use host_kind daytona, provider openrouter, runbook lite, and this message:
"Inspect the repo context, propose the smallest high-impact improvement, and leave evidence."

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

from synth_ai import SynthClient

research = SynthClient().research

run = research.swarms.create(
    objective="Inspect the repo context, propose the smallest high-impact improvement, and leave evidence.",
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)

print("project:", run.project_id)
print("swarm:", run.swarm_id)

Inspect the run

MCP
Python

Ask your MCP client:

Show the latest Managed Research run state, messages, task counts, artifact manifest, and usage.

Useful tools include smr_get_run, smr_get_run_execution, smr_get_run_transcript, smr_list_run_artifacts, smr_get_artifact_content, smr_list_run_actor_logs, and smr_get_run_usage.

result = run.wait(timeout=60 * 60, poll_interval=15)

print("state:", result.state.value)
print("stop reason:", result.stop_reason_message or result.stop_reason)
print("tasks:", run.task_counts())
print("actors:", run.actor_counts())

for message in run.messages(limit=20):
    print(message.get("role"), message.get("status"), message.get("body", "")[:120])

manifest = run.artifact_manifest()
print("output files:", [artifact.path for artifact in manifest.output_files])

for artifact in run.artifacts():
    print(artifact.artifact_id, artifact.artifact_type, artifact.title)

Runs normally move through queued, planning, executing, and finalizing before reaching done. Terminal outcomes include done, failed, blocked, or a stopped state when a budget, timeout, operator action, or launch/runtime policy ends the run. Treat a terminal state as stable: inspect the stop reason, artifact manifest, usage, and final report before starting follow-up work.

Use a project when context matters

Projects are reusable control units for repos, files, datasets, credentials, notes, budgets, and project knowledge.

from synth_ai import SynthClient

research = SynthClient().research

created = research.projects.create_runnable({"name": "Improve my eval runner"})
project_id = created.project_id

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

if not preflight.get("clear_to_trigger"):
    raise RuntimeError(preflight.get("resolution_reason") or "Run is not ready to start")

run = research.swarms.create(
    objective="Inspect the eval runner, fix the highest-leverage issue, and explain the evidence.",
    project_id=project_id,
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)

Attach repos, credentials, and files in the web console or via MCP (smr_attach_source_repo, smr_work_repos_attach, provider key tools).

Limits and launch denials

Free plans include Managed Research allowance, lite runbooks, directed_effort, standard model access, and one active run at a time. Beta Access can unlock heavy, open_ended_discovery, and all-model access on top of the base plan. Standard and Max plans add higher included usage windows and higher active-run limits. Use preflight before launching when you want structured blockers without spending runtime. A 402 response usually means included usage, flex-credit, or budget headroom is not available. A 429 response usually means a rate, capacity, or concurrent-run cap is active. User-fixable denials should name the blocking resource, such as credits, agent_codex, sandbox, active-run capacity, unsupported harness, unsupported model, or missing provider credentials. See Preflight and Errors.

What just happened

Synth provisioned a hosted workspace, gave workers the launch message and project context, tracked durable run state, and exposed the evidence stream for review. Next, choose the detailed path:

Getting Started