Agent Browser

Add hosted or local browser control to a workspace so agents can use real browser tools through MCP, with human handoff for logins, MFA, and CAPTCHAs.

Agent Browser

Some work has no API. Internal tools, legacy portals, and dashboards behind a login sometimes require a real browser. Agent Browser adds browser sessions to a workspace so agents can navigate, read, click, type, download files, and ask a human to take over the same live session when a password, MFA challenge, or CAPTCHA appears.

Use hosted agent-browser for most workflows. Use local browser access when a site must see the user's own device, network, password manager, or device-trust state. Add model-backed browser actions only when agents need natural-language instructions instead of explicit browser steps. Use agent-browser-stealth only for hosted workflows where standard browser automation is often challenged. All browser variants expose the same core action names to MCP and action callers.

For most teams, setup is simple: add a browser workspace integration, then create an MCP server for that workspace. The agent receives browser tools the same way it receives Slack, Gmail, Filesystem, State KV, Sandbox, and other workspace integrations.

It is not OAuth, and it is not a CAPTCHA bypass. The human signs in directly inside the browser; the agent never receives the password or MFA secret.

By default, browser profile persistence is scoped to the current end user. Pass your user's external ID as endUserId when agents should keep using that user's saved sign-in state. If a workflow is intentionally shared by the workspace or by a custom namespace, set settings.persistence on the workspace integration.

Use agent-browser for most governed browser work. Add agent-local-browser-control when the browser must run on the user's own device. Add agent-browser-ai or agent-browser-stealth-ai only when the browser needs model-backed natural-language actions.

Primary Path: Workspace Integration + MCP

Add Agent Browser to the workspace

Create a workspace integration with a stable alias such as browser. No connection is required for the deterministic browser tools.

Create an MCP server for the workspace

Use Code Mode when you want compact search, read, and execute meta-tools. Use Tool Mode when the MCP client should see every browser action as an individual tool.

Let the agent use the browser

The first browser action starts a hosted session automatically. Later actions reuse the same live session for that workspace and end user when one is available.

Hand control to a human when needed

When a login, MFA challenge, or CAPTCHA blocks progress, the agent calls request_human. Weavz returns a viewer link so a person can control the same browser and then hand it back with resume.

Hosted Stealth Browser

agent-browser-stealth uses the same deterministic actions, persistence settings, screenshots, and human handoff flow as agent-browser. Choose it when the workflow can run in a hosted browser but needs a tougher browser environment for pages that challenge standard automation.

Stealth is for tougher hosted web workflows, not for bypassing user verification. When a site needs the user's device, network reputation, password manager, security key, or local trust state, use agent-local-browser-control instead.

Add it with an alias such as stealth_browser:

json

{
  "integrationName": "agent-browser-stealth",
  "alias": "stealth_browser",
  "displayName": "Agent Browser (Stealth)",
  "settings": {
    "persistence": {
      "scope": "end_user"
    }
  }
}

Use agent-browser-stealth-ai when the same hosted stealth session also needs the AI driver actions act, extract, and observe. It uses the same persistence and human handoff behavior as agent-browser-stealth, but the model-backed actions require the configured model provider connection.

Local Browser Control

agent-local-browser-control uses the same action names as agent-browser, but the browser runs in the user's Chrome profile through the Weavz Local Browser Extension. This is useful for portals that treat hosted browser environments as suspicious, or for login flows where the user's existing device, network, password manager, security keys, or device trust checks matter.

New local browser workspace integrations use Chrome extension mode by default. Use the managed profile CLI fallback when a user cannot install the extension or when a workflow needs the older dedicated-profile companion behavior.

Add the local browser integration

Add agent-local-browser-control to the workspace with an alias such as local_browser. It supports the same settings.persistence scopes as hosted Agent Browser. Advanced setup includes settings.localBrowser.runtime, which defaults to chrome_extension.

Install and sign in

The user installs the Weavz Local Browser Extension, opens it in Chrome, and signs in to Weavz. The extension lets the user approve or block sites before browser actions can run there.

Start a local session

Call start_session from MCP or the action API. In extension mode the result returns extension readiness fields instead of a command.

Confirm it is connected

Call ensure_connected before navigation or element actions. It briefly waits for the extension and returns connected, waiting_for_connection, disconnected, or revoked.

Let the agent drive it

