5.2 常用 API 详解

文档摘要

5.2 常用 API 详解 5.2 常用 API 详解为了更清晰地展现 API 之间的调用关系和工作流程，本章节将适当穿插使用 Mermaid 的图表，辅助读者理解。 5.2.1 核心 API：Agent 类类是库的核心，它代表一个具备浏览器交互能力的智能代理。开发者通过实例化类并配置相应的参数，即可创建一个能够根据自然语言指令在浏览器中执行任务的智能体。 5.2.1.1 Agent 类初始化参数详解类的初始化函数接受多个参数，这些参数控制着智能代理的行为和能力。以下是对常用参数的详细解释： 1. (str, 必传) 参数是描述智能代理需要执行的任务的自然语言字符串。这是接收到的最核心指令，它将指导 LLM（语言模型）进行解析、规划和执行。

5.2 常用 API 详解

为了更清晰地展现 API 之间的调用关系和工作流程，本章节将适当穿插使用 Mermaid 的 graph TD 图表，辅助读者理解。

5.2.1 核心 API：Agent 类

Agent 类是 browser-use 库的核心，它代表一个具备浏览器交互能力的智能代理。开发者通过实例化 Agent 类并配置相应的参数，即可创建一个能够根据自然语言指令在浏览器中执行任务的智能体。

5.2.1.1 Agent 类初始化参数详解

Agent 类的初始化函数接受多个参数，这些参数控制着智能代理的行为和能力。以下是对常用参数的详细解释：

1. task (str, 必传)

task 参数是描述智能代理需要执行的任务的自然语言字符串。这是 Agent 接收到的最核心指令，它将指导 LLM（语言模型）进行解析、规划和执行。task 应该清晰、明确地表达用户的意图，例如：“打开 https://www.example.com，点击 ‘登录’ 按钮，并输入用户名和密码”。


agent = Agent(
    task="打开 https://www.example.com，点击 ‘登录’ 按钮",
    llm=llm  # 假设 llm 已定义
)

2. llm (BaseChatModel, 必传)

llm 参数是 LangChain 提供的语言模型实例，用于驱动智能代理的决策和规划。browser-use 能够与 LangChain 框架无缝集成，支持各种 LLM，如 OpenAI 的 GPT 系列、Anthropic 的 Claude、Google 的 Gemini 等。选择合适的 LLM 模型将直接影响智能代理的理解能力、规划能力和执行效果。


from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o")
agent = Agent(
    task="...",
    llm=llm
)

3. controller (Controller, 可选, 默认 Controller() )

controller 参数允许用户自定义函数或工具调用，扩展智能代理的能力。Controller 实例充当自定义动作的注册表。通过注册自定义 action，用户可以使智能代理执行 browser-use 默认 actions 之外的操作，例如数据处理、文件保存、数据库交互等。关于 Controller 的详细用法将在后续章节中展开。


from browser_use import Controller, Agent
from browser_use.agent.views import ActionResult
controller = Controller()
@controller.registry.action("保存文本到文件")
def save_text_to_file(text: str, filepath: str) -> ActionResult:
    """自定义 action: 将文本保存到指定文件路径"""
    with open(filepath, "w") as f:
        f.write(text)
    return ActionResult(extracted_content="文本已保存到文件: " + filepath)
agent = Agent(
    task="...",
    llm=llm,
    controller=controller
)

4. use_vision (bool, 可选, 默认 True )

use_vision 参数控制是否启用视觉能力。当设置为 True 时，智能代理可以利用截图和视觉分析来理解网页内容。如果使用的 LLM 模型支持图像输入（例如 GPT-4o, Gemini Pro Vision），启用视觉能力可以显著提高智能代理对网页的理解和操作精度，尤其是在处理复杂布局或动态内容时。但需要注意的是，启用视觉能力可能会产生额外的 token 成本。


agent = Agent(
    task="...",
    llm=llm,
    use_vision=True  # 启用视觉能力
)

5. save_conversation_path (str, 可选, 默认 None )

save_conversation_path 参数用于指定对话历史的保存路径。如果设置了该参数，browser-use 会将智能代理的对话历史记录保存到指定路径下的文件中，方便用户进行调试、审计或后续分析。


agent = Agent(
    task="...",
    llm=llm,
    save_conversation_path="./conversation_history.json" # 保存对话历史到指定文件
)

