Browser-Use 底层工具方法文档

本文档整理了 browser-use 项目的所有底层工具方法，方便你在自己的 Agent 中集成使用。

1. 浏览器会话管理 (BrowserSession)

文件位置: browser_use/browser/session.py

核心方法

`async start() -> None`

功能: 启动浏览器会话

自动检测是本地浏览器还是云浏览器
建立 CDP (Chrome DevTools Protocol) 连接
初始化所有 watchdog 服务
使用场景: 在使用任何浏览器功能前必须调用

browser_session = BrowserSession(headless=False)
await browser_session.start()

`async stop() -> None`

功能: 优雅停止浏览器会话

保存存储状态 (cookies, localStorage 等)
清理事件总线和缓存
保持浏览器进程运行
使用场景: 临时暂停会话但不关闭浏览器

`async kill() -> None`

功能: 强制终止浏览器会话

保存存储状态
关闭浏览器进程
清理所有资源
使用场景: 完全结束浏览器使用

`async reset() -> None`

功能: 重置会话状态

清除所有 CDP 会话缓存
清除 DOM 缓存和选择器映射
重置焦点目标
使用场景: 需要清理状态但保持连接时

`async get_or_create_cdp_session(target_id: str, focus: bool = True) -> CDPSession`

功能: 获取或创建 CDP 会话

参数:
- target_id: 目标页面/标签的 ID
- focus: 是否将焦点切换到该目标
返回: CDP 会话对象，用于发送 CDP 命令
使用场景: 需要直接使用 CDP 协议操作浏览器时

`async get_current_page_url() -> str`

功能: 获取当前页面 URL

返回当前焦点标签页的 URL
使用场景: 需要知道当前浏览位置

`async get_selector_map() -> dict[int, EnhancedDOMTreeNode]`

功能: 获取页面元素索引映射

返回页面所有可交互元素的索引字典
键是元素索引，值是增强的 DOM 节点对象
使用场景: 需要通过索引访问页面元素时

`async get_element_by_index(index: int) -> EnhancedDOMTreeNode | None`

功能: 通过索引获取页面元素

参数: index - 元素索引号
返回: 增强的 DOM 节点对象或 None
使用场景: 根据 LLM 返回的索引定位元素

2. 页面操作工具 (Tools)

文件位置: browser_use/tools/service.py

这是最核心的工具类，包含了所有高级浏览器操作方法。

2.1 导航类方法

`async search(query: str, engine: str = 'google') -> ActionResult`

功能: 使用搜索引擎搜索

参数:
- query: 搜索关键词
- engine: 搜索引擎 ('google', 'duckduckgo', 'bing')
返回: 操作结果，包含搜索状态
实现位置: browser_use/tools/service.py:126

result = await tools.search(
    query="Python async programming",
    engine="google",
    browser_session=browser_session
)

`async navigate(url: str, new_tab: bool = False) -> ActionResult`

功能: 导航到指定 URL

参数:
- url: 目标 URL
- new_tab: 是否在新标签页打开
返回: 导航结果
实现位置: browser_use/tools/service.py:169

result = await tools.navigate(
    url="https://example.com",
    new_tab=True,
    browser_session=browser_session
)

`async go_back() -> ActionResult`

功能: 返回上一页

相当于浏览器的后退按钮
实现位置: browser_use/tools/service.py:213

`async wait(seconds: int = 3) -> ActionResult`

功能: 等待指定秒数

参数: seconds - 等待时间（最大 30 秒）
使用场景: 等待页面加载或动画完成
实现位置: browser_use/tools/service.py:227

2.2 元素交互方法

`async click(index: int, coordinate_x: int = None, coordinate_y: int = None) -> ActionResult`

功能: 点击页面元素

参数:
- index: 元素索引（优先使用）
- coordinate_x, coordinate_y: 坐标点击（备选）
返回: 点击结果，包含点击坐标元数据
实现位置: browser_use/tools/service.py:299 (索引), browser_use/tools/service.py:258 (坐标)

# 通过索引点击
result = await tools.click(
    index=5,
    browser_session=browser_session
)

# 通过坐标点击（需要启用坐标点击功能）
result = await tools.click(
    coordinate_x=100,
    coordinate_y=200,
    browser_session=browser_session
)

