Runs and Evidence

Inspect run state, messages, tasks, actors, artifacts, checkpoints, usage, reports, and PRs.

Managed Research runs are designed to leave a reviewable trail.

Launch and state types

ResearchRunLaunchRequest is the released typed launch request. ResearchSwarm is the state model returned by swarm state and wait operations. Import both from the public Research namespace:

from synth_ai.research import ResearchRunLaunchRequest, ResearchSwarm

Most applications launch and inspect runs through SynthClient().research; use these models when a typed application boundary needs to construct a launch request or annotate a returned swarm without adding low-level transport code.

State flow

Runs usually move through:

queued -> planning -> executing -> finalizing -> done
                         |             |
                         v             v
                      blocked        failed

A run may also stop because of budget, timeout, operator action, or launch/runtime failure.

Status and messages

Use status reads for current state and messages for durable communication with the runtime.

MCP tools:

• smr_get_run
• smr_get_run_execution
• smr_get_run_transcript
• smr_list_run_actor_logs

Python:

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

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

Tasks and actors

Task and actor counts help show what the system actually did.

print("tasks:", run.task_counts())
print("actors:", run.actor_counts())

Artifacts and reports

Artifacts include reports, files, diffs, PR metadata, logs, and workflow-specific outputs.

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)

MCP tools:

• smr_list_run_artifacts
• smr_get_run_artifact_manifest
• smr_get_artifact_content

Checkpoints and branches

Use checkpoints before riskier changes or when a long run finds a useful intermediate state.

checkpoint = run.create_checkpoint(reason="before trying a riskier refactor")
retry = run.branch_from_checkpoint(
    checkpoint_id=checkpoint.checkpoint_id,
    mode="with_message",
    message="Try again from this checkpoint with a smaller patch.",
)

Usage

Usage readback helps connect the evidence to spend and budgets. Use smr_get_run_usage, smr_get_project_usage, and resource-limit progress tools from MCP, or handle.usage.get() / client.research.limits.get() from the hero Python SDK.

Hard stops can come from run budget, monthly budget, timebox, or policy blockers.