6. system_prompt_class (type, 可选, 默认 Prompt 类)

system_prompt_class 参数允许用户自定义系统提示词逻辑。browser-use 默认使用内置的 Prompt 类来生成系统提示词。如果用户需要定制化系统提示词的生成方式，例如根据任务类型动态调整提示词内容，可以继承 Prompt 类并重写相关方法，然后将自定义的 Prompt 类传递给 system_prompt_class 参数。


from browser_use.prompt import Prompt
class CustomPrompt(Prompt):
    def generate_system_prompt(self, task: str, **kwargs) -> str:
        # 自定义系统提示词生成逻辑
        return f"Custom System Prompt for task: {task}"
agent = Agent(
    task="...",
    llm=llm,
    system_prompt_class=CustomPrompt # 使用自定义 Prompt 类
)

7. browser (Browser, 可选, 默认 None )

browser 参数允许用户重用已创建的 Browser 实例。如果用户不提供 browser 参数，Agent 在每次调用 run() 方法时会自动创建并关闭新的浏览器实例。当需要更精细地控制浏览器实例的生命周期或需要在多个 Agent 之间共享同一个浏览器实例时，可以使用 browser 参数。


from browser_use.browser.browser import Browser, BrowserConfig
browser_instance = Browser(config=BrowserConfig()) # 创建 Browser 实例
agent1 = Agent(task="...", llm=llm, browser=browser_instance) # Agent 1 使用该实例
agent2 = Agent(task="...", llm=llm, browser=browser_instance) # Agent 2 也使用该实例

8. browser_context (BrowserContext, 可选, 默认 None )

browser_context 参数允许用户使用已有的浏览器上下文 (Context)。浏览器上下文可以维护持久会话信息，如 cookies、localStorage 等。在需要保持登录状态或跨多个任务维护会话信息的场景中，使用 browser_context 参数非常有用。


from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context() # 创建 Playwright BrowserContext
    agent = Agent(task="...", llm=llm, browser_context=context) # Agent 使用该 Context
    # ... 执行任务 ...
    context.close()
    browser.close()

9. max_steps (int, 可选, 默认 100 )

max_steps 参数限制智能代理执行的最大步骤数。每个步骤通常对应一次 LLM 调用和一系列浏览器操作。设置 max_steps 可以防止智能代理陷入死循环或无限操作，确保任务执行的可控性。


agent = Agent(
    task="...",
    llm=llm,
    max_steps=50 # 限制最大步骤数为 50
)

10. planner_llm (BaseChatModel, 可选, 默认 None )

planner_llm 参数允许用户为智能代理配置一个专门用于规划的语言模型。默认情况下，Agent 使用 llm 参数指定的模型进行任务规划和动作决策。如果用户希望使用不同的模型进行规划和执行，例如使用较小或更经济的模型进行高层策略规划，可以使用 planner_llm 参数。


planner_llm = ChatOpenAI(model="gpt-3.5-turbo") # 使用 GPT-3.5-turbo 进行规划
agent = Agent(
    task="...",
    llm=llm, # 主 LLM (例如 GPT-4o)
    planner_llm=planner_llm # 规划 LLM
)

11. use_vision_for_planner (bool, 可选, 默认 True )

use_vision_for_planner 参数控制规划模型是否可以使用视觉功能。当 planner_llm 参数被设置时，该参数决定是否允许规划模型使用视觉能力。如果主 LLM 已经开启了视觉能力 (use_vision=True)，用户可以通过设置 use_vision_for_planner=False 来独立关闭规划模型的视觉功能，从而节省资源。


agent = Agent(
    task="...",
    llm=llm,
    planner_llm=planner_llm,
    use_vision=True, # 主 LLM 启用视觉
    use_vision_for_planner=False # 规划 LLM 不使用视觉
)

12. planner_interval (int, 可选, 默认 1 )

planner_interval 参数定义规划模型执行的间隔。它表示智能代理每执行多少步调用一次规划模型进行重新规划。默认值为 1，表示每一步都可能进行重新规划。用户可以根据任务的复杂度和资源限制调整该参数，例如设置为 5 表示每 5 步调用一次规划模型。


agent = Agent(
    task="...",
    llm=llm,
    planner_llm=planner_llm,
    planner_interval=5 # 每 5 步进行一次重新规划
)