After ensure_connected returns ready: true, agents use snapshot, navigate, click, type, screenshot, and the rest of the browser actions exactly as they do with hosted Agent Browser.

javascript

const session = await weavz.local_browser.start_session({})
 
return {
  sessionId: session.sessionId,
  runtime: session.runtime,
  nextAction: session.nextAction,
  ready: session.ready,
}

When the workflow is finished, call end_session.

Managed Profile CLI Fallback

Set settings.localBrowser.runtime to managed_profile when you need the existing companion flow. In this mode, start_session returns localRunnerCommand and localProfileId.

Keep the command secret to the user or device that should attach the local browser. It is a session-scoped runner URL, not a long-lived API key.

The returned command uses the public npm package @weavz-io/local-browser-use:

bash

npx -y @weavz-io/local-browser-use connect --url "<localRunnerUrl from start_session>" --profile "<localProfileId>"

If the local browser has not connected yet, ensure_connected returns waiting_for_connection. If it was connected and later closed, it returns disconnected, lastSeenAt, and disconnectReason. Managed-profile sessions also return a fresh localRunnerCommand. Agents should not call navigate, click, type, or other browser actions until ensure_connected returns ready: true.

Add It To A Workspace And Create MCP

bash

curl -X POST https://platform.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "agent-browser",
    "alias": "browser",
    "displayName": "Agent Browser",
    "settings": { "persistence": { "scope": "end_user" } }
  }'
 
curl -X POST https://platform.weavz.io/api/v1/mcp/servers \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Browser Agent Workspace",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "mode": "CODE",
    "authMode": "oauth",
    "endUserAccess": "restricted"
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
const workspaceId = 'YOUR_WORKSPACE_ID'
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'agent-browser',
  alias: 'browser',
  displayName: 'Agent Browser',
  settings: { persistence: { scope: 'end_user' } },
})
 
const { server, mcpEndpoint } = await client.mcpServers.create({
  name: 'Browser Agent Workspace',
  workspaceId,
  mode: 'CODE',
  authMode: 'oauth',
  endUserAccess: 'restricted',
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
workspace_id = "YOUR_WORKSPACE_ID"
 
client.workspaces.add_integration(
    workspace_id,
    integration_name="agent-browser",
    integration_alias="browser",
    display_name="Agent Browser",
    settings={"persistence": {"scope": "end_user"}},
)
 
result = client.mcp_servers.create(
    name="Browser Agent Workspace",
    workspace_id=workspace_id,
    mode="CODE",
    auth_mode="oauth",
    end_user_access="restricted",
)

typescript

await fetch('https://platform.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'agent-browser',
    alias: 'browser',
    displayName: 'Agent Browser',
    settings: { persistence: { scope: 'end_user' } },
  }),
})
 
const res = await fetch('https://platform.weavz.io/api/v1/mcp/servers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Browser Agent Workspace',
    workspaceId: 'YOUR_WORKSPACE_ID',
    mode: 'CODE',
    authMode: 'oauth',
    endUserAccess: 'restricted',
  }),
})
const { server, mcpEndpoint } = await res.json()

python

import httpx
 
headers = {
    "Authorization": "Bearer wvz_your_api_key",
    "Content-Type": "application/json",
}
 
httpx.post(
    "https://platform.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations",
    headers=headers,
    json={
        "integrationName": "agent-browser",
        "alias": "browser",
        "displayName": "Agent Browser",
        "settings": {"persistence": {"scope": "end_user"}},
    },
)
 
res = httpx.post(
    "https://platform.weavz.io/api/v1/mcp/servers",
    headers=headers,
    json={
        "name": "Browser Agent Workspace",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "mode": "CODE",
        "authMode": "oauth",
        "endUserAccess": "restricted",
    },
)
server = res.json()["server"]
mcp_endpoint = res.json()["mcpEndpoint"]

How Sessions Are Handled

Agent Browser uses browser sessions behind the scenes, but normal MCP and action callers do not need to create sessions manually.

Behavior	What happens
First hosted browser action	Starts a hosted browser session automatically when no live session is available
First local browser action	Creates a local browser session; call `start_session`, then connect with the Chrome extension or managed-profile fallback
Later browser actions	Reuse the active session for the same workspace and end user
`sessionId` omitted	Weavz uses the auto-managed session for that caller context
`sessionId` provided	The action targets that explicit session after access checks
`show_live_view`	Mints a watch-only viewer link so a person can see what the agent is doing without taking control
`request_human`	Mints a viewer link and blocks agent control while the human is driving
`request_human` on local browser	Asks the user to use Chrome or the connected local browser window, then call `resume`
`resume`	Returns control to the agent
`end_session`	Ends the live session and snapshots the profile to the configured persistence scope

