Managed Research Quickstart

Start one hosted research run, then read back state and artifacts.

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

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."

Python

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

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_actor_status, smr_search_project_logs, smr_list_artifacts, smr_get_artifact_content, and smr_get_usage.

Python

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.

project = client.projects.create(name="Improve my eval runner")
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:

• MCP Quickstart
• Python SDK Quickstart
• Launch Fields
• Runs and Evidence