13. message_context (str, 可选, 默认 None )

message_context 参数允许用户提供额外的任务或上下文信息，辅助 LLM 更好地理解或执行任务。这些信息不会直接显示在任务描述中，但会作为上下文传递给 LLM，帮助模型更准确地把握用户意图。


agent = Agent(
    task="...",
    llm=llm,
    message_context="用户偏好设置：喜欢简洁风格的网页" # 提供额外的上下文信息
)

14. initial_actions (list[dict], 可选, 默认 None )

initial_actions 参数允许用户在智能代理初始化时指定要执行的动作列表。这些动作会在任务开始前被执行，无需经过 LLM 调用。initial_actions 可以用于设置初始浏览器状态或执行一些预热操作。动作列表的格式为 [{action_name: {action_parameters}}]。


agent = Agent(
    task="...",
    llm=llm,
    initial_actions=[
        {"goto_url": {"url": "https://www.google.com"}}, # 初始化时打开 Google 首页
        {"set_viewport_size": {"width": 1280, "height": 720}} # 设置浏览器窗口大小
    ]
)

15. max_actions_per_step (int, 可选, 默认 1 )

max_actions_per_step 参数限制每个步骤中智能代理可以执行的最大动作数。每个步骤通常由 LLM 规划生成一系列动作。设置该参数可以控制智能代理的操作频率，防止其过度频繁地操作浏览器。


agent = Agent(
    task="...",
    llm=llm,
    max_actions_per_step=2 # 每个步骤最多执行 2 个动作
)

16. max_failures (int, 可选, 默认 3 )

max_failures 参数定义智能代理允许失败的最大次数。如果在执行任务过程中，智能代理遇到错误并失败的次数超过 max_failures，任务将停止执行。该参数用于控制任务的健壮性，防止因持续错误导致无限重试。


agent = Agent(
    task="...",
    llm=llm,
    max_failures=2 # 允许最大失败次数为 2
)

17. retry_delay (int, 可选, 默认 10 秒)

retry_delay 参数设置在遇到限流 (rate limit) 或可重试的错误时，智能代理等待多少秒后再次尝试。该参数用于处理网络波动或服务不稳定等暂时性错误，提高任务的成功率。


agent = Agent(
    task="...",
    llm=llm,
    retry_delay=5 # 遇到可重试错误时等待 5 秒后重试
)

18. generate_gif (bool 或 str, 可选, 默认 False )

generate_gif 参数控制是否录制浏览器操作过程并生成 GIF 动画。当设置为 True 时，browser-use 会自动生成一个随机文件名的 GIF 文件保存浏览器操作过程。如果设置为字符串路径，GIF 文件将保存到指定的路径。该功能对于调试、演示或记录智能代理的行为非常有用。


agent = Agent(
    task="...",
    llm=llm,
    generate_gif=True # 自动生成 GIF 文件
    # generate_gif="./task_record.gif" # 保存 GIF 到指定路径
)

5.2.1.2 Agent 类核心方法：`run()`

Agent 类最核心的方法是 run() 方法。该方法启动智能代理的执行流程，根据 task 参数描述的任务，驱动 LLM 进行解析、规划和浏览器操作，最终返回任务执行结果。run() 方法是一个异步方法，需要使用 asyncio.run() 或 await 调用。


import asyncio
from browser_use import Agent
from langchain_openai import ChatOpenAI
from dotenv import load_dotenv
load_dotenv()
llm = ChatOpenAI(model="gpt-4o")
async defmain():
    agent = Agent(
        task="打开 https://cn.vuejs.org/guide/essentials/computed，获取页面里所有的 h2 标签文本及所有的 a 标签文本（以及它的 href）",
        llm=llm,
    )
    result = await agent.run()
    print('result:', result)
if __name__ == "__main__":
    asyncio.run(main())

当调用 agent.run() 后，智能代理将按照以下流程执行任务：

流程说明:

