AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 无影 Agent 开发套件 AgentBay SDK接入 实践教程 浏览器持久化

浏览器持久化

更新时间：
产品详情
我的收藏

浏览器持久化是无影 AgentBay SDK 的核心功能，可实现跨多个会话的持久浏览器状态管理。允许在会话之间维护 Cookie、缓存、本地存储和其他浏览器数据，显著减少反机器人检测的干扰并加快网页加载速度。

概述

浏览器持久化代表一个持久的浏览器环境以存储浏览器状态，包括：

  • Cookie。

  • 缓存。

  • 本地存储。

  • 会话存储。

  • 浏览器首选项。

  • 已安装的扩展程序（当与扩展管理一起使用时）。

优势

  1. 减少反机器人检测干扰：通过维护浏览器状态，网站会将会话识别为回访用户而不是新访客。

  2. 更快的页面加载速度：缓存的资源和 Cookie 减少页面加载时间。

  3. 会话连续性：在多个会话中继续之前的操作。

  4. 一致的用户体验：保持用户首选项和设置。

Python 示例

基本用法

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams, BrowserContext

# 初始化 AgentBay 客户端
agent_bay = AgentBay(api_key="your_api_key")

# 创建或获取持久化上下文
context_result = agent_bay.context.get("my-browser-context", create=True)
context = context_result.context

# 使用持久化创建浏览器会话
browser_context = BrowserContext(
    context_id=context.id,
    auto_upload=True
)

session_params = CreateSessionParams(
    image_id="browser-image-id",
    browser_context=browser_context
)

session_result = agent_bay.create(session_params)
session = session_result.session

Cookie 持久化

import time
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams, BrowserContext
from agentbay.browser.browser import BrowserOption
from playwright.sync_api import sync_playwright

# 初始化 AgentBay
agent_bay = AgentBay(api_key="your_api_key")

# 创建持久化上下文
context_result = agent_bay.context.get("cookie-demo-context", create=True)
context = context_result.context

# 第一个会话 - 设置 cookie
browser_context = BrowserContext(
    context_id=context.id,
    auto_upload=True
)

params = CreateSessionParams(
    image_id="browser-image-id",
    browser_context=browser_context
)

session1 = agent_bay.create(params).session

# 在第一个会话中设置 cookie
session1.browser.initialize(BrowserOption())
endpoint_url = session1.browser.get_endpoint_url()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(endpoint_url)
    context_p = browser.contexts[0] if browser.contexts else browser.new_context()
    page = context_p.new_page()
    
    # 导航并设置 cookie
    page.goto("https://example.com")
    context_p.add_cookies([
        {
            "name": "session_cookie",
            "value": "session_value",
            "domain": "example.com",
            "path": "/",
        }
    ])
    
    browser.close()

# 删除带有上下文同步的第一个会话
agent_bay.delete(session1, sync_context=True)

# 第二个会话 - 验证 cookie 是否持久化
session2 = agent_bay.create(params).session

# 在第二个会话中检查 cookie
session2.browser.initialize(BrowserOption())
endpoint_url2 = session2.browser.get_endpoint_url()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(endpoint_url2)
    context_p = browser.contexts[0] if browser.contexts else browser.new_context()
    
    # 验证 cookie 是否持久化
    cookies = context_p.cookies()
    print(f"持久化的 cookie: {cookies}")
    
    browser.close()

TypeScript 示例

基本用法

import { AgentBay, CreateSessionParams, BrowserContext } from 'wuying-agentbay-sdk';

// 初始化 AgentBay 客户端
const agentBay = new AgentBay({ apiKey: "your_api_key" });

// 创建或获取持久化上下文
const contextResult = await agentBay.context.get("my-browser-context", true);
const context = contextResult.context;

# 创建带持久化的浏览器会话
const browserContext: BrowserContext = {
    contextId: context.id,
    autoUpload: true
};

const params = new CreateSessionParams()
    .withImageId("browser-image-id")
    .withBrowserContext(browserContext);

const sessionResult = await agentBay.create(params);
const session = sessionResult.session;

Cookie 持久化

import { AgentBay, CreateSessionParams, BrowserContext, BrowserOption } from 'wuying-agentbay-sdk';
import { chromium } from 'playwright';

# 初始化 AgentBay
const agentBay = new AgentBay({ apiKey: "your_api_key" });

# 创建持久化上下文
const contextResult = await agentBay.context.get("cookie-demo-context", true);
const context = contextResult.context;

# 第一个会话 - 设置 cookie
const browserContext: BrowserContext = {
    contextId: context.id,
    autoUpload: true
};

const params = new CreateSessionParams()
    .withImageId("browser-image-id")
    .withBrowserContext(browserContext);

const session1 = (await agentBay.create(params)).session;

# 在第一个会话中设置 cookie
await session1.browser.initializeAsync(new BrowserOption());
const endpointUrl = session1.browser.getEndpointUrl();

const browser = await chromium.connectOverCDP(endpointUrl);
const contextP = browser.contexts()[0] || await browser.newContext();
const page = await contextP.newPage();

# 导航并设置 cookie
await page.goto("https://example.com");
await contextP.addCookies([
    {
        name: "session_cookie",
        value: "session_value",
        domain: "example.com",
        path: "/",
    }
]);

await browser.close();

# 删除带有上下文同步的第一个会话
await agentBay.delete(session1, true);

# 第二个会话 - 验证 cookie 是否持久化
const session2 = (await agentBay.create(params)).session;

# 在第二个会话中检查 cookie
await session2.browser.initializeAsync(new BrowserOption());
const endpointUrl2 = session2.browser.getEndpointUrl();

const browser2 = await chromium.connectOverCDP(endpointUrl2);
const contextP2 = browser2.contexts()[0] || await browser2.newContext();

# 验证 cookie 是否持久化
const cookies = await contextP2.cookies();
console.log(`持久化的 cookie: ${JSON.stringify(cookies)}`);

await browser2.close();

推荐用法

  1. 使用描述性的上下文名称：根据用途命名上下文（例如：ecommerce-scraping、social-media-automation）。

  2. 启用自动上传：设置 auto_upload=True 以在会话结束时自动同步浏览器数据。

  3. 清理资源：完成操作后删除会话以释放云资源。

  4. 优雅地处理错误：为上下文操作实现适当的错误处理。

  5. 重用上下文：在多个会话中重用相同的上下文以保持连续性。

高级功能

上下文同步策略

from agentbay.context_sync import SyncPolicy

# 创建自定义同步策略
policy = SyncPolicy(
    upload=True,
    extract=True,
    white_list=["/cookies.json", "/storage/"],
    black_list=["/cache/large_files/"]
)

# 使用上下文同步
context_sync = ContextSync.new(
    context_id=context.id,
    path="/browser-data",
    policy=policy
)

多个上下文

# 为不同网站创建单独的上下文
ecommerce_context = agent_bay.context.get("ecommerce-site", create=True).context
social_context = agent_bay.context.get("social-media", create=True).context

# 对不同会话使用不同的上下文
ecommerce_session_params = CreateSessionParams(
    browser_context=BrowserContext(ecommerce_context.id, True)
)

social_session_params = CreateSessionParams(
    browser_context=BrowserContext(social_context.id, True)
)

错误处理

try:
    context_result = agent_bay.context.get("my-context", create=True)
    if not context_result.success:
        print(f"创建上下文失败: {context_result.error_message}")
        
    session_result = agent_bay.create(session_params)
    if not session_result.success:
        print(f"创建会话失败: {session_result.error_message}")
        
except Exception as e:
    print(f"发生错误: {e}")
上一篇：自动化测试下一篇：方法参考