`async input(index: int, text: str, clear: bool = True) -> ActionResult`

功能: 在输入框中输入文本

参数:
- index: 输入框元素索引
- text: 要输入的文本
- clear: 是否先清空输入框
返回: 输入结果
实现位置: browser_use/tools/service.py:369
特性: 支持敏感数据检测和脱敏

result = await tools.input(
    index=3,
    text="user@example.com",
    clear=True,
    browser_session=browser_session
)

`async upload_file(index: int, path: str) -> ActionResult`

功能: 上传文件到文件输入框

参数:
- index: 文件输入框索引
- path: 文件路径
返回: 上传结果
实现位置: browser_use/tools/service.py:438
特性: 自动查找最近的文件输入元素

result = await tools.upload_file(
    index=7,
    path="/path/to/file.pdf",
    browser_session=browser_session,
    available_file_paths=["/path/to/file.pdf"],
    file_system=file_system
)

2.3 滚动和视图方法

`async scroll(down: bool = True, pages: float = 1.0, index: int = None) -> ActionResult`

功能: 滚动页面或元素

参数:
- down: True 向下滚动，False 向上滚动
- pages: 滚动页数（0.5-10.0）
- index: 可选，滚动特定元素（如下拉框）
返回: 滚动结果
实现位置: browser_use/tools/service.py:789
特性: 自动检测视口高度，支持多页连续滚动

# 向下滚动 2 页
result = await tools.scroll(
    down=True,
    pages=2.0,
    browser_session=browser_session
)

# 滚动特定元素
result = await tools.scroll(
    down=True,
    pages=1.0,
    index=10,
    browser_session=browser_session
)

`async find_text(text: str) -> ActionResult`

功能: 查找并滚动到文本位置

参数: text - 要查找的文本
返回: 查找结果
实现位置: browser_use/tools/service.py:910

`async screenshot() -> ActionResult`

功能: 请求在下次观察中包含截图

返回: 包含截图请求标志的结果
实现位置: browser_use/tools/service.py:934
使用场景: 需要视觉检查页面状态时

2.4 标签页管理方法

`async switch(tab_id: str) -> ActionResult`

功能: 切换到指定标签页

参数: tab_id - 标签页 ID（target_id 的最后 4 位）
返回: 切换结果
实现位置: browser_use/tools/service.py:605

result = await tools.switch(
    tab_id="a3f2",
    browser_session=browser_session
)

`async close(tab_id: str) -> ActionResult`

功能: 关闭指定标签页

参数: tab_id - 标签页 ID
返回: 关闭结果
实现位置: browser_use/tools/service.py:630

2.5 下拉框操作方法

`async dropdown_options(index: int) -> ActionResult`

功能: 获取下拉框的所有选项

参数: index - 下拉框元素索引
返回: 包含所有选项的结果
实现位置: browser_use/tools/service.py:952

result = await tools.dropdown_options(
    index=8,
    browser_session=browser_session
)

`async select_dropdown(index: int, text: str) -> ActionResult`

功能: 选择下拉框选项

参数:
- index: 下拉框索引
- text: 要选择的选项文本
返回: 选择结果
实现位置: browser_use/tools/service.py:980

2.6 数据提取方法

`async extract(query: str, extract_links: bool = False, start_from_char: int = 0) -> ActionResult`

功能: 使用 LLM 从页面提取结构化数据

参数:
- query: 提取查询（告诉 LLM 要提取什么）
- extract_links: 是否提取链接
- start_from_char: 从哪个字符开始（用于分页提取）
返回: 提取的内容
实现位置: browser_use/tools/service.py:659
特性:
- 自动将 HTML 转换为 Markdown
- 过滤噪音内容
- 支持大内容分页提取（最大 100k 字符）

result = await tools.extract(
    query="提取页面上所有产品的名称和价格",
    extract_links=True,
    browser_session=browser_session,
    page_extraction_llm=llm,
    file_system=file_system
)

2.7 JavaScript 执行方法

`async evaluate(code: str) -> ActionResult`

功能: 在页面中执行 JavaScript 代码

参数: code - JavaScript 代码字符串
返回: 执行结果
实现位置: browser_use/tools/service.py:1098
特性:
- 自动修复常见 JavaScript 语法问题
- 支持 Promise
- 限制输出大小（20k 字符）
- 自动提取图片数据

