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.13.0"
export SYNTH_API_KEY="sk_..."

from synth_ai import SynthClient

research = SynthClient().research

run = research.runs.start(
    "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("run:", run.run_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.runs.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.runs.start(
    "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 one-time Managed Research credits, 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. Pro and Team plans add higher included usage and higher active run limits. Use preflight before launching when you want structured blockers without spending runtime. A 402 response usually means 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:

​Prerequisites

​Start a one-off run

​Inspect the run

​Use a project when context matters

​Limits and launch denials