BrowserUse-无影 Agent 开发套件 AgentBay(AgentBay)-阿里云帮助中心

什么是 AgentBay AIBrowser

Agentbay AIBrowser 是一个可扩展的托管平台，用于大规模运行无头/有头浏览器。提供基础设施进行创建和管理会话、初始化浏览器实例，并按需分配底层硬件资源。专为网页自动化场景设计，如表单填写、模拟用户操作，以及在现代动态网站上编排复杂的多步骤任务。

Agentbay AIBrowser API 提供了简洁的接口来控制浏览器，以及实用的工具来创建并管理会话，通过先进的 AI 能力来执行自然语言描述的任务。

主要特点

自动化框架兼容性：通过 CDP 高度兼容 Playwright 和 Puppeteer。
安全可扩展的基础架构：托管式会话、隔离环境和弹性资源分配。
可观测性：会话回放、会话检查器和实时模式，支持实时调试。
高级能力：上下文管理、IP 代理和隐身/指纹选项。
AI 驱动的 PageUseAgent：通过自然语言执行复杂 Web 工作流任务。
丰富的API接口：提供简洁的会话管理、浏览器生命周期控制和代理操作接口。

快速入门（Python）

以下是一个最小化的可运行示例，展示了如何通过 AgentBay Python SDK 初始化浏览器并使用 Playwright 通过 CDP 进行驱动。示例代码将完成以下操作：

通过使用的 API 密钥构建 AgentBay 客户端进行身份验证，构建可信通道。
通过创建带有浏览器启用镜像的会话来配置一个新的执行环境，确保所需的运行时可用。
使用 BrowserOption() 初始化会话的浏览器，启动一个准备自动化的远程浏览器实例。
通过 get_endpoint_url() 获取 CDP 终端 URL，并使用 Playwright 的 connect_over_cdp 进行连接，将本地代码桥接到远程浏览器。
建立活动连接后，代码将打开新页面并导航至网站，可以像本地浏览器一样检查或操作 DOM。
当所有工作完成后，删除会话以释放已分配的资源。

先决条件：

设置 API 密钥：export AGENTBAY_API_KEY=your_api_key
安装依赖项：pip install wuying-agentbay-sdk playwright
安装 Playwright 浏览器：python -m playwright install chromium

import os
import asyncio
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams
from agentbay.browser.browser import BrowserOption
from playwright.async_api import async_playwright

async def main():
    api_key = os.getenv("AGENTBAY_API_KEY")
    if not api_key:
        raise RuntimeError("AGENTBAY_API_KEY environment variable not set")

    agent_bay = AgentBay(api_key=api_key)

    # Create a session (use an image with browser preinstalled)
    params = CreateSessionParams(image_id="browser_latest")
    session_result = agent_bay.create(params)
    if not session_result.success:
        raise RuntimeError(f"Failed to create session: {session_result.error_message}")

    session = session_result.session

    # Initialize browser (supports stealth, proxy, fingerprint, etc. via BrowserOption)
    ok = await session.browser.initialize_async(BrowserOption())
    if not ok:
        raise RuntimeError("Browser initialization failed")

    endpoint_url = session.browser.get_endpoint_url()

    # Connect Playwright over CDP and automate
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(endpoint_url)
        page = await browser.new_page()
        await page.goto("https://www.aliyun.com")
        print("Title:", await page.title())
        await browser.close()

    session.delete()

if __name__ == "__main__":
    asyncio.run(main())

关键的浏览器 API：

Browser.initialize(option: BrowserOption) -> bool / initialize_async(...)：为会话启动浏览器实例。
Browser.get_endpoint_url() -> str：返回 CDP WebSocket 终端；与 Playwright connect_over_cdp 一起使用。
Browser.is_initialized() -> bool：检查浏览器是否就绪。

基本配置

有时网页需要不同的伪装和舞台。通过自定义浏览器的身份标识和窗口尺寸，可以引导网站展现出针对特定设备类别或受众群体的体验。以下示例将设置自定义用户代理和精确的窗口尺寸，将完成以下操作：

进行身份验证并创建一个托管浏览器的会话。
模拟一个常见的 macOS + Chrome 浏览器的 User-Agent，用于伪装浏览器身份。
使用 initialize_async 启动浏览器，请求 CDP 终端，并通过 Playwright 建立连接。
访问网站并验证User-Agent和窗口大小是否被正确设置。

