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 |
|---|---|---|
|
string |
Workspace owning your task. |
|
string |
Original run task ID. |
|
HTTP header |
Sent automatically by the browser; missing or disallowed values are rejected. |
|
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 |
|---|---|---|
|
string |
Known events include frame, url, status, and released. |
|
integer |
Server frame sequence number for ack. |
|
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.