用户任务 (task): 用户通过 task 参数向 Agent 描述需要执行的任务。
Agent.run(): 调用 agent.run() 方法启动任务执行。
LLM 解析任务: Agent 将 task 传递给配置的 LLM (llm 或 planner_llm) 进行解析，理解用户意图。
Agent 决策/规划: LLM 基于解析结果，结合可用的 actions 和当前浏览器状态，制定任务执行计划，生成一系列浏览器操作指令。
浏览器动作: Agent 将 LLM 规划的浏览器操作指令转换为具体的 Playwright API 调用。
Playwright 调用: browser-use 内部使用 Playwright 库驱动浏览器自动化。Playwright API 将被调用，控制浏览器执行相应的操作，例如页面导航、元素点击、文本输入等。
浏览器实例: Playwright 驱动真实的浏览器实例 (Chromium, Firefox, WebKit)。
数据提取: 在浏览器执行操作后，Agent 可以从页面中提取所需信息。提取方式可以是基于 HTML 结构分析、视觉分析 (如果 use_vision 启用) 或其他自定义方法。
模型处理 (结构化): 提取的数据可以进一步由 LLM 进行处理和结构化，以便更好地满足用户需求。
结构化结果输出: Agent.run() 方法最终返回结构化的任务执行结果。结果通常包含提取的内容、执行状态、以及可能的其他信息，例如对话历史或录制的 GIF 文件路径。
返回 Agent.run(): run() 方法将处理后的结果返回给调用者。

run() 方法返回值:

run() 方法返回一个字典 (或 ActionResult 对象，最终会被转换为字典)，包含任务执行的结果。返回值的具体结构会根据任务类型和 Agent 的配置而有所不同，但通常会包含以下关键信息：

extracted_content: (str 或 dict 或 list) 提取的网页内容，具体格式取决于任务需求。例如，可以是文本字符串、JSON 对象、列表等。
status: (str) 任务执行状态，例如 "success"、"failed" 等。
conversation_history: (list, 可选) 如果启用了对话历史记录，则包含任务执行过程中的对话历史。
gif_path: (str, 可选) 如果启用了 GIF 录制，则包含录制生成的 GIF 文件路径。
其他自定义字段: 根据自定义 actions 的定义，返回值可能包含其他自定义字段。

代码示例:


import asyncio
from browser_use import Agent
from langchain_openai import ChatOpenAI
from dotenv import load_dotenv
load_dotenv()
llm = ChatOpenAI(model="gpt-4o")
async def main():
    agent = Agent(
        task="打开 https://www.example.com，获取页面标题和前三段文本内容。",
        llm=llm,
    )
    result = await agent.run()
    print("任务结果:", result)
if __name__ == "__main__":
    asyncio.run(main())

在这个例子中，agent.run() 将驱动智能代理执行以下操作：

访问 https://www.example.com。
提取网页的 <title> 标签文本。
提取网页的前三个 <p> 标签文本。
将提取的标题和文本内容封装在结果字典中返回。

5.2.2 Controller 类详解

Controller 类在 browser-use 中扮演着动作注册中心的角色。它允许开发者注册自定义的 actions，扩展智能代理的能力，使其能够执行超出默认浏览器操作范围的任务。通过 Controller，用户可以将自身业务逻辑或特定工具集成到智能代理的工作流程中。

5.2.2.1 Controller 类初始化与基本用法

Controller 类的初始化非常简单，直接实例化即可：


from browser_use import Controller
controller = Controller()

创建 Controller 实例后，就可以使用其 registry 属性来注册自定义 actions。registry 属性是一个 ActionRegistry 实例，提供了 action() 装饰器用于注册 action 函数。

使用 @controller.registry.action() 装饰器注册 action:


from browser_use import Controller
from browser_use.agent.views import ActionResult
controller = Controller()
@controller.registry.action("自定义Action名称")
def custom_action_function(参数1: 类型, 参数2: 类型, ...) -> ActionResult:
    """Action 函数的文档字符串 (可选)"""
    # Action 函数的具体逻辑
    # ...
    return ActionResult(extracted_content="Action 执行结果") # 返回 ActionResult 对象

注册 action 的关键要素:

@controller.registry.action("Action 名称"): 使用 action() 装饰器，并提供 action 的名称。这个名称将用于在 LLM 的规划结果中引用该 action。Action 名称应该具有描述性，方便 LLM 理解和调用。
custom_action_function(参数: 类型, ...): 定义 action 函数。
- 参数: Action 函数可以接受参数。参数类型需要明确声明，browser-use 会根据类型提示进行参数解析和传递。参数类型可以是 Python 内置类型 (str, int, float, bool, list, dict) 或 Pydantic 模型。
- 返回值: Action 函数必须返回 ActionResult 对象。ActionResult 用于封装 action 的执行结果，包括提取的内容 (extracted_content) 和其他可选信息。

