agent-browser

Agent Browser

看看你的 Agent 看到了什么。

为 AI Agent 提供的可自托管 Chrome。
你的 Agent 操控一个真实的浏览器会话——你可以观看操作过程，并随时介入。

快速开始 · API · MCP · 安全模型 · Node 客户端 · Python 客户端 · 参与贡献 · 更新日志

_{这是一段 18 秒的录制演示。Agent 登录后遇到无法回答的 2FA 提示，于是停下。人类在显示的会话中输入代码，然后 Agent 继续操作。
录制来源、校验和以及可独立验证的限制均有记录。  ·  录制方式}

为什么要做这个项目

大多数面向 Agent 的浏览器工具都会把一个你看不到的浏览器交给模型。页面读错了，或是卡在登录环节时，你能看到的只有操作记录和猜测。

Agent Browser 运行一个有头 Chrome 会话。你的 Agent 通过小型 JSON API 操控它，而该同一个会话的实时画面就在你面前。Agent 卡住时，你可以在它正在使用的窗口中接管操作，然后再交还给它。

启动运行时：

docker compose up --build

然后按你喜欢的方式访问：

npm install aether-browser    # TypeScript
pip install aether-browser    # Python
claude mcp add agent-browser -- npx -y aether-browser mcp    # any MCP client

快速开始

在 Linux 上的 Docker Engine 中，只需运行一条命令，并使用 Compose v2。它会从源代码检出目录构建并启动 Xvfb、x11vnc、noVNC 和 API——这套服务栈负责管理一个有头 Chrome 会话。 两个面向用户的监听器都绑定到数字回环地址。

docker compose up --build

健康检查响应后，打开实时画面 127.0.0.1:6080/vnc.html，并在另一个终端中检查 API：

curl -fsS http://127.0.0.1:8092/browser/health | jq .

按 Ctrl+C 即可停止。

首次构建需要几分钟。 它会安装哈希锁定的 Python 环境，然后使用 Patchright 安装当前的 Google Chrome Stable 软件包。每个获准的镜像都会记录确切的浏览器版本，因此稍后使用相同源代码重新构建时，可能会获取更新的 Stable 版本。

特意使用 Linux 主机网络。 这样可确保未经身份验证的 v0.x noVNC 界面仅通过数字回环地址开放。Docker Desktop 和远程主机部署不在本快速开始的范围内。

四次调用即可使用 API

运行时正常运行且已安装 curl 和 jq。按设计，本地 loopback 无需 bearer token — 更改部署方式前，请阅读权限约定。

# Open the session. This is the browser you are about to watch.
SESSION_ID="$(curl -fsS -X POST http://127.0.0.1:8092/browser/session/create \
  -H 'Content-Type: application/json' \
  -d '{"api_version":"v1"}' | jq -er '.session_id')"

# Go somewhere. The page changes in the live view as this runs.
curl -fsS -X POST http://127.0.0.1:8092/browser/navigate \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"v1\",\"session_id\":\"${SESSION_ID}\",\"url\":\"https://example.com\"}" \
  | jq '{status, final_url, title, readable_text}'

# Read it back as structure, not pixels.
curl -fsS -X POST http://127.0.0.1:8092/browser/snapshot \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"v1\",\"session_id\":\"${SESSION_ID}\"}" \
  | jq '{status, url, title, sequence, vision_steps_remaining}'

# Give the browser back.
curl -fsS -X POST http://127.0.0.1:8092/browser/session/end \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"v1\",\"session_id\":\"${SESSION_ID}\"}" | jq .

执行的操作：session/create 启动了一个有头 Chrome 会话，并返回其 UUID 和本地查看 URL。navigate 验证目标地址、固定允许的地址，并在共享显示屏上切换页面。snapshot 返回有界文本、无障碍状态、视口元数据、计数器，以及该页面的 PNG。API 和人工视图从未创建相互竞争的浏览器 — 它们共用同一个受控会话。

同样的流程也提供于 examples/curl.sh。

在 MCP 客户端中使用

任何 MCP 客户端 — Claude Code、Claude Desktop、Cursor、Windsurf — 都能在你观看时驱动会话，并在遇到问题时让你接管。

claude mcp add agent-browser -- npx -y aether-browser mcp

已经有 Python 客户端？aether-browser mcp 提供相同的九种工具。

{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["-y", "aether-browser", "mcp"]
    }
  }
}

九种工具 — browser_open · browser_navigate · browser_read · browser_click · browser_type · browser_press · browser_scroll · browser_status · browser_close

browser_open 会返回实时查看 URL，之后的每条响应也都会重复该 URL，让你始终知道该查看哪里。连接时，服务会提示模型在遇到登录、付款或 2FA 提示词时停止操作并请求接管，而不是猜测 — 录制视频中展示的就是这一流程。