import os
import asyncio
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams
from agentbay.browser.browser import BrowserOption, BrowserViewport
from playwright.async_api import async_playwright

CUSTOM_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"

async def main():
    agent_bay = AgentBay(api_key=os.environ["AGENTBAY_API_KEY"])  # first, authenticate

    params = CreateSessionParams(image_id="browser_latest")       # then, provision a browser-ready session
    result = agent_bay.create(params)
    if not result.success:
        raise RuntimeError(result.error_message)

    session = result.session

    # after that, define how the browser should look and feel
    option = BrowserOption(
        user_agent=CUSTOM_UA,                    # present ourselves with a custom identity
        viewport=BrowserViewport(width=1366, height=768),  # and stand on a stage sized like a common laptop
    )

    ok = await session.browser.initialize_async(option)
    if not ok:
        raise RuntimeError("Browser initialization failed")

    endpoint_url = session.browser.get_endpoint_url()      # now, discover the CDP doorway

    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(endpoint_url)  # step through and take control
        page = await browser.new_page()

        await page.goto("https://www.whatismybrowser.com/detect/what-is-my-user-agent")
        # verify our new voice and our new stage
        ua = await page.evaluate("navigator.userAgent")
        w = await page.evaluate("window.innerWidth")
        h = await page.evaluate("window.innerHeight")
        print("Effective UA:", ua)
        print("Viewport:", w, "x", h)

        await browser.close()

    session.delete()  # finally, bow out and free the stage

if __name__ == "__main__":
    asyncio.run(main())

使用 PageUseAgent【Beta】

PageUseAgent 使用户能够使用自然语言与浏览器对话，并驱使浏览器执行用户意图。PageUseAgent调用依赖大语言模型能力，将产生token消耗，按照后付费规则产生费用，Beta版试用期间免费试用。

以下示例将在 Google 搜索一本书，将完成以下操作：

创建并初始化一个浏览器会话，并告知 Agent 需要做什么。
输入查询内容，代理会将意图转化为页面操作。
浏览器自动在搜索框输入查询内容并跳转至结果页面。
关闭浏览器并释放会话。

import os
import asyncio
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams
from agentbay.browser.browser import BrowserOption
from agentbay.browser.browser_agent import ActOptions
from playwright.async_api import async_playwright

BOOK_QUERY = "The Pragmatic Programmer"

async def main():
    agent_bay = AgentBay(api_key=os.environ["AGENTBAY_API_KEY"])  # authenticate

    params = CreateSessionParams(image_id="browser_latest")       # provision session with browser image
    result = agent_bay.create(params)
    if not result.success:
        raise RuntimeError(result.error_message)
    session = result.session

    # initialize the remote browser
    if not await session.browser.initialize_async(BrowserOption()):
        raise RuntimeError("Browser initialization failed")

    endpoint_url = session.browser.get_endpoint_url()

    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(endpoint_url)
        page = await browser.new_page()

        # step onto the stage
        await page.goto("https://www.google.com")

        # ask the agent to act: type the book name into the search box
        act_result = await session.browser.agent.act_async(ActOptions(
            action=f"Type '{BOOK_QUERY}' into the search box and submit",
        ), page)
        print("act_result:", act_result.success, act_result.message)

        # let the agent open the first result
        open_first = await session.browser.agent.act_async(ActOptions(
            action="Click the first result in the search results",
        ), page)
        print("open_first:", open_first.success, open_first.message)

        # pause briefly to observe
        await page.wait_for_timeout(5000)
        await browser.close()

    session.delete()

if __name__ == "__main__":
    asyncio.run(main())

关于PageUseAgent.act：

variables插值动态值，实现可复用的提示。
通过对底层获取其 context_id 和 page_id 在活动 Playwright 页面上操作。
返回结构化的 ActResult，包含 success和message，便于日志记录和恢复流程。

限制

PageUseAgent不包括长期规划器，不会自行编排多步骤计划。依赖于调用者（或更高级别的代理）将项目分解为步骤，并为每个步骤调用 act 或其他 PageUseAgent 方法。

PageUseAgent优势在于精确、原子的网页操作（点击、填充、滚动等）并快速一致地执行。

PageUseAgent优先考虑每一步的吞吐量和准确性，并将复杂的任务规划和分支逻辑留给外部控制器。