result = await tools.evaluate(
    code="""
    (function(){
        try {
            const title = document.querySelector('h1');
            return title ? title.textContent : 'not found';
        } catch(e) {
            return 'Error: ' + e.message;
        }
    })()
    """,
    browser_session=browser_session
)

2.8 键盘操作方法

`async send_keys(keys: list[str]) -> ActionResult`

功能: 发送键盘按键序列

参数: keys - 按键列表（如 ['Control', 'a']）
返回: 操作结果
实现位置: browser_use/tools/service.py:894

result = await tools.send_keys(
    keys=['Control', 'a'],
    browser_session=browser_session
)

2.9 文件系统方法

`async write_file(file_name: str, content: str, append: bool = False) -> ActionResult`

功能: 写入文件到本地文件系统

参数:
- file_name: 文件名
- content: 文件内容
- append: 是否追加模式
返回: 写入结果
实现位置: browser_use/tools/service.py:1026
支持格式: .txt, .md, .json, .jsonl, .csv, .pdf

result = await tools.write_file(
    file_name="output.txt",
    content="Hello World",
    append=False,
    file_system=file_system
)

`async read_file(file_name: str) -> ActionResult`

功能: 读取文件内容

参数: file_name - 文件名
返回: 文件内容
实现位置: browser_use/tools/service.py:1060
支持格式: 文本文件、PDF、DOCX、图片

`async replace_file(file_name: str, old_str: str, new_str: str) -> ActionResult`

功能: 替换文件中的特定文本

参数:
- file_name: 文件名
- old_str: 要替换的文本
- new_str: 新文本
返回: 替换结果
实现位置: browser_use/tools/service.py:1052

2.10 任务完成方法

`async done(text: str, success: bool = True, files_to_display: list[str] = None) -> ActionResult`

功能: 标记任务完成

参数:
- text: 完成消息
- success: 是否成功
- files_to_display: 要显示的文件列表
返回: 包含 is_done=True 的结果
实现位置: browser_use/tools/service.py:1295

3. DOM 服务 (DomService)

文件位置: browser_use/dom/service.py

核心方法

`async get_all_trees(target_id: str) -> TargetAllTrees`

功能: 获取页面的所有 DOM 树

参数: target_id - 目标页面 ID
返回: 包含 DOM 树、可访问性树和快照的完整数据
实现位置: browser_use/dom/service.py:248
特性:
- 合并主框架和所有 iframe 的 DOM
- 包含元素位置、样式、可见性信息
- 支持跨域 iframe（可配置）

`is_element_visible_according_to_all_parents(node: EnhancedDOMTreeNode, html_frames: list) -> bool`

功能: 检查元素在所有父框架中是否可见

参数:
- node: DOM 节点
- html_frames: HTML 框架列表
返回: 是否可见
实现位置: browser_use/dom/service.py:125
检查项:
- CSS display/visibility/opacity
- 元素边界框
- iframe 视口交集
- 滚动位置

4. 页面交互 (Page)

文件位置: browser_use/actor/page.py

Page 类提供了对单个页面/标签的直接操作接口。

核心方法

`async evaluate(page_function: str, *args) -> str`

功能: 在页面中执行 JavaScript 函数

参数:
- page_function: 必须是箭头函数格式 (...args) => {...}
- *args: 传递给函数的参数
返回: 执行结果的字符串表示
实现位置: browser_use/actor/page.py:103

page = Page(browser_session, target_id)
result = await page.evaluate(
    "() => document.title"
)

`async screenshot(format: str = 'png', quality: int = None) -> str`

功能: 截取页面截图

参数:
- format: 图片格式 ('png', 'jpeg', 'webp')
- quality: JPEG 质量 (0-100)
返回: Base64 编码的图片数据
实现位置: browser_use/actor/page.py:192

`async press(key: str) -> None`

功能: 按下键盘按键

参数: key - 按键名称或组合键（如 "Enter", "Control+A"）
实现位置: browser_use/actor/page.py:213
支持: 单键和组合键（用 + 连接）

await page.press("Enter")
await page.press("Control+A")

`async reload() -> None`

功能: 重新加载页面

实现位置: browser_use/actor/page.py:90