设置和限制：docs/MCP.md。

Node 和 TypeScript 客户端

通过 Node 使用相同的 API，并提供类型支持和不会忘记的清理操作：

npm install aether-browser

import { AgentBrowser, withSession } from 'aether-browser'

const browser = new AgentBrowser({ controllerToken: process.env.AGENT_BROWSER_CONTROLLER_TOKEN })

await withSession(browser, async (session) => {
  const page = await session.navigate('https://example.com')
  await session.click({ selector: '#login' })
  await session.type({ selector: '#user', text: 'ada' })
  console.log(page.title, session.viewUrl)
})

withSession 始终会结束会话，包括回调抛出异常时，因此崩溃不会导致唯一的会话槽位一直被占用。没有运行时依赖，可在任何能够访问服务的环境中运行。它还附带一个小型 CLI：首次运行前，npx aether-browser doctor 会告诉你缺少哪些内容；up 则会在 Linux 主机上构建并启动运行时。

请参阅 clients/node/README.md。

Python 客户端

相同的客户端、相同的名称、相同的命令，并与 npm 包按版本同步发布：

pip install aether-browser

import os

from aether_browser import AgentBrowser, session

browser = AgentBrowser(controller_token=os.environ["AGENT_BROWSER_CONTROLLER_TOKEN"])

with session(browser) as live:
    page = live.navigate("https://example.com")
    live.click(selector="#login")
    live.type("ada", selector="#user")
    print(page["title"], live.view_url)

session 上下文管理器始终会结束会话，包括代码块引发异常时。没有运行时依赖 — 传输使用标准库中的 urllib — 提供类型提示，可在 Python 3.10 或更高版本中运行，适用于任何能够访问服务的环境。CLI 与 npm 包相同： aether-browser doctor、up、status、open、down。

请参阅 clients/python/README.md。

可选的 Jev 网页决策（Python）

Python 客户端提供可选启用的 aether_browser.jev 层，用于 Jev → 你选定的模型。 Jev 会读取调用方选定的文本摘录，并在最多三个由调用方批准的 URL、交接或人工接管之间做出选择。浏览器只会导航到调用方提供的 URL，且仍会执行常规目标检查。发生交接时，你的回调会收到当前页面证据，以及 Jev 的请求 ID、令牌数量和费用；你的应用会调用所选的推理模型来撰写内容、进行分析或继续浏览。Jev 返回的是决策，而非文本或视觉判断，因此截图和复杂的页面交互应交由所选模型或正在观看实时浏览器的人员处理。

import os

from aether_browser import AgentBrowser, session
from aether_browser.jev import HumanTakeover, JevWebAgent, NavigationOption, OpenRouterJev

browser = AgentBrowser(controller_token=os.environ["AGENT_BROWSER_CONTROLLER_TOKEN"])
with session(browser) as live:
    first_page = live.navigate("https://example.com")
    result = JevWebAgent(OpenRouterJev(os.environ["OPENROUTER_API_KEY"])).run(
        live,
        goal="Read the site's documentation",
        initial_page=first_page,
        options_for=lambda page: (
            [NavigationOption("https://example.com/docs", "Official documentation")]
            if page["final_url"] == "https://example.com/"
            else []
        ),
        excerpt_for=lambda page: page["readable_text"][:6000],
        selected_model=lambda handoff: your_model(handoff),  # Supply your own model callback.
    )
    if isinstance(result, HumanTakeover):
        print("Take control at", result.view_url)
        input("Press Enter when the human is done to close this session: ")
    else:
        print(result)

示例中的 your_model 是应用自定义的函数，并非此软件包的一部分。excerpt_for 回调会明确选择要发送到 OpenRouter 的文本，options_for 则会明确选择候选 URL。除非你的应用有意将私有页面内容或签名 URL 发送给该服务提供商，否则切勿返回这些内容。OpenRouter 密钥会留在调用进程中；浏览器服务端不会存储该密钥。只有调用此可选层时才会发送 Jev 请求。如果 Jev 失败或返回无效决策，所选模型回调会收到 reason="jev_unavailable" 的交接，浏览器不会采取其他操作。对于已识别的身份验证页面或付款页面，Jev 收到其文本之前会先提示人工接管。会话仍由你的代码持有；人工接管期间请保持会话开启。完整的契约和限制请参阅 docs/JEV.md。

有何不同