ActionResult 对象:

ActionResult 类用于封装 action 函数的返回值。它至少需要包含 extracted_content 属性，用于传递 action 执行后提取或生成的数据。


from browser_use.agent.views import ActionResult
# 创建 ActionResult 对象
result = ActionResult(extracted_content="这是 action 的执行结果")
# 可以添加额外的 metadata
result_with_metadata = ActionResult(
    extracted_content="这是 action 的执行结果",
    metadata={"file_path": "/path/to/saved/file.txt"}
)

ActionResult 的常用参数:

extracted_content (Any, 可选, 默认 None): Action 提取或生成的主要内容。可以是字符串、数字、列表、字典等任何 Python 对象。
metadata (dict, 可选, 默认 None): 额外的元数据，用于传递 action 执行的辅助信息，例如文件路径、状态信息等。

5.2.2.2 自定义 Action 示例：保存网页内容到文件

以下示例演示如何创建一个自定义 action，用于将网页内容保存到本地文件：


import asyncio
from browser_use import Agent, Controller
from browser_use.agent.views import ActionResult
from langchain_openai import ChatOpenAI
from dotenv import load_dotenv
load_dotenv()
llm = ChatOpenAI(model="gpt-4o")
controller = Controller()
@controller.registry.action("保存网页内容到文件")
def save_webpage_content(url: str, filepath: str) -> ActionResult:
    """自定义 action:  访问指定 URL，获取网页 HTML 内容，并保存到本地文件。"""
    import requests
    try:
        response = requests.get(url)
        response.raise_for_status() # 检查请求是否成功
        html_content = response.text
        with open(filepath, "w", encoding="utf-8") as f:
            f.write(html_content)
        return ActionResult(extracted_content=f"网页内容已保存到: {filepath}")
    except requests.exceptions.RequestException as e:
        return ActionResult(extracted_content=f"保存网页内容失败: {e}", status="failed")
async def main():
    agent = Agent(
        task="访问 https://www.example.com，将网页内容保存到文件 example.html",
        llm=llm,
        controller=controller # 注册自定义 controller
    )
    result = await agent.run()
    print("任务结果:", result)
if __name__ == "__main__":
    asyncio.run(main())

代码解析:

定义 save_webpage_content action:
- 使用 @controller.registry.action("保存网页内容到文件") 装饰器注册 action，命名为 "保存网页内容到文件"。
- Action 函数接受两个参数： url (str) - 网页 URL, filepath (str) - 保存文件路径。
- 函数内部使用 requests 库获取网页 HTML 内容，并保存到指定文件。
- 成功时返回 ActionResult 对象，extracted_content 包含成功消息。
- 失败时返回 ActionResult 对象，extracted_content 包含错误信息，并设置 status="failed"。
创建 Agent 实例:
- 在创建 Agent 实例时，将 controller 参数设置为我们定义的 controller 实例，从而使 Agent 可以使用自定义的 "保存网页内容到文件" action。
执行任务:
- task 描述了用户意图："访问 https://www.example.com，将网页内容保存到文件 example.html"。
- Agent 会解析 task，识别出需要执行 "保存网页内容到文件" action，并从 task 中提取 action 参数 (URL 和文件路径)。
- Agent 调用 save_webpage_content 函数，并将参数传递给函数。
- Action 函数执行网页内容保存操作，并返回结果。
- Agent.run() 返回最终的任务结果。

5.2.2.3 Action 参数类型与 Pydantic 模型

自定义 action 函数的参数类型可以是 Python 内置类型，也可以是 Pydantic 模型。使用 Pydantic 模型可以更灵活地定义复杂的数据结构，并利用 Pydantic 的数据验证和序列化功能。

示例：使用 Pydantic 模型定义 Action 参数


from browser_use import Controller
from browser_use.agent.views import ActionResult
from pydantic import BaseModel
controller = Controller()
class FileSaveConfig(BaseModel):
    filepath: str
    content: str