`async set_viewport_size(width: int, height: int) -> None`

功能: 设置视口大小

参数:
- width: 宽度（像素）
- height: 高度（像素）
实现位置: browser_use/actor/page.py:279

`async get_element(backend_node_id: int) -> Element`

功能: 通过后端节点 ID 获取元素对象

参数: backend_node_id - 元素的后端节点 ID
返回: Element 对象
实现位置: browser_use/actor/page.py:95

`@property async mouse -> Mouse`

功能: 获取鼠标操作接口

返回: Mouse 对象
实现位置: browser_use/actor/page.py:81

5. 鼠标操作 (Mouse)

文件位置: browser_use/actor/mouse.py

核心方法

`async click(x: int, y: int, button: str = 'left', click_count: int = 1) -> None`

功能: 在指定坐标点击

参数:
- x, y: 坐标位置
- button: 鼠标按钮 ('left', 'right', 'middle')
- click_count: 点击次数（双击用 2）
实现位置: browser_use/actor/mouse.py:21

mouse = await page.mouse
await mouse.click(100, 200, button='left', click_count=1)

`async move(x: int, y: int, steps: int = 1) -> None`

功能: 移动鼠标到指定坐标

参数:
- x, y: 目标坐标
- steps: 移动步数（预留参数）
实现位置: browser_use/actor/mouse.py:77

`async down(button: str = 'left', click_count: int = 1) -> None`

功能: 按下鼠标按钮

参数:
- button: 鼠标按钮
- click_count: 点击计数
实现位置: browser_use/actor/mouse.py:49

`async up(button: str = 'left', click_count: int = 1) -> None`

功能: 释放鼠标按钮

参数: 同 down()
实现位置: browser_use/actor/mouse.py:63

`async scroll(x: int = 0, y: int = 0, delta_x: int = None, delta_y: int = None) -> None`

功能: 滚动页面

参数:
- x, y: 滚动起始坐标（默认视口中心）
- delta_x, delta_y: 滚动距离（正数向下/右）
实现位置: browser_use/actor/mouse.py:85
特性: 三种滚动方法自动降级

# 向下滚动 500 像素
await mouse.scroll(delta_y=500)

6. 元素操作 (Element)

文件位置: browser_use/actor/element.py

核心方法

`async click(button: str = 'left', click_count: int = 1, modifiers: list[str] = None) -> None`

功能: 点击元素

参数:
- button: 鼠标按钮
- click_count: 点击次数
- modifiers: 修饰键列表 (['Alt', 'Control', 'Meta', 'Shift'])
实现位置: browser_use/actor/element.py:93
特性:
- 自动获取元素几何信息
- 多种方法降级（getContentQuads → getBoxModel → getBoundingClientRect）
- 自动滚动到可见区域
- 检查元素可见性

element = await page.get_element(backend_node_id)
await element.click(button='left', click_count=1)

使用示例

完整的浏览器自动化流程

from browser_use import BrowserSession
from browser_use.tools.service import Tools
from browser_use.llm.base import BaseChatModel

# 1. 初始化浏览器会话
browser_session = BrowserSession(
    headless=False,
    user_data_dir="./profile"
)

# 2. 启动浏览器
await browser_session.start()

# 3. 初始化工具
tools = Tools()

# 4. 导航到网页
await tools.navigate(
    url="https://example.com",
    browser_session=browser_session
)

# 5. 等待页面加载
await tools.wait(seconds=2)

# 6. 获取页面元素
selector_map = await browser_session.get_selector_map()

# 7. 点击元素
await tools.click(
    index=5,
    browser_session=browser_session
)

# 8. 输入文本
await tools.input(
    index=3,
    text="search query",
    browser_session=browser_session
)

# 9. 滚动页面
await tools.scroll(
    down=True,
    pages=2.0,
    browser_session=browser_session
)

# 10. 提取数据
result = await tools.extract(
    query="提取所有产品信息",
    browser_session=browser_session,
    page_extraction_llm=your_llm
)

# 11. 清理
await browser_session.stop()

在你的 Agent 中集成

