Connect to a task browser stream

Receive frames/events over WebSocket and send bounded protocol inputs. This is a browser handoff protocol; a successful upgrade is not a JSON query result.

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-runtime-tasks/{task_id}/browser/stream

Before you call this API

First obtain an unexpired short-lived token for the same workspace/task. Browser Origin must match the host or a deployment-allowed Origin. Current identity and role are rechecked at admission and during connection.

Request parameters

const target = new URL(apiBaseUrl);
target.pathname = target.pathname.replace(/\/$/, '') + `/workspaces/${encodeURIComponent(workspaceId)}/agent-runtime-tasks/${encodeURIComponent(taskId)}/browser/stream`;
target.protocol = target.protocol === 'https:' ? 'wss:' : 'ws:';
target.search = '';
target.hash = '';
const socket = new WebSocket(target.toString(), ['moi-browser.v1', token]);

Other variables come from the original task and previous token step. This snippet shows only the handshake. Implement events, frames, and acknowledgements according to the shared protocol.

Parameter

Type

Description

workspace_id

string

Workspace owning your task.

task_id

string

Original run task ID.

Origin

HTTP header

Sent automatically by the browser; missing or disallowed values are rejected.

Sec-WebSocket-Protocol

string list

Supply both moi-browser.v1 and one proof beginning with moi-browser-token-v1.

Streaming response

HTTP/1.1 101 Switching Protocols
Sec-WebSocket-Protocol: moi-browser.v1

文本消息:{"type":"frame","seq":1,"metadata":{"deviceWidth":1280,"deviceHeight":720}}
下一条消息:原始图像二进制字节

Field or response item

Type

Description

type

string

Known events include frame, url, status, and released.

seq

integer

Server frame sequence number for ack.

metadata

JSON object

Frame metadata. The example contains dimensions without enumerating every provider field.

Image message

binary

Immediately follows the frame text event; not Base64 inside JSON.

Connection recheck

Protocol behavior

The current implementation periodically rebuilds access context and rechecks it. Failures may close with 1008.

Error responses

HTTP / code

Condition

400 / 2

Invalid browser parameters.

401 / 6

Invalid identity proof, or stream proof does not match the path.

403 / 5

Current authorization denied, or stream Origin/subprotocol requirements unmet.

404 / 3

Task inaccessible, owned by another user, or missing required context.

409 / 15

Existing browser is not running; details.reason=BROWSER_NOT_RUNNING.

410 / 3

Original environment ended or expired; details.reason=BROWSER_SESSION_ENDED.

503 / 15

Browser runtime dependencies unavailable, or task state unusable.

500 / 1

Other internal failure.

After 101 upgrade, ordinary HTTP JSON errors no longer apply. Periodic recheck failures may close the connection. See environments and errors for recovery.

Product authentication may also use string code/msg. The numeric errors above do not enumerate every authentication envelope.

Last updated on