@controller.registry.action("保存内容到文件 (Pydantic)")
def save_content_to_file_pydantic(config: FileSaveConfig) -> ActionResult:
    """使用 Pydantic 模型作为参数的自定义 action"""
    try:
        with open(config.filepath, "w", encoding="utf-8") as f:
            f.write(config.content)
        return ActionResult(extracted_content=f"内容已保存到: {config.filepath}")
    except Exception as e:
        return ActionResult(extracted_content=f"保存内容失败: {e}", status="failed")

在这个例子中，我们定义了一个 Pydantic 模型 FileSaveConfig，用于描述文件保存的配置信息，包括 filepath 和 content 两个字段。save_content_to_file_pydantic action 函数的参数类型被声明为 FileSaveConfig。

当 LLM 规划调用 "保存内容到文件 (Pydantic)" action 时，它需要提供符合 FileSaveConfig 模型结构的数据，例如：


{
    "action_name": "保存内容到文件 (Pydantic)",
    "action_parameters": {
        "config": {
            "filepath": "output.txt",
            "content": "This is the content to be saved."
        }
    }
}

browser-use 会自动将 JSON 数据解析为 FileSaveConfig 对象，并传递给 action 函数。Pydantic 模型的类型提示和验证功能可以帮助确保 action 函数接收到正确格式的参数，提高代码的健壮性。

5.2.3 Browser 类详解

Browser 类负责管理浏览器实例的生命周期和配置。它封装了 Playwright 的浏览器启动、关闭等操作，并提供了一些配置选项，允许用户定制浏览器的行为。

5.2.3.1 Browser 类初始化与配置

创建 Browser 实例需要使用 BrowserConfig 对象进行配置。BrowserConfig 类提供了一系列参数，用于配置浏览器实例的启动行为。

BrowserConfig 类参数详解:

BrowserConfig 类的初始化函数接受多个参数，用于配置浏览器实例。以下是对常用参数的详细解释：

1. browser_type (str, 可选, 默认 'chromium' )

browser_type 参数指定要使用的浏览器类型。browser-use 基于 Playwright，支持 Chromium, Firefox, 和 WebKit 三种浏览器内核。可选值包括：

'chromium': 使用 Chromium 内核浏览器 (例如 Chrome, Edge)。
'firefox': 使用 Firefox 浏览器。
'webkit': 使用 WebKit 内核浏览器 (例如 Safari)。


from browser_use.browser.browser import Browser, BrowserConfig
# 使用 Firefox 浏览器
browser_config_firefox = BrowserConfig(browser_type='firefox')
browser_firefox = Browser(config=browser_config_firefox)
# 使用 WebKit 浏览器
browser_config_webkit = BrowserConfig(browser_type='webkit')
browser_webkit = Browser(config=browser_config_webkit)
# 使用默认 Chromium 浏览器
browser_config_chromium = BrowserConfig() # 默认 browser_type='chromium'
browser_chromium = Browser(config=browser_config_chromium)

2. headless (bool, 可选, 默认 True )

headless 参数控制浏览器是否以无头模式运行。

True: (默认) 以无头模式运行。无头模式下，浏览器在后台运行，没有图形界面显示。这种模式适合自动化任务，效率更高，资源占用更少。
False: 以有头模式运行。有头模式下，会显示浏览器窗口，用户可以直观地看到浏览器的操作过程。这种模式适合调试和演示。


from browser_use.browser.browser import Browser, BrowserConfig
# 以有头模式运行 Chromium 浏览器
browser_config_headed = BrowserConfig(headless=False)
browser_headed = Browser(config=browser_config_headed)
# 以无头模式运行 (默认)
browser_config_headless = BrowserConfig(headless=True) # 默认 headless=True
browser_headless = Browser(config=browser_config_headless)

3. slow_mo (int, 可选, 默认 0 )

slow_mo 参数设置浏览器操作的延迟时间 (毫秒)。当 slow_mo 大于 0 时，每个浏览器操作 (例如点击、输入) 都会延迟指定的毫秒数。这主要用于演示和调试，可以放慢浏览器操作速度，更清晰地观察操作过程。


from browser_use.browser.browser import Browser, BrowserConfig
# 每个操作延迟 500 毫秒
browser_config_slowmo = BrowserConfig(slow_mo=500)
browser_slowmo = Browser(config=browser_config_slowmo)

4. devtools (bool, 可选, 默认 False )

devtools 参数控制是否在启动浏览器时打开开发者工具 (DevTools)。

