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.

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

import os

from managed_research import ManagedResearchClient

client = ManagedResearchClient(api_key=os.environ["SYNTH_API_KEY"])

run = client.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)

Use a project when context matters

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

created = client.projects.create_runnable({"name": "Improve my eval runner"})
project = client.project(created.project_id)
project.repositories.attach(github_repo="owner/repo")
project.context.set_project_knowledge(
    "Focus on benchmark reliability, reproducibility, and clear run evidence."
)

preflight = project.runs.preflight(
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)

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

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

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

​What just happened

Prerequisites

Start a one-off run

Inspect the run

Use a project when context matters

What just happened