AgentSurf
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
AgentSurf controls the user's local Chrome. Start with browser_list_tabs. Before element actions, call browser_get_interactives and use its returned opaque element_id; never invent selectors or element IDs. An element_id only works in the frame that produced it: when the snapshot came from a frame_id, pass that same frame_id on the later element action, otherwise the runtime looks in the top document and reports a stale element. browser_list_tabs hides tabs held by another conversation and reports the count instead; a tab that is not yours is refused with tab_in_use. Ask the user before consequential actions such as submitting, purchasing, deleting, uploading, or sending messages. This conversation already owns a browser session: tabs you open are claimed and grouped automatically, and another conversation is refused them. Use browser_claim_tab to take over a tab the user already had open; that claims and groups it too. Pass session_name on any call once you know what the task is: it names this conversation's Chrome tab group, so the tab bar reads as the task instead of a generated id. It sticks for the conversation, and without it the group falls back to the first page you touched. When the browser task is finished, call browser_reset_sessions so the tab group does not linger in the user's tab bar: it ungroups, and closes the tabs you opened yourself while leaving the user's own tabs open. Report your findings after that, and do not make cleanup the user's job.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| browser_claim_tabA | Take over a tab this session does not own yet, for example a page the user already had open. The tab joins the session group unless you pass group: false, and other sessions are refused it from then on. |
| browser_reset_sessionsA | Finish a browser task: release this conversation's session and ungroup its tabs so the group does not linger in the user's tab bar. It also closes the tabs this conversation opened itself, but never a tab the user already had open, so pass close_opened_tabs: false to keep them. force: true instead releases every session, including other conversations', and only ungroups. |
| browser_close_tabC | Close a Chrome tab. |
| browser_backB | Go back one entry in the tab history. |
| browser_forwardB | Go forward one entry in the tab history. |
| browser_reloadB | Reload the tab, re-running its scripts. |
| browser_list_downloadsA | List recent Chrome downloads. Chrome does not record which tab started a download, so tab_id is null unless a previous browser_wait_for_download associated it. |
| browser_wait_for_downloadB | Wait for a download to complete or fail, optionally only one started from a given tab. |
| browser_set_filesB | Set files on a file input element using absolute local paths. |
| browser_list_tabsA | List Chrome tabs without changing the active tab. Start here to find a tab_id. Only this conversation tabs and unclaimed tabs are returned, with other_session_tabs counting what was hidden; pass include_all to see every tab. |
| browser_get_framesA | List the frames inside a tab: iframes and blank-src app frames included. Frame 0 is the top document. Pass a returned frame_id to page reads and element actions to work inside that frame. |
| browser_get_pageC | Read page metadata and viewport state. |
| browser_get_interactivesA | List interactive page elements and their opaque element_ids. Call this before any element action. Pass frame_id to inspect an iframe; the top document is frame 0, and an element_id only works in the frame that returned it. A heavy page can hold hundreds of elements, so the list is capped at 150 and reports total plus truncated; narrow it with limit, visible_only, tag, role or name_contains instead of asking for everything. |
| browser_get_page_contentA | Extract readable page text, and optionally HTML, image, and iframe metadata. Covers the top document unless frame_id targets a frame; app shells keep their real content inside an iframe, so check browser_get_frames when the text looks like navigation only. |
| browser_clickB | Click an element returned by browser_get_interactives. |
| browser_double_clickB | Double-click an element returned by browser_get_interactives. |
| browser_typeC | Type into an editable element returned by browser_get_interactives. |
| browser_pressC | Press a key on an element returned by browser_get_interactives. Supports optional modifier keys. |
| browser_set_checkedC | Set a checkbox or radio button to a specific checked state. |
| browser_select_optionC | Choose options in a select element by value. |
| browser_dragB | Drag one element from browser_get_interactives onto another. |
| browser_wait_for_elementA | Wait for an element from browser_get_interactives to become attached, detached, visible, or hidden. Get a fresh element_id if the page revision changed while waiting. |
| browser_scrollB | Scroll the document by a pixel delta, reporting whether it reached the top or bottom. |
| browser_screenshotA | Capture a screenshot of a Chrome tab as an image. Works on a background tab. Prefer this over describing a page in text when layout or visual state matters. |
| browser_observeB | Capture page state, interactive elements, accessibility data, and a screenshot in one call. |
| browser_switch_tabA | Bring a tab to the front of its window. Screenshots work without this, but the user will see the tab change. |
| browser_openB | Open a URL in Chrome, or navigate an existing tab when tab_id is given. |
| browser_select_textC | Select text or place the cursor before or after text in an editable element. |
| browser_handle_dialogA | Accept or dismiss a JavaScript alert, confirm, or prompt. Supply prompt_text when accepting a prompt. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 29 tools
Most tools target clearly distinct browser actions or resources, such as click vs. type vs. drag vs. select_option. The main overlap is browser_observe, which combines page state, interactives, accessibility, and screenshot, potentially competing with browser_get_page, browser_get_interactives, and browser_screenshot, but descriptions clarify when to use each.
All tools use a consistent browser_ prefix and snake_case, making the set predictable. Most names are verb_noun or verb-only, which is readable, though the mix of patterns is a minor deviation from a strict verb_noun convention.
At 29 tools, the surface is heavy for a single server, even for browser automation. Several inspection tools could be consolidated, and the count exceeds the 25-tool threshold where each tool must strongly justify its place.
The set covers navigation, tabs, frames, element interaction, dialogs, downloads, file inputs, screenshots, and waiting, which is a broad browser-automation lifecycle. Minor gaps remain, such as JavaScript evaluation, hover, and cookie/storage management, but agents can work around most of these.