• 一个会话，两个参与者。 Agent 通过 JSON 执行操作。你可以观看同一画面，并在需要时接管控制权。
• 先看结构，再看像素。 在消耗视觉步骤处理截图之前，先返回可读文本和受限的无障碍树。
• 精简的控制界面。 v0.x API 提供明确的浏览器操作——不是 Shell，不是任意 JavaScript，也不是原始 DevTools。
• 与模型无关且可自托管。 使用你现有的框架，并将浏览器运行在你控制的硬件上。

当前功能

请求和响应格式、限制及稳定的错误代码：docs/API.md。

架构

flowchart LR
    Agent["Agent client"] -->|bounded JSON API| API["FastAPI"]
    API --> Guard["authority + navigation policy"]
    Guard --> Session["single-session manager"]
    Session --> Chrome["Patchright + headed Google Chrome"]
    Chrome --> State["text · accessibility · PNG"]
    State --> Agent
    Chrome --> Display["shared Xvfb display"]
    Display -->|loopback noVNC| Human["Human observer / takeover"]

会话管理器负责页面、浏览器上下文、临时配置文件、计时器、计数器和清理工作。API 和实时视图是访问此共享资源的不同接口，而非两条独立的自动化路径。请参阅 docs/ARCHITECTURE.md。

重要

Agent Browser v0.2.3 采用源码优先和可自托管模式。 它不是托管服务；v0.x 的 noVNC 界面未经身份验证，仅供在你控制的机器上通过数字环回地址访问。 除非另有文档说明已获得再分发授权，否则不会分发包含 Chrome 的镜像、镜像 tar 包或公共层缓存。

安全边界

• API 和 noVNC 默认监听数字形式的回环地址；在 v0.x 系列中，noVNC 始终仅限回环访问。
• 远程 API 客户端需要单独运行在同一主机上的 HTTPS 反向代理、精确匹配的受信任回环对端、严格的 Host 验证，以及彼此独立的强观察者令牌和控制器令牌。
• 目标验证会拒绝凭据、不受支持的协议、被阻止的地址类别、不安全的重定向和 DNS 重绑定。浏览器的出站流量会通过专属的 TCP 代理固定路由。
• 禁用非代理 WebRTC UDP，避免其绕过 TCP 出站边界。
• 输入、输出、交互、超时、生命周期和截图预算均设有上限。
• 会话结束、过期、启动失败、应用程序关闭和进程故障时，都会执行清理。

docs/SECURITY.md 详细说明了信任假设和剩余风险。 请通过 SECURITY.md 私下报告漏洞 — 请勿公开提交安全问题。

源码恢复与排除项

源码恢复规则是复用通用浏览器行为，而非私有领域代码。 可以改编经授权参考资料中的生命周期、结构化状态、交互和清理模式；ATS／交易集成、经纪商或账户选择器、下单操作、机密信息和凭据注入均不属于公共核心。来源追踪状态记录在 docs/SOURCE-RECOVERY.md 中。

不支持的功能

• 不提供托管式云服务、云控制平面，也不宣称可用于生产环境的远程托管。
• 不捆绑大模型或默认模型调用、账户系统、仪表板、凭据库或凭据注入。
• 不绕过 CAPTCHA，不保证规避检测，也不提供隐身功能或代理轮换。
• 不提供任意 JavaScript、Shell、文件系统、上传、剪贴板、下载或原始 CDP API。
• 不提供多会话池、ATS 集成、交易集成或经纪业务行为。

路线图

已发布。 两个客户端及其 CLI 均以 aether-browser 名称发布，并且版本号保持一致： 来自 clients/node 的版本发布在 npm 上，来自 clients/python 的版本发布在 PyPI 上。自 0.2.0 起，两者也都提供 MCP 服务。

目前开放两项工作，各有一个议题，也都适合作为首次贡献：

1. 多会话工作池 — 明确隔离和容量语义。
2. 会话跟踪与录制导出 — 并提供清晰的隐私控制。

这些是候选功能，并非已发布功能。

参与贡献

请从 CONTRIBUTING.md、行为准则 和当前的 API 合约 开始。我们非常欢迎小规模、经过充分测试且保持权限边界精简的更改 — 上述两项路线图议题是最好的起点。安全报告请通过 SECURITY.md 中的私密流程提交，切勿公开提交议题。

许可证与第三方声明

Aether 拥有的源代码依据 Apache License 2.0 授权。Google Chrome 依据 Google 的 Chrome 条款 单独授权，不受 Aether 的 Apache 许可证约束；依赖项、系统软件包、字体和 Web 资源也各自遵循相应条款。请参阅 THIRD_PARTY_NOTICES.md。 Aether 与 Google 无关联，也未获 Google 背书。v0.x 的分发目标是可在本地构建的源代码；本仓库不分发包含预构建 Chrome 的镜像。

_{Agent Browser · 查看你的 Agent 所看到的内容。}