Pass the end user's externalId as endUserId when you want per-user browser identity. End-user scoped sessions can reuse saved sign-in state across runs. Workspace and external scopes reuse the same live browser session and saved browser profile for the configured workspace integration scope.

Batched Code Mode Workflows

When Agent Browser is exposed through a Code Mode MCP server, agents should batch related browser operations inside one weavz_execute call. A single run can navigate, inspect the page, click or type by snapshot ref, take a screenshot, and return the observations the agent needs. This is faster and more reliable than one execute call per browser action.

javascript

const session = await weavz.browser.start_session({ headless: true })
await weavz.browser.navigate({
  sessionId: session.sessionId,
  url: 'https://app.example.com',
})
 
const snapshot = await weavz.browser.snapshot({ sessionId: session.sessionId })
const status = await weavz.browser.read_text({
  sessionId: session.sessionId,
  target: '#status',
}).catch(() => null)
const screenshot = await weavz.browser.screenshot({
  sessionId: session.sessionId,
  quality: 55,
})
 
return {
  sessionId: session.sessionId,
  snapshot: String(snapshot.snapshot).slice(0, 3000),
  status,
  screenshot: {
    mimeType: screenshot.mimeType,
    width: screenshot.width,
    height: screenshot.height,
  },
}

Use sessionId across separate runs only when the workflow needs incremental state, human handoff, or a later follow-up. For unfamiliar pages, the most robust loop is snapshot, choose an element ref such as e5, then call click, type, read_text, or screenshot with that ref.

Tool Mode also includes run_steps for deterministic browser sequences when you do not want a full Code Mode script. It runs a small list of browser operations after one session attach, and can return a final snapshot or final inline screenshot. Use Code Mode for branching logic and custom parsing; use run_steps for straightforward flows such as navigate, wait, read, and snapshot.

Persistence Scopes

Agent Browser, Agent Browser (Stealth), Agent Browser AI, Agent Browser (Stealth AI), and Agent Local Browser Control use the same settings.persistence object as Filesystem and State KV:

Scope	Use when
`end_user`	Each of your users should keep a separate browser identity. This is the default and requires `endUserId` on calls.
`workspace`	The browser identity is intentionally shared by the workspace.
`external`	You want a custom namespace such as a tenant, project, or account key. Set `settings.persistence.externalId`.

json

{
  "integrationName": "agent-browser",
  "alias": "browser",
  "settings": {
    "persistence": {
      "scope": "workspace"
    }
  }
}

For Local Browser for Agents, settings.localBrowser.runtime controls the local runtime:

json

{
  "integrationName": "agent-local-browser-control",
  "alias": "local_browser",
  "settings": {
    "persistence": { "scope": "end_user" },
    "localBrowser": { "runtime": "chrome_extension" }
  }
}

Deterministic Browser Actions

Use these actions directly through REST or the SDK when you are not going through MCP, or when you want to test the integration before connecting an MCP client.

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "YOUR_WORKSPACE_ID",
    "integrationName": "agent-browser",
    "integrationAlias": "browser",
    "actionName": "navigate",
    "endUserId": "user_123",
    "input": { "url": "https://app.acme.com" }
  }'

typescript

const ctx = {
  workspaceId: 'YOUR_WORKSPACE_ID',
  integrationAlias: 'browser',
  endUserId: 'user_123',
}
 
await client.actions.execute('agent-browser', 'navigate', {
  ...ctx,
  input: { url: 'https://app.acme.com' },
})
 
const snapshot = await client.actions.execute('agent-browser', 'snapshot', {
  ...ctx,
  input: {},
})
 
await client.actions.execute('agent-browser', 'click', {
  ...ctx,
  input: { target: 'e42' },
})

python

ctx = {
    "workspace_id": "YOUR_WORKSPACE_ID",
    "integration_alias": "browser",
    "end_user_id": "user_123",
}
 
client.actions.execute(
    "agent-browser",
    "navigate",
    **ctx,
    input={"url": "https://app.acme.com"},
)
 
snapshot = client.actions.execute(
    "agent-browser",
    "snapshot",
    **ctx,
    input={},
)
 
