Extensions in agent runs

An agent run can load up to 3 Chrome extensions from your project. Each browser of the run loads them before the agent uses it.

Zero Data Retention projects cannot use extensions.

First upload the extensions and keep their IDs. The browser Extensions guide shows how.

Start a run with extensions

Pass the extension IDs in browserSettings:

from browser_use_sdk.v4 import BrowserUse

client = BrowserUse()
run = client.runs.create(
    "List the top 3 headlines on bbc.com",
    browser_settings={"extensionIds": ["<extension-id>"]},
)

curl https://api.browser-use.com/api/v4/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"List the top 3 headlines on bbc.com",
       "browserSettings":{"extensionIds":["<extension-id>"]}}'

In Python, pass browser_settings as a dict with the REST field name extensionIds. The TypeScript SDK types do not include extensionIds yet. Use the REST API from TypeScript. Browser Use does not tell the agent which extensions the browser has. If the agent must open an extension page, put its chrome-extension:// URL in the task.

Follow-up runs

The first run of a session sets the extensions of the session. Every browser that the session starts loads the same extensions. Leave out extensionIds in follow-up runs. They keep the extensions of the session. A follow-up run that passes different extensions gets a 400 response. If you delete an extension, a browser that is already running keeps it until the browser stops. Follow-up runs can reuse that browser. Browsers that the session starts later do not load the extension. A follow-up run that passes extensionIds must leave out the deleted ID. The API accepts this shorter list. A list with the deleted ID gets a 404 response.

Get Started

Pillars

More

Extensions in agent runs

Start a run with extensions

Follow-up runs

​Start a run with extensions

​Follow-up runs

Start a run with extensions

Follow-up runs