class MyAgent:
    def __init__(self):
        self.browser_session = BrowserSession(headless=False)
        self.tools = Tools()

    async def start(self):
        await self.browser_session.start()

    async def navigate_and_extract(self, url: str, query: str):
        # 导航
        await self.tools.navigate(
            url=url,
            browser_session=self.browser_session
        )

        # 等待加载
        await self.tools.wait(seconds=2)

        # 提取数据
        result = await self.tools.extract(
            query=query,
            browser_session=self.browser_session,
            page_extraction_llm=self.llm
        )

        return result.extracted_content

    async def cleanup(self):
        await self.browser_session.stop()

关键概念

ActionResult

所有工具方法返回的结果对象，包含：

extracted_content: 提取的内容（短期记忆）
long_term_memory: 长期记忆摘要
error: 错误信息
is_done: 是否完成任务
success: 是否成功
metadata: 元数据（如点击坐标）
attachments: 附件文件路径列表

EnhancedDOMTreeNode

增强的 DOM 节点对象，包含：

node_id: 节点 ID
node_name: 节点名称（如 'DIV', 'INPUT'）
node_type: 节点类型
attributes: 属性字典
absolute_position: 绝对位置
snapshot_node: 快照信息（样式、边界框等）
children_nodes: 子节点列表
parent_node: 父节点引用

CDPSession

CDP 会话对象，用于发送 CDP 命令：

cdp_client: CDP 客户端
target_id: 目标 ID
session_id: 会话 ID

注意事项

异步操作: 所有方法都是异步的，必须使用 await
会话管理: 使用前必须调用 browser_session.start()
资源清理: 使用完毕后调用 stop() 或 kill()
错误处理: 所有方法可能抛出异常，建议使用 try-except
元素索引: 元素索引可能因页面变化而失效，需要重新获取
坐标点击: 默认禁用，需要调用 tools.set_coordinate_clicking(True) 启用
文件路径: 上传文件时需要在 available_file_paths 中声明路径

扩展阅读

CDP 协议文档: https://chromedevtools.github.io/devtools-protocol/
Browser-Use 项目: https://github.com/browser-use/browser-use
事件驱动架构: 查看 browser_use/browser/events.py
Watchdog 服务: 查看 browser_use/browser/watchdog_base.py

文档版本: 1.0 最后更新: 2026-01-28 适用版本: browser-use >= 0.1.0

baseTools.md 20 KB Permalänk Historik Rå

Browser-Use 底层工具方法文档

目录

1. 浏览器会话管理 (BrowserSession)

核心方法

async start() -> None

async stop() -> None

async kill() -> None

async reset() -> None

async get_or_create_cdp_session(target_id: str, focus: bool = True) -> CDPSession

async get_current_page_url() -> str

async get_selector_map() -> dict[int, EnhancedDOMTreeNode]

async get_element_by_index(index: int) -> EnhancedDOMTreeNode | None

2. 页面操作工具 (Tools)

2.1 导航类方法

async search(query: str, engine: str = 'google') -> ActionResult

async navigate(url: str, new_tab: bool = False) -> ActionResult

async go_back() -> ActionResult

async wait(seconds: int = 3) -> ActionResult

2.2 元素交互方法

async click(index: int, coordinate_x: int = None, coordinate_y: int = None) -> ActionResult

async input(index: int, text: str, clear: bool = True) -> ActionResult

async upload_file(index: int, path: str) -> ActionResult

2.3 滚动和视图方法

async scroll(down: bool = True, pages: float = 1.0, index: int = None) -> ActionResult

async find_text(text: str) -> ActionResult

async screenshot() -> ActionResult

2.4 标签页管理方法

async switch(tab_id: str) -> ActionResult

async close(tab_id: str) -> ActionResult

2.5 下拉框操作方法

async dropdown_options(index: int) -> ActionResult

async select_dropdown(index: int, text: str) -> ActionResult

2.6 数据提取方法

async extract(query: str, extract_links: bool = False, start_from_char: int = 0) -> ActionResult

2.7 JavaScript 执行方法

async evaluate(code: str) -> ActionResult

2.8 键盘操作方法

async send_keys(keys: list[str]) -> ActionResult

2.9 文件系统方法

async write_file(file_name: str, content: str, append: bool = False) -> ActionResult

async read_file(file_name: str) -> ActionResult

async replace_file(file_name: str, old_str: str, new_str: str) -> ActionResult