client.actions.execute(
    "agent-browser",
    "click",
    **ctx,
    input={"target": "e42"},
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workspaceId: 'YOUR_WORKSPACE_ID',
    integrationName: 'agent-browser',
    integrationAlias: 'browser',
    actionName: 'navigate',
    endUserId: 'user_123',
    input: { url: 'https://app.acme.com' },
  }),
})
const result = await res.json()

python

import httpx
 
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "workspaceId": "YOUR_WORKSPACE_ID",
        "integrationName": "agent-browser",
        "integrationAlias": "browser",
        "actionName": "navigate",
        "endUserId": "user_123",
        "input": {"url": "https://app.acme.com"},
    },
)
result = res.json()

The deterministic action set includes snapshot, navigate, navigate_back, click, type, fill_form, select_option, hover, drag, press_key, file_upload, evaluate, read_text, read_html, screenshot, run_steps, wait_for, handle_dialog, tabs, show_live_view, request_human, resume, ensure_connected, start_session, session_status, and end_session.

Screenshots

screenshot returns a browser image envelope:

json

{
  "mimeType": "image/jpeg",
  "width": 1280,
  "height": 720,
  "imageContent": "base64-encoded JPEG"
}

Set saveToFilesystem when you also need a hosted URL:

json

{
  "mimeType": "image/jpeg",
  "width": 1280,
  "height": 720,
  "imageContent": "base64-encoded JPEG",
  "url": "hosted screenshot URL"
}

MCP tool calls also include an MCP image content item, so agents can inspect the screenshot directly without fetching the hosted URL. By default screenshots are JPEG quality 60 at agent-friendly scale and use a fast viewport capture path. Set fullResolution only when the agent or your backend needs the original device-scale image, and set saveToFilesystem only when a human-viewable download URL is useful.

Optional LLM Driver

Natural-language browser actions live in separate integrations: agent-browser-ai for the standard hosted browser, and agent-browser-stealth-ai for the hosted stealth browser. They expose the same browser control actions as their auth-free counterparts, plus model-backed actions. If you do not add an AI browser integration, the auth-free hosted, stealth, and local browser tools still work.

When configuring either AI browser integration, choose the provider and model from dropdowns and store the API key as a secret connection value. The shared picker supports OpenAI, Anthropic, Google AI, and xAI. Only the AI-specific actions require that connection; deterministic browser controls stay auth-free.

agent-browser-ai provides:

act - complete a natural-language browser task by looping over snapshots and browser actions.
extract - extract structured data from the current page.
observe - identify relevant page elements without taking action.

agent-browser-stealth-ai provides the same AI actions on the hosted stealth browser. It is not a CAPTCHA bypass; use local browser control when the user's device, network, password manager, or device trust state is required.

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "agent-browser-ai",
    "actionName": "act",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "endUserId": "user_123",
    "input": { "instruction": "Open the latest invoice and download the PDF" }
  }'

typescript

await client.actions.execute('agent-browser-ai', 'act', {
  workspaceId,
  endUserId: 'user_123',
  input: { instruction: 'Open the latest invoice and download the PDF' },
})

python

client.actions.execute(
    "agent-browser-ai",
    "act",
    workspace_id=workspace_id,
    end_user_id="user_123",
    input={"instruction": "Open the latest invoice and download the PDF"},
)

typescript

await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'agent-browser-ai',
    actionName: 'act',
    workspaceId: 'YOUR_WORKSPACE_ID',
    endUserId: 'user_123',
    input: { instruction: 'Open the latest invoice and download the PDF' },
  }),
})

python

import httpx
 
httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "agent-browser-ai",
        "actionName": "act",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "endUserId": "user_123",
        "input": {"instruction": "Open the latest invoice and download the PDF"},
    },
)

Human Handoff

Use show_live_view when a teammate needs to watch the browser while the agent keeps working. This link stays watch-only, even if a separate human handoff link is currently interactive.

Use request_human when the browser reaches a step the agent should not complete, such as login, MFA, CAPTCHA, payment, or a sensitive admin screen. The viewer becomes interactive, agent control is blocked, and the agent should call resume after the person finishes.

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "agent-browser",
    "actionName": "show_live_view",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "integrationAlias": "browser",
    "endUserId": "user_123",
    "input": {}
  }'
 
curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "agent-browser",
    "actionName": "request_human",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "integrationAlias": "browser",
    "endUserId": "user_123",
    "input": { "reason": "Login or MFA required" }
  }'
 
curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "agent-browser",
    "actionName": "resume",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "integrationAlias": "browser",
    "endUserId": "user_123",
    "input": {}
  }'

typescript

const liveView = await client.actions.execute("agent-browser", "show_live_view", {
  workspaceId,
  integrationAlias: "browser",
  endUserId: "user_123",
  input: {},
})
 
// Share liveView.output.viewerUrl when someone only needs to watch.
 
const handoff = await client.actions.execute("agent-browser", "request_human", {
  workspaceId,
  integrationAlias: "browser",
  endUserId: "user_123",
  input: { reason: "Login or MFA required" },
})
 
// Send handoff.output.viewerUrl to the person who should complete the step.
 
await client.actions.execute("agent-browser", "resume", {
  workspaceId,
  integrationAlias: "browser",
  endUserId: "user_123",
  input: {},
})

python

live_view = client.actions.execute(
    "agent-browser",
    "show_live_view",
    workspace_id=workspace_id,
    integration_alias="browser",
    end_user_id="user_123",
    input={},
)
 
# Share live_view["output"]["viewerUrl"] when someone only needs to watch.
 
handoff = client.actions.execute(
    "agent-browser",
    "request_human",
    workspace_id=workspace_id,
    integration_alias="browser",
    end_user_id="user_123",
    input={"reason": "Login or MFA required"},
)
 
# Send handoff["output"]["viewerUrl"] to the person who should complete the step.
 
client.actions.execute(
    "agent-browser",
    "resume",
    workspace_id=workspace_id,
    integration_alias="browser",
    end_user_id="user_123",
    input={},
)

typescript

const liveViewRes = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'agent-browser',
    actionName: 'show_live_view',
    workspaceId: 'YOUR_WORKSPACE_ID',
    integrationAlias: 'browser',
    endUserId: 'user_123',
    input: {},
  }),
})
const liveView = await liveViewRes.json()
 
const handoffRes = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'agent-browser',
    actionName: 'request_human',
    workspaceId: 'YOUR_WORKSPACE_ID',
    integrationAlias: 'browser',
    endUserId: 'user_123',
    input: { reason: 'Login or MFA required' },
  }),
})
const handoff = await handoffRes.json()
 
await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'agent-browser',
    actionName: 'resume',
    workspaceId: 'YOUR_WORKSPACE_ID',
    integrationAlias: 'browser',
    endUserId: 'user_123',
    input: {},
  }),
})

python

import httpx
 
live_view = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "agent-browser",
        "actionName": "show_live_view",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "integrationAlias": "browser",
        "endUserId": "user_123",
        "input": {},
    },
).json()
 
handoff = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "agent-browser",
        "actionName": "request_human",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "integrationAlias": "browser",
        "endUserId": "user_123",
        "input": {"reason": "Login or MFA required"},
    },
).json()
 
httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "agent-browser",
        "actionName": "resume",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "integrationAlias": "browser",
        "endUserId": "user_123",
        "input": {},
    },
)

In user state, viewer clicks, typing, scrolling, paste, and navigation control the live page. Agent browser actions are blocked until control returns to agent.

Call session_status or ensure_connected before continuing after a handoff or a local-browser disconnect. browserReady means the browser infrastructure exists. canExecuteBrowserActions means the current caller can act now. If canExecuteBrowserActions is false, use nextAction, recommendedNextCommand, and recovery.message to decide whether to call resume, reconnect the local browser, wait briefly, or start a new session.

Restrict Browsing

Pass allowedHosts to start_session or the first browser action in a run when a workflow should stay inside a known set of domains.

json

{
  "allowedHosts": ["app.acme.com", "*.acme-cdn.com"]
}

Omit allowedHosts for unrestricted browsing.

Session Lifecycle

Agent Browser manages the hosted browser session behind the workspace integration. The first browser action starts a session for the workspace and end user, later actions reuse it, and end_session releases it when the workflow is finished.

When an action includes endUserId, it must be an existing end user external ID in that workspace. This scopes browser identity and saved sign-in state to that user. Use show_live_view when someone needs to watch the agent work without interrupting it. Use request_human to mint a fresh interactive viewer link for login, MFA, CAPTCHA, or payment steps, then call resume after the person completes the step.