True: 启动浏览器时自动打开 DevTools 面板。这在调试网页加载、性能分析或查看网络请求时非常有用。
False: (默认) 不打开 DevTools。


from browser_use.browser.browser import Browser, BrowserConfig
# 启动浏览器并打开 DevTools
browser_config_devtools = BrowserConfig(devtools=True)
browser_devtools = Browser(config=browser_config_devtools)

5. chrome_instance_path (str, 可选, 默认 None )

chrome_instance_path 参数允许用户指定已安装的 Chrome 浏览器可执行文件路径。默认情况下，Playwright 会使用其自带的 Chromium 版本。如果用户希望使用系统上已安装的 Chrome 浏览器，可以设置该参数。


from browser_use.browser.browser import Browser, BrowserConfig
# 指定 Chrome 浏览器可执行文件路径 (Windows 示例)
chrome_path = "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
browser_config_chrome_path = BrowserConfig(chrome_instance_path=chrome_path)
browser_chrome_path = Browser(config=browser_config_chrome_path)

注意: 使用 chrome_instance_path 参数时，需要确保指定的路径是 Chrome 浏览器的可执行文件路径，并且 Playwright 能够正确访问该路径。

6. browser_launch_kwargs (dict, 可选, 默认 {} )

browser_launch_kwargs 参数允许用户传递额外的 Playwright 浏览器启动参数。Playwright 的 browser.launch() 方法接受很多可选参数，例如 proxy, viewport, args 等。用户可以通过 browser_launch_kwargs 参数将这些参数传递给 Playwright。

例如，设置代理服务器：


from browser_use.browser.browser import Browser, BrowserConfig
# 设置代理服务器
proxy_config = {
    "server": "http://proxy.example.com:8080",
    "username": "proxy_user",
    "password": "proxy_password"
}
browser_config_proxy = BrowserConfig(browser_launch_kwargs={"proxy": proxy_config})
browser_proxy = Browser(config=browser_config_proxy)

更多 Playwright 浏览器启动参数，请参考 Playwright 官方文档: https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch

5.2.3.2 Browser 类方法

Browser 类提供了一些方法用于管理浏览器实例：

browser.new_context(**kwargs): 创建一个新的浏览器上下文 (BrowserContext)。BrowserContext 允许在同一个浏览器实例中创建多个隔离的会话，每个会话拥有独立的 cookies, localStorage 等。关于 BrowserContext 的详细信息将在下一节介绍。
browser.close(): 关闭浏览器实例。释放浏览器进程和相关资源。通常在任务执行完成后调用 browser.close() 方法来清理资源。

Browser 类生命周期管理:

Browser 实例的生命周期通常由 Agent 类自动管理。当 Agent 初始化时，如果没有提供 browser 参数，Agent 会在内部创建一个 Browser 实例。在每次调用 agent.run() 方法时，Agent 会使用这个 Browser 实例进行浏览器操作。任务执行完成后，如果 Agent 是自动创建的 Browser 实例，Agent 会自动关闭该实例。

如果用户通过 browser 参数向 Agent 传递了预先创建的 Browser 实例，则 Agent 不会负责管理该实例的生命周期。用户需要手动调用 browser.close() 方法来关闭浏览器实例。

5.2.4 BrowserContext 类详解

BrowserContext 类代表一个浏览器上下文，它提供了一个隔离的浏览环境。同一个 Browser 实例可以创建多个 BrowserContext，每个 Context 拥有独立的会话状态，例如 cookies, localStorage, 缓存等。这使得在同一个浏览器实例中模拟多个用户会话或执行并行任务成为可能。

5.2.4.1 BrowserContext 类创建与配置

BrowserContext 实例通常通过 Browser 实例的 new_context() 方法创建。new_context() 方法接受一个可选的 BrowserContextConfig 对象，用于配置 Context 的行为。

BrowserContextConfig 类参数详解:

BrowserContextConfig 类提供了一些参数用于配置浏览器上下文。以下是对常用参数的详细解释：

1. viewport (dict, 可选, 默认 None )

viewport 参数设置浏览器视口大小。视口大小决定了网页在浏览器中渲染的区域大小。可以设置 width 和 height 属性来指定视口宽度和高度。


