Start task (streaming)

POST/agent/tasks/stream

Starts an agent task and streams events via SSE (Content-Type: text/event-stream).

Body ParametersJSONExpand Collapse

instruction: string

Instruction is the task prompt for the agent.

agent_icon: optional string

AgentIcon is optional client metadata used by task history UIs. It is captured by go-backend before proxying and ignored by older agent servers.

agent_type: optional string

AgentType is accepted for legacy clients. Current agent servers ignore it.

computer_id: optional string

ComputerID reuses a live computer session, or restores a saved persistent session with the same ID if it is not currently live.

context: optional array of object { content, role }

Context seeds the worker transcript with recent conversation turns, oldest first.

content: string

Content is the text of this prior conversation turn.

role: "user" or "assistant"

Role is the speaker for this prior conversation turn.

One of the following:

"user"

"assistant"

environment_id: optional string

EnvironmentID restores a previous persistent session snapshot. Prefer ComputerID with the saved computer/session ID for new integrations.

harness_version: optional "v1" or "v2"

HarnessVersion selects which agent harness implementation runs the task. "v1" is the stable/core harness with broader shell/search tools. "v2" is the training-aligned GUI harness.

One of the following:

"v1"

"v2"

idempotency_key: optional string

IdempotencyKey deduplicates retried task start requests.

maxLength200

minLength1

keep_alive: optional boolean

KeepAlive is a user-friendly alias for terminate_on_completion=false.

kind: optional "desktop" or "browser"

Kind selects the virtual environment type. Omit to use the agent default: browser when start_url is set, otherwise desktop. Saved computer_id sessions restore using the stored session kind.

One of the following:

"desktop"

"browser"

max_duration_seconds: optional number

MaxDurationSeconds caps wall-clock runtime before the server cancels the task.

maximum86400

minimum1

max_steps: optional number

MaxSteps caps how many agent loop steps can run before max-steps termination.

maximum1000

minimum1

metadata: optional map[string]

Metadata is customer-defined task metadata for correlating with external workflows.

model: optional string

Model is the LLM model to use. Omit to use the agent server default.

on_missing_computer: optional "fail" or "restore" or "create_new"

OnMissingComputer controls fallback when ComputerID is not live: "restore" (default) restores a saved persistent session or returns 404, "fail" always returns 404, "create_new" restores when possible and otherwise creates a fresh computer.

One of the following:

"fail"

"restore"

"create_new"

persistent: optional boolean

Persistent controls whether the computer session should persist state on teardown.

save_session: optional boolean

SaveSession is a user-friendly alias for Persistent.

screenshot_mode: optional "url" or "base64"

ScreenshotMode controls whether task screenshots are emitted as URLs or base64 data URLs.

One of the following:

"url"

"base64"

start_url: optional string

StartURL opens this URL before the agent starts. Omitted kind defaults to browser.

stream_deltas: optional boolean

StreamDeltas streams per-token text deltas as progress_update events when supported.

stream_mode: optional "verbose" or "concise"

StreamMode controls event verbosity. "verbose" emits all events; "concise" emits product-facing progress, screenshots, completion, and errors.

One of the following:

"verbose"

"concise"

system_prompt: optional string

SystemPrompt is appended to the harness system message.

temperature: optional number

Temperature controls LLM sampling temperature. Omit to use the harness default.

maximum2

minimum0

terminate_on_completion: optional boolean

TerminateOnCompletion controls whether the task should terminate its computer automatically. Set false to keep the computer alive for handoff or inspection.

thread_id: optional string

ThreadID is optional client metadata for grouping task history by chat thread. It is captured by go-backend before proxying and ignored by older agent servers.

viewport_height: optional number

ViewportHeight is the browser viewport height in pixels.

maximum2160

minimum240

viewport_width: optional number

ViewportWidth is the browser viewport width in pixels.

maximum3840

minimum320

ReturnsExpand Collapse

TaskStartStreamResponse = string