<span id="连接任务浏览器流"></span>

# Connect to a task browser stream

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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.

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

<span id="调用前准备"></span>

## 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.

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```javascript
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.

:::::
:::::{tab-item} Parameters

| 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. |

:::::
::::::
:::::::

<span id="流式响应"></span>

## Streaming response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

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

:::::
:::::{tab-item} Fields

| 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. |

:::::
::::::
:::::::

<span id="错误响应"></span>

## 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](errors-environments.md) for recovery.

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