> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Use

> Let an assistant use approved websites during a conversation.

Browser Use is available on enabled Famulor workspace plans, including a whitelabel reseller's own workspace. It is not yet available in reseller customer workspaces. Workspace processing must be set to **Global**.

## Watch the setup and test

The videos show the English interface. Use the subtitle menu for step-by-step instructions. The bookshop is a public demonstration site; its prices and stock are example data.



\> \[tab] Add and assign the tool
\>
\> \\\<video controls playsInline preload="none" poster="/videos/tutorials/browser-use/setup.png" aria-label="Add and assign the tool">\<source src="https://docs.famulor.io/videos/tutorials/browser-use/setup.mp4" type="video/mp4" />
\>
\>       \\\[Download the video]\(/videos/tutorials/browser-use/setup.mp4)\</video>



\> \[tab] Use the tool in Test Chat
\>
\> \\\<video controls playsInline preload="none" poster="/videos/tutorials/browser-use/test.png" aria-label="Use the tool in Test Chat">\<source src="https://docs.famulor.io/videos/tutorials/browser-use/test.mp4" type="video/mp4" />
\>
\>       \\\[Download the video]\(/videos/tutorials/browser-use/test.mp4)\</video>



## Add Browser Use to an assistant

1. Open **Agent Tools → Agent Connectors** and select **Add** on the **Browser Use** card. Alternatively, create a **Built-in** tool and choose **Browser Use**.
2. Enter an HTTPS **Start URL** and the exact **Allowed websites**, including required redirects and page resources.
3. Use **Description (when to use)** to tell the assistant when to choose this tool.
4. Add **Browser instructions** for the website workflow, expected result and stopping conditions. These instructions are sent directly to every browser task.
5. Add **Required information** with a unique label and optional question guidance for each answer the assistant must collect. The assistant asks for missing answers before starting the browser or reserving browser credits. Add only information needed for every task.
6. Optionally enter a **Wait message**. The caller hears it while the browser works, unless the assistant already said something before the task. Leave it empty for a default sentence in the conversation language. The browser keeps working in the background, the caller can keep talking, and the assistant tells the caller the result as soon as it is ready. In a conversational flow, let the same node that runs the browser tool report its result: if the flow moves to another node while the browser works, the task still finishes, but its result does not reach the next node.
7. If the website needs a sign-in, choose a **Website login** (see below). Otherwise leave **No login**.
8. Save the tool and assign it to the assistant. You do not need to duplicate its browser instructions in the assistant prompt.
9. Start a Test Call or Test Chat. The browser drawer opens automatically when the assistant starts a browser task. Use **View browser** to close or reopen it. Public demos provide the same live view.

For an appointment lookup, use the doctor’s profile as the starting page. Browser instructions can say “Read available dates and times; stop before selecting or booking an appointment.” Required information could be “Patient category”, with guidance “Ask whether this is a new or existing patient.” Actual answers come from the conversation, not from fixed defaults. The description explains when to use the tool; browser instructions explain how to carry out the task.

Phone, widget and messaging conversations keep their existing interface. The assistant can use its assigned browser tool in the background. Viewing is read-only.

### Website login

Some websites show their data only after you sign in. With a **Website login**, the cloud browser signs in by itself before the task starts, so the assistant can read pages behind the sign-in. The assistant never sees the username, password or authenticator key and never asks callers for them. Sign-in screens are not recorded, do not appear in the live view and are not part of the saved video.

A website login belongs to a reusable Browser Use tool, the one you create under **Agent Tools** and assign to assistants. A Browser Use entry placed directly in an assistant's own `builtin_tools` (API) cannot hold a login.

Under **Website login** in the tool settings, choose one method:

* **Username and password**: enter the **Username or email** and the **Password**. **Login page (optional)** is the HTTPS page that shows the sign-in form; its host must be listed under **Allowed websites**, and without an entry the Start URL is used. If the website also asks for a code from an authenticator app, enter the **Authenticator key (optional)**: the Base32 setup key the website shows when you set up two-step verification, often next to the QR code. Famulor generates the current six-digit code itself. The saved login is entered only on the website of the login page (or of the Start URL when no login page is set), never on another allowed website. If the sign-in form is on a separate address, for example a dedicated sign-in domain, enter that address as the login page.
* **Salesforce connection**: select a Salesforce connection from **Automations → Connections** (an API connection with your Salesforce instance URL and access token). Famulor exchanges the connection's token for a one-time Salesforce sign-in link, so no password is stored in the tool. The token needs the web or full scope and must not belong to an API-only user. Add both your My Domain host (for example `acme.my.salesforce.com`) and your Lightning host (for example `acme.lightning.force.com`) to **Allowed websites**. The connection's access token expires. While it is expired, an existing website session keeps working until it ends; after that, reconnect the connection under **Automations → Connections**. Salesforce is the only app that works this way today; other OAuth apps cannot turn a token into a website session, so use **Username and password** for them.

