Browser automation powered by the agent-browser CLI. Each agent gets its own isolated browser session. Enable by including "browser_*" in the agent’s allowedTools array.
Requires agent-browser CLI installed (npm install -g agent-browser && agent-browser install).
Persistent Browser Profiles
Browser profiles let agents reuse login sessions, cookies, and localStorage across tasks. This is essential for agents that need to interact with authenticated websites.
Setup Flow
# 1. Open a visible browser and log in manually
polpo browser login marco https://twitter.com/login
# 2. A browser window opens — log in to any services you need
# 3. Close the browser when done — your session is saved
# The profile is stored in .polpo/browser-profiles/marco/
Configuration
Set browserProfile on the agent to use a persistent profile:
{
"name": "marco",
"allowedTools": ["read", "write", "edit", "bash", "glob", "grep", "ls", "browser_*"],
"browserProfile": "marco"
}
Managing Profiles
polpo browser list # List all profiles with last-used timestamps
polpo browser clear marco # Delete a profile (removes all saved sessions)
If a login session expires, re-run polpo browser login <agent> <url> to log in again. The profile is overwritten with the fresh session.
browser_navigate — Open URL
Navigate to a URL. Launches the browser if not running.
Parameters
| Parameter | Type | Required | Description |
|---|
url | string | yes | URL to navigate to |
Returns
Browser result with page status.
Notes
- Default timeout: 30s
- Launches browser automatically on first call
browser_snapshot — Accessibility Snapshot
Capture an accessibility snapshot of the current page. Returns a structured representation of the DOM useful for understanding page content without a screenshot.
Parameters
| Parameter | Type | Required | Description |
|---|
interactive_only | boolean | no | Only include interactive elements (buttons, inputs, links) |
compact | boolean | no | Return a compact representation with less detail |
max_depth | number | no | Maximum depth of the DOM tree to capture |
selector | string | no | CSS selector to scope the snapshot to a subtree |
Returns
Structured accessibility tree of the page or selected subtree.
Notes
- Timeout: 15s
- Useful for understanding page structure without taking a screenshot
- Compact mode reduces token usage significantly
browser_click — Click Element
Click an element on the page.
Parameters
| Parameter | Type | Required | Description |
|---|
selector | string | yes | CSS selector of the element to click |
Returns
Browser result confirming the click action.
Notes
- Waits for the element to be visible and actionable before clicking
- Default timeout: 30s
Fill an input field with text. Clears existing content before typing.
Parameters
| Parameter | Type | Required | Description |
|---|
selector | string | yes | CSS selector of the input element |
text | string | yes | Text to fill into the input |
Returns
Browser result confirming the fill action.
Notes
- Clears the field before typing the new value
- Use
browser_type instead if you want to append text without clearing
browser_type — Type Text
Type text into an element. Does NOT clear existing content first.
Parameters
| Parameter | Type | Required | Description |
|---|
selector | string | yes | CSS selector of the element to type into |
text | string | yes | Text to type into the element |
Returns
Browser result confirming the type action.
Notes
- Does NOT clear the field before typing — appends to existing content
- Use
browser_fill if you want to replace existing content
browser_press — Press Key
Press a keyboard key or key combination.
Parameters
| Parameter | Type | Required | Description |
|---|
key | string | yes | Key to press (e.g. Enter, Tab, Control+a, Meta+c) |
Returns
Browser result confirming the key press.
Notes
- Supports modifier combinations like
Control+a, Shift+Enter, Meta+c
- Key names follow the Playwright keyboard API naming convention
browser_screenshot — Take Screenshot
Capture a screenshot of the current page.
Parameters
| Parameter | Type | Required | Description |
|---|
path | string | no | File path to save the screenshot to |
full_page | boolean | no | Capture the full scrollable page instead of just the viewport |
Returns
Screenshot image data, or confirmation if saved to a file path.
Notes
- Returns base64-encoded image data when no path is specified
- Default timeout: 30s
browser_get — Get Page Content
Retrieve content from the page — text, HTML, input values, title, or URL.
Parameters
| Parameter | Type | Required | Description |
|---|
what | enum: text | html | value | title | url | yes | Type of content to retrieve |
selector | string | conditional | CSS selector of the target element. Required when what is text, html, or value |
Returns
The requested content as a string.
Notes
selector is required for text, html, and value — ignored for title and url- Output is truncated if it exceeds MAX_OUTPUT_BYTES (50,000 bytes)
browser_select — Select Option
Select an option from a <select> dropdown element.
Parameters
| Parameter | Type | Required | Description |
|---|
selector | string | yes | CSS selector of the <select> element |
value | string | yes | Value of the option to select |
Returns
Browser result confirming the selection.
Notes
- Matches the
value attribute of the <option> element
- Default timeout: 30s
browser_hover — Hover Element
Hover over an element on the page.
Parameters
| Parameter | Type | Required | Description |
|---|
selector | string | yes | CSS selector of the element to hover over |
Returns
Browser result confirming the hover action.
Notes
- Useful for triggering tooltips, dropdown menus, or hover states
- Default timeout: 30s
browser_scroll — Scroll Page
Scroll the page in a given direction.
Parameters
| Parameter | Type | Required | Description |
|---|
direction | enum: up | down | left | right | yes | Direction to scroll |
pixels | number | no | Number of pixels to scroll. Uses a sensible default if omitted |
Returns
Browser result confirming the scroll action.
Notes
- Default scroll amount is used when
pixels is not specified
- Scrolls the page viewport, not a specific element
browser_wait — Wait for Condition
Wait for a selector, text, URL, or page load state.
Parameters
| Parameter | Type | Required | Description |
|---|
selector | string | no | CSS selector to wait for |
text | string | no | Text content to wait for on the page |
url | string | no | URL (or URL pattern) to wait for |
timeout_ms | number | no | Maximum time to wait in milliseconds |
load_state | enum: load | domcontentloaded | networkidle | no | Page load state to wait for |
Returns
Browser result confirming the condition was met.
Notes
- Timeout: 60s (higher than the default 30s)
- At least one condition parameter should be provided
- Useful for waiting on navigation, AJAX requests, or dynamic content
browser_eval — Evaluate JavaScript
Execute JavaScript code in the browser page context.
Parameters
| Parameter | Type | Required | Description |
|---|
javascript | string | yes | JavaScript code to evaluate in the page context |
Returns
The return value of the evaluated expression, serialized as a string.
Notes
- Code is base64-encoded for transport to avoid escaping issues
- Has access to the full page DOM and browser APIs
- Output is truncated if it exceeds MAX_OUTPUT_BYTES (50,000 bytes)
browser_close — Close Browser
Close the browser session and release resources.
Parameters
No parameters.
Returns
Confirmation that the browser session was closed.
Notes
- Terminates the browser process entirely
- A new browser will be launched automatically on the next browser tool call
browser_back — Go Back
Navigate back in browser history.
Parameters
No parameters.
Returns
Browser result with the new page status after navigating back.
Notes
- Equivalent to clicking the browser back button
- No-op if there is no previous history entry
browser_forward — Go Forward
Navigate forward in browser history.
Parameters
No parameters.
Returns
Browser result with the new page status after navigating forward.
Notes
- Equivalent to clicking the browser forward button
- No-op if there is no forward history entry
browser_reload — Reload Page
Reload the current page.
Parameters
No parameters.
Returns
Browser result with the page status after reload.
Notes
- Performs a full page reload
- Default timeout: 30s
browser_tabs — Manage Tabs
List, open, switch, or close browser tabs.
Parameters
| Parameter | Type | Required | Description |
|---|
action | enum: list | new | switch | close | yes | Tab action to perform |
index | number | no | Tab index for switch and close actions |
url | string | no | URL to open when action is new |
Returns
For list: array of open tabs with index, URL, and title. For other actions: confirmation of the tab operation.
Notes
index is required for switch and close, ignored otherwiseurl is only used with the new action; opens a blank tab if omitted- Tab indices are zero-based
