Skip to main content
Managed Research runs are designed to leave a reviewable trail.

​
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 smr_get_project_economics from MCP or the matching SDK helpers. Hard stops can come from run budget, monthly budget, timebox, or policy blockers.