After a successful sign-in, Famulor saves the website session cookies encrypted after each completed task and keeps them for up to 7 days after their last successful use. Later tasks therefore usually start already signed in and do not type the password again. If the session ends in the middle of a task, the browser signs in again as soon as the website sends it back to its sign-in page (the saved login page, the Start URL or a sign-in address such as `/login`). Salesforce sessions and sign-in pages that ask for the email on a separate page are not renewed in the middle of a task; they recover at the next task. Changing the login or its secrets starts a fresh session.

All conversations that use the tool share this one website session. Use a dedicated website account with only the rights the assistant needs, and do not use the tool for data that must stay separate between different callers.

After a rejected sign-in, a required code or a CAPTCHA, the tool pauses sign-in attempts for up to an hour, or until you change the saved login, so the website account is not locked. To continue sooner, correct the login (for example the password) and save it.

The saved login is only used on sign-in forms, recognised by a button that says log in, sign in, next or continue. Sign-up and “add user” forms are never filled with it, and neither are password prompts for something else, such as deleting an account, a checkout, changing an email address or a card form. A sign-in step that the website does not answer in time is not counted as a rejection; only a second one in a row pauses sign-in attempts.

Not supported: CAPTCHAs, codes sent by SMS or email, and sign-in forms inside iframes from other domains. Websites that require one of these cannot be signed in automatically.

Passwords and authenticator keys are stored encrypted and are never shown again: after saving, the tool settings, the API and MCP only show `•••`. Leave a saved value untouched to keep it, or enter a new one to replace it. Test the login in a Test Chat before you use the tool in live conversations.

#### Set the login with the API, MCP, CLI or SDK

The login is part of the tool configuration. Create a **Built-in** tool whose configuration has the type `browser_use`:

```json theme={null}
{
  "name": "check_portal_orders",
  "description": "Use when the customer asks for the status of an order in the supplier portal.",
  "type": "builtin",
  "config": {
    "type": "browser_use",
    "start_url": "https://portal.example.com/orders",
    "allowed_hosts": ["portal.example.com"],
    "browser_instructions": "Open the order list and read the status of the requested order. Do not change anything.",
    "wait_message": "One moment, I'm checking your order in the supplier portal.",
    "login": {
      "method": "password",
      "username": "orders@example.com",
      "password": "your-website-password",
      "totp_secret": "JBSWY3DPEHPK3PXP",
      "login_url": "https://portal.example.com/login"
    }
  }
}
```

For a Salesforce connection, use this `login` instead and list both Salesforce hosts in `allowed_hosts`:

```json theme={null}
"login": { "method": "oauth", "connection_id": "3f2b1c9e-6a7d-4e0f-9b1a-2c8d5e4f7a10" }
```

| Surface | Create | Update |
| - | - | - |
| API | `POST /api/v1/tools` | `PATCH /api/v1/tools/{id}` with `expected_revision` |
| MCP | `create_tool` | `update_tool` |
| CLI | `famulor create-tool --name check_portal_orders --type builtin --config @browser-tool.json` | `famulor update-tool <id> --config @browser-tool.json --expected-revision <revision>` |
| SDK | `client.api.createTool({ body })` | `client.api.updateTool({ path: { id }, body })` |

Website logins are only accepted on reusable tools, as above. An inline `browser_use` item in an assistant's `builtin_tools` with a `login` is rejected with `400`: create the tool, then assign it to the assistant with `PUT /api/v1/assistants/{id}/tools`.

For the CLI, `browser-tool.json` contains only the `config` object. Reading the tool returns `"password": "•••"` and `"totp_secret": "•••"`. An update replaces the whole configuration, so send `login` back as you read it: `•••` keeps the stored value, `"totp_secret": null` removes the authenticator key, and `"login": null` (or leaving `login` out) removes the login.

### Recorded flow

A recorded flow is an addition to your **Browser instructions**: the assistant repeats your recorded clicks first, and Browser Use only steps in where the website looks different. Use it when the website path stays the same, for example to look up a repair status: type the order number, select **Search**, read the status. Recorded steps need no AI, so the result comes faster.

