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

# Browser Tools

> Open interactive browser sessions to navigate live web apps, inspect page snapshots, click elements, type into forms, and capture screenshots.

## **Overview**

### **Tool Name**

```json theme={null}
browser_tools
```

### **Purpose**

The **browser\_tools** group lets Genesis interact with live web UIs. Use it when a workflow needs to open a page, inspect the current layout, click controls, type into fields, capture screenshots, or step through a multi-action browser flow on an external site or an internal Genesis page.

<Note>
  Use **browser\_tools** for interactive UI work. For simple page reads, API calls, or file downloads, use [Web Access Tools](/docs/Genbot-Toolkit/Web-Access-Tools) instead.
</Note>

If Chromium is not included in the Databricks App deployment, `browser_open`
returns an unavailable error. Related web actions and non-browser alternatives
are described in [Web Access Tools](/docs/Genbot-Toolkit/Web-Access-Tools).

On Genesis Desktop, the first `browser_open` or app screenshot/runtime inspection
starts a one-time browser-tools download when needed. This also applies to
`CAPTURE` or `INSPECT_RUNTIME_STATE`, including captures inside `REVIEW` or
`START`. The download is about 140–160 MB and can take up to 150 seconds. If a
response reports that installation is still in progress, relay the status and
repeat the action in about a minute. If installation fails, relay the reason;
the user can retry with **Install** in **Settings → Advanced → Browser tools**.

### **Key Features**

<Steps>
  <Step title="Open live browser sessions" icon="globe">
    Start a persistent browser session against a full external URL such as `https://example.com` or an internal Genesis path such as `/apps/my-app`.
  </Step>

  <Step title="Inspect accessible page snapshots" icon="diagram-project">
    Return a compact text snapshot with headings, landmarks, and interactive elements labeled with `el_*` IDs for follow-up actions.
  </Step>

  <Step title="Click and type into live pages" icon="hand-pointer">
    Interact with buttons, links, inputs, selects, and text areas by current element ID or matching text.
  </Step>

  <Step title="Capture screenshots when needed" icon="camera">
    Add `include_screenshot=True` to capture the current viewport during `browser_snapshot`.
  </Step>

  <Step title="Close sessions explicitly" icon="xmark">
    End the browser session when the task is complete to release resources.
  </Step>
</Steps>

## **Input Parameters for Each Function**

### **`browser_open`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`url`** | String | none | Required. URL to open. Use a full URL for external sites such as `https://example.com` or a relative path for internal Genesis pages such as `/apps/my-app`. |
| **`viewport_width`** | Integer | `1280` | Browser viewport width in pixels. |
| **`viewport_height`** | Integer | `720` | Browser viewport height in pixels. |

### **`browser_snapshot`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`session_id`** | String | none | Required. Session ID returned by `browser_open`. |
| **`include_screenshot`** | Boolean | `False` | Also capture a visual screenshot of the current viewport. |

### **`browser_click`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`session_id`** | String | none | Required. Session ID returned by `browser_open`. |
| **`element`** | String | none | Required. Element to click. Use an element ID from the current snapshot such as `el_4` or visible text content to match. |

### **`browser_type`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`session_id`** | String | none | Required. Session ID returned by `browser_open`. |
| **`element`** | String | none | Required. Element to type into. Use an element ID from the current snapshot such as `el_5` or visible text or placeholder to match. |
| **`text`** | String | none | Required. Text to type into the element. |
| **`press_enter`** | Boolean | `False` | Press Enter after typing. |
| **`clear_first`** | Boolean | `True` | Clear existing text before typing. Set to `False` to append instead. |

### **`browser_close`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`session_id`** | String | none | Required. Session ID returned by `browser_open`. |

<Tip>
  `thread_id` and `bot_id` are supplied implicitly by Genesis. After `browser_open`, reuse the returned `session_id` for `browser_snapshot`, `browser_click`, `browser_type`, and `browser_close`.
</Tip>

## **Workflow/How It Works**

1. Call `browser_open` with an external URL or an internal Genesis path.
2. Review the returned `snapshot` and identify the current `el_*` IDs for interactive elements.
3. Use `browser_click` or `browser_type` to take the next action.
4. Call `browser_snapshot` whenever you want a refreshed page view or a screenshot.
5. Finish with `browser_close` to release the session.

<Note>
  Element IDs are generated from the current page snapshot. After a navigation or UI change, use the latest returned snapshot before taking the next action.
</Note>

## **Examples**

```python theme={null}
# Open an internal Genesis page
result = browser_open(url="/apps/customer-health")
session_id = result["session_id"]
```

```python theme={null}
# Click a button from the current snapshot
browser_click(session_id=session_id, element="el_3")
```

```python theme={null}
# Type into a search box and submit
browser_type(
    session_id=session_id,
    element="Search",
    text="Q1 pipeline health",
    press_enter=True,
)
```

```python theme={null}
# Refresh the snapshot and capture a screenshot
browser_snapshot(session_id=session_id, include_screenshot=True)
```

```python theme={null}
# Close the session when finished
browser_close(session_id=session_id)
```

## **Output**

* `browser_open` returns `success`, `session_id`, `url`, `snapshot`, `element_count`, and usage `tips`. On Genesis Desktop, if the one-time browser-tools download is still running, it instead returns progress without a `session_id`; relay the status and try again shortly.
* `browser_snapshot` returns `success`, `session_id`, `title`, `url`, `snapshot`, and `element_count`. When `include_screenshot=True`, it also returns `screenshot_path` and `screenshot_reminder`.
* `browser_click` and `browser_type` return `success`, `session_id`, `url`, `snapshot`, and `element_count` after the interaction.
* `browser_close` returns `success`, `session_id`, and `status` set to `closed`.

## **Configuration Details**

* Use full URLs for external sites.
* Use relative paths such as `/apps/my-app` or `/api/apps/<app_id>/proxy/` for internal Genesis pages.
* When `browser_open` targets the local Genesis backend on `localhost` or `127.0.0.1` using the active FastAPI port, Genesis automatically attaches the internal service token as the `X-Genesis-Internal-Token` header.
* That header is scoped to the local Genesis origin only and is not sent to external sites or other localhost ports.
* The default viewport is `1280x720`.
* `browser_type` clears existing text by default; set `clear_first=False` to append instead.

## **Limitations or Notes**

1. These tools operate on a live browser session, so page state can change between actions.
2. `browser_click` and `browser_type` work best when you use the current snapshot's `el_*` IDs instead of guessing text matches.
3. `include_screenshot=True` captures the current viewport rather than a stitched full-page image.
4. Always call `browser_close` when you are done to free server resources.