Runs

A run is one execution of an agent or task. Use runs for direct messages, follow-ups, and real-time output.

Run list and detail responses include needs_reply when a completed turn asks for a concrete replyable decision (approve, answer, connect). Show these runs as Needs you, even after they have been viewed or emailed. Soft FYI / out-of-reach notes must not set needs_reply. Agents choose delivery when awaiting: Slack for one quick decision, email for deep/batched asks, or in-app only (channel=none) when the user is already in the run — unattended runs (schedule, webhook, Day-1) must interrupt via Slack or email (none + needs_reply is rejected there). Send the answer with runs.reply(); viewing the run does not answer the ask. On the Platform board, Archive clears a reply-request run from Needs you in one tap (Undo during the exit animation). A newer completed scheduled run of the same task (and user_id) supersedes it, so recurring tasks do not stack stale asks. closing_preview is a short headline for cards; latest_message_preview contains up to 600 characters from the latest assistant message for hover previews.

Create a run

Streaming (default and recommended)

Use the context manager so the stream closes cleanly even if you exit early:

from m8tes import M8tes

client = M8tes()

with client.runs.create(agent_id=1, message="summarize this week's support trends") as stream:
    for chunk in stream.iter_text():
        print(chunk, end="", flush=True)

print(stream.text)  # full accumulated output

import { M8tes } from "@m8tes/sdk";

const client = new M8tes(); // reads M8TES_API_KEY

const stream = client.runs.create({
  agent_id: 1,
  message: "summarize this week's support trends",
});

for await (const chunk of stream.iterText()) process.stdout.write(chunk);

console.log(stream.output); // full accumulated output

See Streaming & Events for event types, text-only streaming, and reconnection, or pass stream=False and poll:

run = client.runs.create(agent_id=1, message="summarize this week's support trends", stream=False)
run = client.runs.poll(run.id)
print(run.output)

import { M8tes } from "@m8tes/sdk";

const client = new M8tes();

const run = await client.runs.createAsync({
  agent_id: 1,
  message: "summarize this week's support trends",
});

// get() reads ONCE. The run may still be running. createAndWait() polls for you.
const done = await client.runs.get(run.id);
console.log(done.status, done.output);

// Stop a run that is still going:
const cancelled = await client.runs.cancel(run.id);
console.log(cancelled.status); // "cancelled"

curl -X POST https://api.m8tes.ai/api/v2/runs \
  -H "Authorization: Bearer m8_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"teammate_id": 1, "message": "summarize this week", "stream": false}'

teammate_id is the wire name for the agent id: JSON request and response bodies keep it. The SDK accepts agent_id (canonical) and teammate_id alike.

Run options

Follow up on a run

A follow-up continues the same run: it re-opens the run, keeps the prior context, and does not consume a new run-count slot (it reuses the original run id and only burns tokens).

For a failed or cancelled run, can_continue indicates that it has a saved, unexpired conversation eligible for runs.reply(). Prefer Continue when this is true; a run that never started needs its original task retried. Reply still checks current funding and permissions.

For an explicit continuation, pass reset_auto_recovery=True in Python or { reset_auto_recovery: true } in TypeScript. This grants a fresh three-attempt recovery budget when the reply is accepted, including when it is queued. Automatic loops should leave this option false. auto_recovery_attempt_count reports attempts in the current budget; auto_retry_count preserves the cumulative history. A later platform update can then recover work you explicitly continued, even if an earlier recovery budget was exhausted.

first = client.runs.create_and_wait(agent_id=1, message="find all open incidents")

with client.runs.reply(first.id, message="now draft an update for each owner") as stream:
    for chunk in stream.iter_text():
        print(chunk, end="", flush=True)

import { M8tes } from "@m8tes/sdk";

const client = new M8tes();

const first = client.runs.create({ agent_id: 1, message: "find all open incidents" });
await first.text(); // drain the first turn; runId is set by then

const followUp = client.runs.reply(first.runId!, "now draft an update for each owner");
for await (const chunk of followUp.iterText()) process.stdout.write(chunk);

runs.reply() inherits the run's settings: permission mode keeps applying, and AskUserQuestion stays enabled on runs created with human_in_the_loop: true. Pass human_in_the_loop: false on the reply to pin non-interactive behavior.

Replying while the run is still executing

A reply works on a live run too. If the run's current turn is still executing, the message is queued and delivered as the run's next turn the moment the current one ends. Never a second concurrent execution. The response tells you which happened:

run = client.runs.reply(42, message="also check the staging env", stream=False)
if run.delivery == "queued":       # run was mid-turn; message delivers next
    print("queued as message", run.queued_message_id)
else:                              # "resumed": it became the next turn now
    print("resumed")

With stream=True on a queued reply, the SDK joins the live run's ongoing stream (the queued message itself delivers on the next turn). Delivery normally starts within seconds of the turn ending; across a platform update it can take up to ~15 minutes (the recovery sweep).

Every queued message resolves observably: run.message_received when queued, then either run.started for its delivery turn or run.message_cancelled with a reason (owner cancelled [agent senders only; your own replies to a run you cancelled still deliver and revive it], sandbox expired, account disabled, or 24h undelivered).

While the run is live, replies with file attachments or per-reply overrides (tools, permission_mode, task_setup_tools, feedback, human_in_the_loop) return 409. Overrides only apply to an immediate resume; silently dropping them would be worse.

This is also how agent-to-agent messaging behaves: when one of your agents messages another agent's run, the message arrives the same way. Queued if the target is busy, delivered as the next turn, and always attributed to the sending agent, never to you.

Structured output

Pass a JSON Schema as output_schema and the run returns typed data on output_data, so you can act on fields instead of parsing prose.

run = client.runs.create_and_wait(
    agent_id=1,
    message="Review this Sentry issue and rate its severity.",
    output_schema={"type": "object", "properties": {"severity": {"type": "string", "enum": ["low", "medium", "high"]}}},
)

if run.output_data:                      # always None-check
    print(run.output_data["severity"])   # -> "high"

Run outcome

GET /runs/{id}/outcome returns the condensed result of a run in one call (the agent's closing message, the structured result, and what the run cost) instead of the full transcript.

outcome = client.runs.outcome(run_id=42)
print(outcome.summary, outcome.cost_usd)  # "Audit done: paused 3 wasteful keywords." "0.4831"
if outcome.needs_reply:                   # the agent is asking for a decision
    client.runs.reply(42, message="Approve both")
if outcome.delivery_channel == "none":      # agent chose silence. No completion email
    pass

import { M8tes } from "@m8tes/sdk";

const client = new M8tes();

const outcome = await client.runs.outcome(42);
console.log(outcome.summary, outcome.cost_usd); // "Audit done: paused 3 wasteful keywords." "0.4831"

if (outcome.needs_reply) {
  // the agent is asking for a decision
  await client.runs.reply(42, "Approve both").text();
}
if (outcome.delivery_channel === "none") {
  // agent chose silence. No completion email on scheduled runs
}

Scheduled delivery (set_run_delivery)

On scheduled and webhook-triggered runs, the agent chooses how the outcome reaches the owner by calling the set_run_delivery built-in tool before its closing message:

Read the choice from runs.outcome().delivery_channel or run.completed webhook data.delivery_channel. Disable the tool with disabled_builtin_tools: ["delivery"] on the agent.

Embed agents (prompt_profile: "bare") do not receive m8tes's delivery playbook in the system prompt. Document set_run_delivery in your agent instructions if scheduled runs should use it.

run_id = 1
outcome = client.runs.outcome(run_id)
if outcome.delivery_channel == "email" and outcome.needs_reply:
    notify_user(outcome.summary, subject=outcome.headline)
elif outcome.delivery_channel == "none":
    logger.info("scheduled run chose silence run_id=%s", run_id)

Legacy NEEDS-REPLY / HEADLINE: marker lines in closing prose are deprecated; delivery_channel, needs_reply, and headline on outcome and webhooks are authoritative.

run.status values: running, paused, awaiting_approval (waiting for user input or approval), completed, failed, cancelled, closed, archived.

Execution environment

Tools run in an isolated, per-account Linux sandbox. m8tes provisions it automatically.

See Computer use for desktop tools.

List runs

sort="priority" puts runs waiting on a human first; the default is newest first.

for run in client.runs.list(sort="priority", limit=20).auto_paging_iter():
    print(run.id, run.status)

Run files

Attach input files with files= on runs.create (see Files). Runs can also generate files; list and download them after execution:

for f in client.runs.list_files(run_id=1):
    print(f.name, f.size)

content = client.runs.download_file(run_id=1, filename="report.csv")

Next: Agents · Tasks · Streaming & Events · Webhook Events