Recorded flows are in Beta: turn on **Beta Features** under **Settings → Workspace** to see them.

1. In the Browser Use tool, select **Record flow** under **Recorded flow**. The browser opens your start page, signed in with the saved **Website login** if the tool has one. Save the tool first when you add or change the login. Record on a computer: the website and the steps need the space.
2. Click and type in the live page as you normally would. Each click appears on the right as a step, written as a sentence such as “Click “Search””. Or select **Let the AI click through**: Browser Use does the task once with your instructions, and each of its clicks becomes a step.
3. When you click a text field or a list, choose what goes in there: **From the conversation** fills in information the assistant collects from the caller (pick one of the **Required information** or add a **New information**, and enter an example for this recording), **Same text every time** always types the same text.
4. To get a value back, switch **Next click** to **Read value** and click the value, such as the status. Give it a name and keep **Must not be empty** on: a run that finds no value ends as not done.
5. Where the right entry depends on the conversation, switch **Next click** to **AI chooses**, click an entry of the list or table and describe which entry the AI should pick, for example “the appointment the caller wants”. The AI sees only the visible texts of the entries and the required information. If it is unsure, the run stops, the assistant asks the caller which entry they mean and then continues at that step.
6. Select **Done**, check the example values and select **Run test**. Then select **Apply** and save the tool. Example values stay in your browser only.

**Required information** applies with and without a flow: the assistant asks for each one before the run, with your question guidance, and the flow uses it wherever you chose **From the conversation**. Each value you read comes back to the assistant under its name.

If the website changed, **If an element is missing** decides what happens. **AI continues** (default) first lets the AI look for the missing element. If it cannot find it, Browser Use finishes the task on the same page with your **Browser instructions**, without repeating the steps the flow already did. **AI finds it** only looks for the element, and **Stop** ends the run. The test result names these steps. Select **Use what the AI found** to adopt the new element, so the next run is fast again.

Clicks that close a cookie banner are marked **May be missing**: if the banner is not shown, the step is skipped after at most two seconds. Select a step to turn **Step may be missing** on or off. When you click into an embedded part of the page, such as a booking widget, it opens as the page by itself and you keep recording inside it; a field you clicked asks right away what goes in. Its website must be in **Allowed websites**.

Elements are found again by their name, label, role and the form or section around them, not by their position on the screen. Each step waits up to five seconds for its element and is never repeated once it may have reached the website. Recording and test runs use browser time like a task, and **Let the AI click through** also uses decision processing. To change the flow later, select **Edit and test** or **Record again**; select a step to change it. Turn off **Use recorded flow** to work with the browser instructions only; the flow is kept.

### Videos and credits

History shows **Browser recording** when a saved video is available. Open the icon to play the WebM video in a modal. Multiple tasks have separate recordings. Videos are private, expire within seven days or earlier under the workspace retention policy, and are removed when their stored conversation is deleted. Zero-retention workspaces produce no saved video. A capture limit can produce a partial video, marked in the player.

Under **Settings → Data Retention**, **Calls** governs phone calls, Test Call, Test Chat and web-widget chat. Messaging uses its own category, such as **WhatsApp** for text conversations. Browser videos follow the matching category, capped at seven days. Expired videos stop being accessible; deleting the stored conversation or workspace queues physical video deletion, with automatic retries if storage is temporarily unavailable.

Browser Use consumes separate workspace credits for browser session time, including its brief idle period, and decision processing. A temporary maximum budget is deducted when a task starts; unused credits are returned after the session closes and reconciliation finishes. Closing the viewer does not stop the task. Ask the assistant to stop the browser task to cancel it.

### Supported tasks

The tool clicks visible elements, fills ordinary text fields with known values, scrolls and reads page content. Tasks have bounded steps and duration. It does not bypass CAPTCHAs or website restrictions, and the assistant never types passwords itself: use a **Website login** for sign-in. File uploads, complex dropdown controls and popup workflows are not supported. If a page changes or information is missing, the assistant must check the result before retrying. A task reporting completion does not replace a visible confirmation on the website.

## Example workflows

Use these as configuration ideas and test the exact website flow with your assistant. They are not guarantees that every site's controls are supported. Dynamic calendars, sign-in steps that a Website login does not cover, or complex selectors can prevent completion. A direct profile or prepared results page often needs fewer steps than a homepage search.