from browser_use.browser.browser import Browser, BrowserConfig
from browser_use.browser.context import BrowserContextConfig
browser_config = BrowserConfig()
browser = Browser(config=browser_config)
# 设置视口大小为 1280x720
context_config_viewport = BrowserContextConfig(viewport={"width": 1280, "height": 720})
context_viewport = browser.new_context(config=context_config_viewport)

2. user_agent (str, 可选, 默认 None )

user_agent 参数设置浏览器 User-Agent 字符串。User-Agent 字符串是浏览器在 HTTP 请求头中发送给服务器的标识，用于告知服务器浏览器的类型和版本等信息。修改 User-Agent 可以模拟不同的浏览器或设备。


from browser_use.browser.browser import Browser, BrowserConfig
from browser_use.browser.context import BrowserContextConfig
browser_config = BrowserConfig()
browser = Browser(config=browser_config)
# 设置 User-Agent 为 iPhone Safari
user_agent_iphone = "Mozilla/iPhone..." # 实际 User-Agent 字符串
context_config_useragent = BrowserContextConfig(user_agent=user_agent_iphone)
context_useragent = browser.new_context(config=context_config_useragent)

3. locale (str, 可选, 默认 None )

locale 参数设置浏览器的区域设置。区域设置影响网页内容的语言和格式 (例如日期、数字格式)。


from browser_use.browser.browser import Browser, BrowserConfig
from browser_use.browser.context import BrowserContextConfig
browser_config = BrowserConfig()
browser = Browser(config=browser_config)
# 设置区域设置为中文 (中国)
context_config_locale = BrowserContextConfig(locale="zh-CN")
context_locale = browser.new_context(config=context_config_locale)

4. storage_state_path (str, 可选, 默认 None )

storage_state_path 参数允许用户加载或保存浏览器上下文的存储状态 (例如 cookies, localStorage)。

加载存储状态: 如果指定了一个已存在的 JSON 文件路径，BrowserContext 会从该文件中加载存储状态，恢复之前的会话。
保存存储状态: 在 BrowserContext 关闭时，如果指定了一个文件路径，BrowserContext 会将当前的存储状态保存到该文件中。


from browser_use.browser.browser import Browser, BrowserConfig
from browser_use.browser.context import BrowserContextConfig
browser_config = BrowserConfig()
browser = Browser(config=browser_config)
# 从文件加载存储状态
context_config_load_storage = BrowserContextConfig(storage_state_path="./storage_state.json")
context_load_storage = browser.new_context(config=context_config_load_storage)
# ... 执行操作 ...
# 关闭 Context 时保存存储状态到文件
context_config_save_storage = BrowserContextConfig(storage_state_path="./storage_state.json")
context_save_storage = browser.new_context(config=context_config_save_storage)
# ... 执行操作 ...
context_save_storage.close() # 关闭时存储状态会被保存到 storage_state.json

5. extra_http_headers (dict, 可选, 默认 {} )

extra_http_headers 参数允许用户设置额外的 HTTP 请求头。这些请求头会在浏览器发起的所有 HTTP 请求中被添加。


from browser_use.browser.browser import Browser, BrowserConfig
from browser_use.browser.context import BrowserContextConfig
browser_config = BrowserConfig()
browser = Browser(config=browser_config)
# 添加自定义 HTTP 请求头
extra_headers = {"X-Custom-Header": "CustomValue"}
context_config_headers = BrowserContextConfig(extra_http_headers=extra_headers)
context_headers = browser.new_context(config=context_config_headers)

6. context_kwargs (dict, 可选, 默认 {} )

context_kwargs 参数允许用户传递额外的 Playwright 浏览器上下文创建参数。Playwright 的 browser.new_context() 方法也接受一些可选参数，例如 ignore_https_errors, record_video_dir 等。用户可以通过 context_kwargs 参数将这些参数传递给 Playwright。

更多 Playwright 浏览器上下文创建参数，请参考 Playwright 官方文档: https://playwright.dev/python/docs/api/class-browser#browser-new-context

5.2.4.2 BrowserContext 类方法

BrowserContext 类提供了一系列方法，用于在浏览器上下文中进行网页操作和管理：

context.new_page(): 在当前浏览器上下文中创建一个新的页面 (Page)。Page 类是进行网页内容交互的核心 API，将在后续章节详细介绍。

5.2 常用 API 详解

文档摘要