2.10 任务完成方法

async done(text: str, success: bool = True, files_to_display: list[str] = None) -> ActionResult

3. DOM 服务 (DomService)

核心方法

async get_all_trees(target_id: str) -> TargetAllTrees

is_element_visible_according_to_all_parents(node: EnhancedDOMTreeNode, html_frames: list) -> bool

4. 页面交互 (Page)

核心方法

async evaluate(page_function: str, *args) -> str

async screenshot(format: str = 'png', quality: int = None) -> str

async press(key: str) -> None

async reload() -> None

async set_viewport_size(width: int, height: int) -> None

async get_element(backend_node_id: int) -> Element

@property async mouse -> Mouse

5. 鼠标操作 (Mouse)

核心方法

async click(x: int, y: int, button: str = 'left', click_count: int = 1) -> None

async move(x: int, y: int, steps: int = 1) -> None

async down(button: str = 'left', click_count: int = 1) -> None

async up(button: str = 'left', click_count: int = 1) -> None

async scroll(x: int = 0, y: int = 0, delta_x: int = None, delta_y: int = None) -> None

6. 元素操作 (Element)

核心方法

async click(button: str = 'left', click_count: int = 1, modifiers: list[str] = None) -> None

使用示例

完整的浏览器自动化流程

在你的 Agent 中集成

关键概念

ActionResult

EnhancedDOMTreeNode

CDPSession

注意事项

扩展阅读

baseTools.md 20 KB

Permalänk Historik Rå

`async start() -> None`

`async stop() -> None`

`async kill() -> None`

`async reset() -> None`

`async get_or_create_cdp_session(target_id: str, focus: bool = True) -> CDPSession`

`async get_current_page_url() -> str`

`async get_selector_map() -> dict[int, EnhancedDOMTreeNode]`

`async get_element_by_index(index: int) -> EnhancedDOMTreeNode | None`

`async search(query: str, engine: str = 'google') -> ActionResult`

`async navigate(url: str, new_tab: bool = False) -> ActionResult`

`async go_back() -> ActionResult`

`async wait(seconds: int = 3) -> ActionResult`

`async click(index: int, coordinate_x: int = None, coordinate_y: int = None) -> ActionResult`

`async input(index: int, text: str, clear: bool = True) -> ActionResult`

`async upload_file(index: int, path: str) -> ActionResult`

`async scroll(down: bool = True, pages: float = 1.0, index: int = None) -> ActionResult`

`async find_text(text: str) -> ActionResult`

`async screenshot() -> ActionResult`

`async switch(tab_id: str) -> ActionResult`

`async close(tab_id: str) -> ActionResult`

`async dropdown_options(index: int) -> ActionResult`

`async select_dropdown(index: int, text: str) -> ActionResult`

`async extract(query: str, extract_links: bool = False, start_from_char: int = 0) -> ActionResult`

`async evaluate(code: str) -> ActionResult`

`async send_keys(keys: list[str]) -> ActionResult`

`async write_file(file_name: str, content: str, append: bool = False) -> ActionResult`

`async read_file(file_name: str) -> ActionResult`

`async replace_file(file_name: str, old_str: str, new_str: str) -> ActionResult`

`async done(text: str, success: bool = True, files_to_display: list[str] = None) -> ActionResult`

`async get_all_trees(target_id: str) -> TargetAllTrees`

`is_element_visible_according_to_all_parents(node: EnhancedDOMTreeNode, html_frames: list) -> bool`

`async evaluate(page_function: str, *args) -> str`

`async screenshot(format: str = 'png', quality: int = None) -> str`

`async press(key: str) -> None`

`async reload() -> None`

`async set_viewport_size(width: int, height: int) -> None`

`async get_element(backend_node_id: int) -> Element`

`@property async mouse -> Mouse`

`async click(x: int, y: int, button: str = 'left', click_count: int = 1) -> None`

`async move(x: int, y: int, steps: int = 1) -> None`

`async down(button: str = 'left', click_count: int = 1) -> None`

`async up(button: str = 'left', click_count: int = 1) -> None`

`async scroll(x: int = 0, y: int = 0, delta_x: int = None, delta_y: int = None) -> None`

`async click(button: str = 'left', click_count: int = 1, modifiers: list[str] = None) -> None`