Browser Agent：让多个 AI Agent 共用同一个真实 Chrome

一个本地共享浏览器运行时：统一管理真实 Chrome、固定 Profile、CDP 和自动恢复，让 Skill 与 AI Agent 只负责页面业务。

Browser Agent 是一个本地共享浏览器运行时。它统一管理真实 Google Chrome、固定 Profile、CDP 端口和浏览器生命周期，让多个 Skill、Python 项目与 AI Agent 连接同一个浏览器环境。

它不负责具体网站的采集逻辑，只负责保证浏览器可用。

项目定位

它解决什么问题

没有统一浏览器运行时，每个自动化项目通常会重复处理同一批问题：

• 自己选择 Chrome 或 Chromium。
• 自己维护 Profile 路径。
• 自己分配远程调试端口。
• 浏览器关闭后连接直接报错。
• Profile 被旧进程占用时无法启动。
• 多个项目分别登录同一批网站。
• Agent 任务结束时误关共享浏览器。

Browser Agent 把这些通用能力集中到一个项目里。

整体架构

flowchart LR
  A[Skill / Python / AI Agent] --> B[browser-agent ensure]
  B --> C{CDP 是否正常}
  C -->|正常| D[复用现有 Chrome]
  C -->|异常| E[清理异常进程与运行锁]
  E --> F[启动真实 Google Chrome]
  F --> G[固定 Profile + 固定 CDP]
  D --> H[Playwright connect_over_cdp]
  G --> H
  H --> I[创建独立 Page]
  I --> J[执行网站业务逻辑]

固定约定如下：

控制入口：~/browser-agent/browser-agent
共享 Profile：~/browser-agent/chrome-profile
CDP：http://127.0.0.1:19312

ensure 如何工作

外部项目不需要判断浏览器当前处于什么状态，只需要执行：

~/browser-agent/browser-agent ensure

外部项目怎么接入

Python 项目只需要先调用 ensure，再通过 Playwright 连接 CDP：

import subprocess
from pathlib import Path

from playwright.sync_api import sync_playwright


browser_agent = Path.home() / "browser-agent" / "browser-agent"

subprocess.run(
    [str(browser_agent), "ensure"],
    check=True,
)

with sync_playwright() as playwright:
    browser = playwright.chromium.connect_over_cdp(
        "http://127.0.0.1:19312"
    )

    context = browser.contexts[0]
    page = context.new_page()

    try:
        page.goto("https://example.com")
        # 当前项目的页面业务逻辑
    finally:
        page.close()

业务项目不再负责以下内容：

Chrome 可执行文件路径
Profile 创建与迁移
远程调试端口分配
Chrome 进程启动与结束
CDP 健康检查
异常进程恢复

使用价值

它尤其适合以下场景：

• 需要登录状态的网页采集。
• 多个 Skill 操作相同网站。
• 本地 Agent 调试网页结构和选择器。
• 定时任务需要在 Chrome 关闭后自动恢复。
• 不希望每个项目创建临时 Profile。

使用边界

Browser Agent 是单机共享运行时，不是远程浏览器集群，也不是并发调度平台。

需要遵守以下边界：

1. 每个任务创建自己的 page，任务结束只关闭该页面。
2. 不调用 context.close() 或 browser.close()，避免影响其他任务。
3. 默认不要让多个 Agent 同时操作同一个页面。
4. 验证码、扫码和账号安全验证需要人工处理。
5. Profile 包含登录信息，不能提交到 Git 仓库。

项目仓库：apexcheng/browser-agent