Agents

Start an agent run in the background

Give the computer a job and walk away: the same loop as POST /computers/{id}/agent, with the same body except stream (refused) and store: false (refused: a background run is kept so it can be read back), started and then read back by id instead of streamed. The run goes on when this request ends, and is not cut at the edge after 120 seconds the way a non-streaming agent call is.

This answers 202 once the run holds the computer, with the run as it stands (status: "running"). What refuses a run before that — an unknown or just-deleted computer (404), one not running (409), one already driven or whose workspace is changing (409 with reason: "contention"), a credential refused, the funded credit hold — is answered here as its own status with {error, reason?, top_up_url?}, and no run is recorded. Everything after it, the model API’s errors included, ends the run as failed with that error.

Poll GET /agent/runs/{run} for its steps, cost and ending, or cancel it with POST /agent/runs/{run}/cancel. A run keeps its thread as the agent route does, and thread_id on the run says which. X-Model-Key is held in memory for the run’s life and never stored. The run uses the API key that started it: deleting that key stops it at its next step, as on the agent route. A run the control plane was executing when it restarted is marked interrupted, with the steps it had taken; it is not resumed. Inspect the desktop before starting another.

The screenshot each step returns, the one the model is shown next, is kept with the run for seven days (within per-run and per-account size limits) so the run can be replayed step by step on the computer’s Activities tab in the dashboard. Those screenshots show whatever was on the screen, so treat them as being as sensitive as the desktop. They are deleted with the run, and with its computer.

Requires the member role or higher.

post/computers/{id}/agent/runs

Request

  • Base URL: https://app.mandala.computer/api/v1
  • URL: https://app.mandala.computer/api/v1/computers/{id}/agent/runs
  • Auth: HTTP bearer

Path parameters

idstring required

The computer id.

Headers

X-Model-Keystring

As on POST /computers/{id}/agent. Held in memory while the run goes, and never stored.

Request body

promptstring required

What you want done, in plain language. Required.

systemstring

A system prompt for the model. Requires your own X-Model-Key.

max_cost_usdnumber

As on POST /computers/{id}/agent.

max_stepsinteger

As on POST /computers/{id}/agent: defaults to 20, at most 100.

provider'anthropic' | 'openai'

As on POST /computers/{id}/agent.

modelstring

As on POST /computers/{id}/agent.

thread_idstring

A thread to continue, as on POST /computers/{id}/agent.

storeboolean

As on POST /computers/{id}/agent. Default true.

Response

The run, running.

idstring required

run_ and twenty-four hex characters.

computer_idstring required
thread_idstring nullable required

The thread the run is kept in, once it is: null until a new thread has something in it (a run that has not acted yet, or failed before it did), and when the thread was deleted. Continue it with thread_id on the next run.

status'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted' required

completed: the loop ended on its own, and result.stop says how — only end_turn means the task was finished. failed: see error. cancelled: stopped by a cancel. interrupted: the control plane restarted while it was going (error.status 503), or the run stopped without its ending being recorded (error.status 500); it was not resumed.

promptstring required

The prompt, at most 32,000 characters of it.

modelstring required

The model the run was started with.

max_stepsinteger required
stepsinteger required

How many actions it has taken so far.

cost_usdnumber

Funded runs: the charge so far, in USD.

created_atstring required
updated_atstring required

When it last took a step or changed status.

ended_atstring nullable required

When it ended; null while running.

Changes

No recorded changes to this operation across all 1 revision of this API.