Start an agent task | EmpirioLabs AI Docs

Submits work to an autonomous, long-running agent (file browsing, research, code execution, document drafting). Currently powers Manus.

One endpoint covers both creating a new task and continuing an existing one:

Omit task_id to start a fresh task. The response carries the new task_id you can poll later.
Include task_id to send a follow-up message to a task that is already running. The agent picks up the new input on its next reasoning step.

Lifecycle for a typical interactive flow:

POST /v1/agents/run with input → { task_id }.
Poll GET /v1/agents/{task_id} until status reaches a terminal state (completed, failed, stopped), or stream the response by passing stream: true on the initial call.
To send a follow-up message: POST /v1/agents/run again with the same task_id plus the new input.
To inspect intermediate reasoning: GET /v1/agents/{task_id}/messages.
To cancel early: POST /v1/agents/{task_id}/stop.

Billing accumulates as the agent runs. Partial work is still charged on stop or failure.

Submits work to an autonomous, long-running agent (file browsing, research, code execution, document drafting). Currently powers Manus. One endpoint covers both creating a new task and continuing an existing one: - Omit `task_id` to start a fresh task. The response carries the new `task_id` you can poll later. - Include `task_id` to send a follow-up message to a task that is already running. The agent picks up the new input on its next reasoning step. Lifecycle for a typical interactive flow: 1. `POST /v1/agents/run` with `input` → `{ task_id }`. 2. Poll `GET /v1/agents/{task_id}` until `status` reaches a terminal state (`completed`, `failed`, `stopped`), or stream the response by passing `stream: true` on the initial call. 3. To send a follow-up message: `POST /v1/agents/run` again with the same `task_id` plus the new `input`. 4. To inspect intermediate reasoning: `GET /v1/agents/{task_id}/messages`. 5. To cancel early: `POST /v1/agents/{task_id}/stop`. Billing accumulates as the agent runs. Partial work is still charged on stop or failure.

Authentication

AuthorizationBearer

Pass your EmpirioLabs API key as a bearer token. The Anthropic-style x-api-key header is also accepted on every endpoint.

Request

This endpoint expects an object.

modelstringRequired

inputstringRequired

Instruction for the agent. For a new task this is the initial prompt; for a follow-up (when task_id is set) this is the new message added mid-run.

task_idstringOptional

Optional. When set, the call sends input as a follow-up message to this existing task instead of creating a new one.

attachmentslist of strings or objectsOptional

Files for the agent to work with (any type, audio, video, images, documents, data). Each item is a URL string or an object with url, filename, and mime_type. Files are placed in the agent’s workspace before the task starts. Up to 10 files per message.

streambooleanOptionalDefaults to true

Stream Server-Sent Events as the agent works. When false, the call blocks until the task reaches a terminal state or max_wait_seconds elapses.

agent_profilestringOptionalDefaults to manus-1.6

Upstream agent profile. Available profiles depend on the model (e.g. Manus exposes manus-1.6).

poll_interval_secondsdoubleOptional1-30Defaults to 3

How often the worker polls upstream while waiting on the task. Only relevant when stream is false.

max_wait_secondsdoubleOptional5-1800Defaults to 900

Maximum time the worker will block on a non-streaming call before returning the in-progress task status.

share_visibilitystringOptionalDefaults to public

Manus share-link visibility (public or private).

disable_formattingbooleanOptionalDefaults to false

Skip the EmpirioLabs Markdown wrapper around the agent run. Aliases raw, passthrough, raw_response.

Response

Task accepted. Poll /v1/agents/{task_id} for status.