| Use case | Starting page | Required information | Browser instructions and result |
| - | - | - | - |
| Compare flight prices | [Google Flights](https://www.google.com/travel/flights) or a prepared flight-results URL | Departure airport, destination, outbound date, one-way or return, passengers; ask for a return date when needed | Read visible fares, currency, flight times and stops. Mention baggage or fare conditions only if shown. Stop before booking. |
| Compare hotels | [Google Hotels](https://www.google.com/travel/hotels) or a hotel's public availability page | Destination, check-in, check-out, guests and rooms | Compare visible prices and say whether each is per night or for the stay. Report taxes and cancellation conditions only when visible. Do not reserve a room. |
| Check appointments | A practice or service provider's direct profile | New or existing customer and appointment type | Open availability, apply the supplied preferences and report visible dates and times. Stop before selecting or booking a slot. |
| Check product availability | A store's product page | Product or variant, size/color, location if relevant | Read the displayed price and stock status for the requested variant. Do not add to cart or purchase. |
| Track a shipment | A carrier's public tracking page | Tracking number | Enter the supplied number and summarize the visible status and estimated delivery date. Stop if account login or extra personal information is required. |

For a flight tool, put `https://www.google.com/travel/flights` in **Start URL** and `www.google.com` in **Allowed websites**. Add other exact hosts only when the chosen flow actually needs their redirects or resources. A URL belongs in Start URL; Allowed websites contains hostnames, without paths or wildcards.

Example **Description (when to use)**: “Use when the customer asks to compare flight prices.” Example **Browser instructions**: “Use the route, dates and passenger details supplied by the customer. Return up to three visible options with price, currency, departure time and stops. Do not invent missing prices or conditions. Stop before booking, payment or login. If the search controls are unsupported, report that the comparison could not be completed.” Mark only universally needed answers as **Required information**; keep a conditional return date in the question guidance. Prices and availability can change after the lookup.

## API, MCP, CLI & SDK

Create and assign the tool with `POST /api/v1/tools` and `PUT /api/v1/assistants/{id}/tools`, or MCP `create_tool` and `set_assistant_tools`. CLI: `famulor create-tool` and `famulor set-assistant-tools`. SDK: `client.api.createTool(...)` and `client.api.setAssistantTools(...)`. A saved website login is part of the tool configuration; the examples are under Website login above. A recorded flow is part of it too: `mode` is `instructions` or `flow`, and `flow` holds the recorded steps. With `flow`, the recorded steps run first, and `flow.fallback` (`agent` by default, `ai_step` or `stop`) sets what happens when an element is missing: with `agent`, the result carries `handed_over` when Browser Use finished the task. Record a flow in the tool editor; with the API you can read it, rename steps, change texts, instructions and expectations, or copy it to another tool. An update that leaves out `mode` and `flow` keeps them; `"flow": null` removes the flow. `required_inputs` apply to both modes: in flow mode each one becomes a parameter of the tool, and the read-only `flow.inputs` lists them together with any `{Placeholder}` in the steps.

| API | MCP | CLI | SDK |
| - | - | - | - |
| `GET /api/v1/calls/{id}/browser-session` | `get_call_browser_session` | `famulor get-call-browser-session <id>` | `client.calls.browserSession(id)` |
| `GET /api/v1/calls/{id}/browser-recordings` | `list_history_browser_recordings` | `famulor list-call-browser-recordings <id>` | `client.calls.browserRecordings(id)` |
| `GET /api/v1/calls/{id}/browser-recordings/{recordingId}` | `get_history_browser_recording` | `famulor get-call-browser-recording <id> <recordingId> --output-file browser.webm` | `client.calls.browserRecording(id, recordingId)` |
| `GET /api/v1/history/messaging/{id}/browser-recordings` | `list_history_browser_recordings` (`kind: messaging`) | `famulor list-messaging-browser-recordings <id>` | `client.api.listMessagingBrowserRecordings({path:{id}})` |
| `GET /api/v1/history/messaging/{id}/browser-recordings/{recordingId}` | `get_history_browser_recording` (`kind: messaging`) | `famulor get-messaging-browser-recording <id> <recordingId> --output-file browser.webm` | `client.api.getMessagingBrowserRecording({path:{id,recordingId}})` |

Live-view tickets expire after 60 seconds. Send `viewer_origin` to request a read-only WebSocket URL for that exact page origin. Downloads require the same workspace credential and `calls:read` scope. MCP returns an authenticated download path. Keep API keys on your server.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.