Skip to main content

Documentation Index

Fetch the complete documentation index at: https://browser-use.mingxi.ltd/llms.txt

Use this file to discover all available pages before exploring further.

​
概述

Agent 类是 Browser Use 处理浏览器自动化的核心组件。以下是初始化代理时可以使用的主要配置选项。

​
基本设置

from browser_use import Agent
from langchain_openai import ChatOpenAI

agent = Agent(
    task="搜索关于 AI 的最新新闻",
    llm=ChatOpenAI(model="gpt-4o"),
)

​
必需参数

  • task: 代理要执行的指令
  • llm: LangChain 聊天模型实例。查看 LangChain 模型 了解支持的模型。

​
代理行为

控制代理如何运行: 
agent = Agent(
    task="你的任务",
    llm=llm,
    controller=custom_controller,  # 用于自定义工具调用
    use_vision=True,              # 启用视觉能力
    save_conversation_path="logs/conversation"  # 保存聊天日志
)

​
行为参数

  • controller: 代理可以调用的函数注册表。默认为基础 Controller。详见 自定义函数。
  • use_vision: 启用/禁用视觉能力。默认为 True。
    • 启用时，模型会处理网页的视觉信息
    • 禁用以降低成本或使用不支持视觉的模型
    • 对于 GPT-4o，图像处理每张图片大约需要 800-1000 个令牌(约 0.002 美元)，但这取决于定义的屏幕大小
  • save_conversation_path: 保存完整对话历史的路径。用于调试。
  • system_prompt_class: 自定义系统提示类。查看 系统提示 了解自定义选项。
建议启用视觉能力以更好地理解网页交互， 但可以禁用以降低成本或在使用不支持视觉的模型时。

​
(重用)浏览器配置

你可以配置代理如何与浏览器交互。要查看更多 Browser 选项，请参考 浏览器设置 文档。

​
重用现有浏览器

browser: Browser Use Browser 实例。提供时，代理将重用此浏览器实例，并为每个 run() 自动创建新的上下文。 
from browser_use import Agent, Browser
from browser_use.browser.context import BrowserContext

# 重用现有浏览器
browser = Browser()
agent = Agent(
    task=task1,
    llm=llm,
    browser=browser  # 浏览器实例将被重用
)

await agent.run()

# 手动关闭浏览器
await browser.close()
记住: 在这种情况下，Browser 不会自动关闭。

​
重用现有浏览器上下文

browser_context: Playwright 浏览器上下文。用于维护持久会话。详见 持久浏览器。 
from browser_use import Agent, Browser
from playwright.async_api import BrowserContext

# 使用特定浏览器上下文(推荐方法)
async with await browser.new_context() as context:
    agent = Agent(
        task=task2,
        llm=llm,
        browser_context=context  # 使用持久上下文
    )

    # 运行代理
    await agent.run()

    # 将上下文传递给下一个代理
    next_agent = Agent(
        task=task2,
        llm=llm,
        browser_context=context
    )

    ...

await browser.close()
有关浏览器上下文如何工作的更多信息，请参考 Playwright 文档。
你可以为多个代理重用相同的上下文。如果你什么都不做，浏览器将在 run() 完成时自动创建和关闭。

​
运行代理

代理使用异步 run() 方法执行:
  • max_steps (默认: 100)
    代理在执行期间可以采取的最大步骤数。这可以防止无限循环并帮助控制执行时间。

​
代理历史

该方法返回一个包含完整执行历史的 AgentHistoryList 对象。这个历史对调试、分析和创建可重现的脚本非常有价值。 
# 访问历史的示例
history = await agent.run()

# 访问(一些)有用的信息
history.urls()              # 访问过的 URL 列表
history.screenshots()       # 截图路径列表
history.action_names()      # 执行的动作名称
history.extracted_content() # 执行期间提取的内容
history.errors()           # 发生的任何错误
history.model_actions()     # 所有带参数的动作
AgentHistoryList 提供了许多帮助方法来分析执行:
  • final_result(): 获取最终提取的内容
  • is_done(): 检查代理是否成功完成
  • has_errors(): 检查是否发生任何错误
  • model_thoughts(): 获取代理的推理过程
  • action_results(): 获取所有动作的结果
有关帮助方法的完整列表和详细的历史分析功能，请参考 AgentHistoryList 源代码。

​
无 LLM 运行初始动作

使用此示例可以在没有 LLM 的情况下运行初始动作。 将动作指定为字典，其中键是动作名称，值是动作参数。你可以在 Controller 源代码中找到我们所有的动作。 
initial_actions = [
    {'open_tab': {'url': 'https://www.google.com'}},
    {'open_tab': {'url': 'https://en.wikipedia.org/wiki/Randomness'}},
    {'scroll_down': {'amount': 1000}},
]
agent = Agent(
    task='页面上显示了哪些理论?',
    initial_actions=initial_actions,
    llm=llm,
)

​
使用规划模型运行

你可以配置代理使用单独的规划模型进行高级任务规划: 
from langchain_openai import ChatOpenAI

# 初始化模型
llm = ChatOpenAI(model='gpt-4o')
planner_llm = ChatOpenAI(model='o3-mini')

agent = Agent(
    task="你的任务",
    llm=llm,
    planner_llm=planner_llm,           # 单独的规划模型
    use_vision_for_planner=False,      # 为规划器禁用视觉
    planner_interval=4                 # 每 4 步规划一次
)

​
规划器参数

  • planner_llm: 用于高级任务规划的 LangChain 聊天模型实例。可以是比主 LLM 更小/更便宜的模型。
  • use_vision_for_planner: 为规划器模型启用/禁用视觉能力。默认为 True。
  • planner_interval: 规划阶段之间的步骤数。默认为 1。
使用单独的规划模型可以帮助:
  • 通过使用较小的模型进行高级规划来降低成本
  • 改进任务分解和战略思维
  • 更好地处理复杂的多步骤任务
规划器模型是可选的。如果未指定，代理将不使用规划器模型。