- 人工智能
- AI Agent
- 浏览器控制
- GUI 自动化
- MCP 服务
【免费下载链接】browser-use
Agents that use the browser.
把完整的网页任务（搜索、填表、数据抽取、登录、点击）整体委托给 browser-use，是构建「编排器 + 浏览器代理」架构时最直接的一种集成模式：任务进去、结果出来，browser-use 自主完成全部浏览行为，编排器全程不触碰浏览器。这篇指南以 skills/cloud/references/guides/subagent.md 为骨架，结合当前仓库的 Cloud SDK、CLI、MCP 服务与测试源码，完整讲解该模式的适用场景、五种主流集成方式（CLI、Python SDK、TypeScript SDK、MCP、HTTP REST）以及结构化输出、错误处理、成本控制与资源清理等横向工程问题。读完你将能够在 LangChain、CrewAI、Vercel AI SDK、Claude Desktop、n8n 等任意编排宿主中把 browser-use 接成可复用的「网页能力即服务」。
何时使用 Subagent 模式
你的系统里有一个编排器（orchestrator）——某个 Agent、流水线或工作流引擎，负责协调多种能力。当它判断「我需要网页上的数据」或「我需要与某个网站交互」时，把任务委托给 browser-use，由后者自主完成导航、点击、抽取并返回结果。编排器不直接操作浏览器，也看不到中间过程。
适合使用 subagent 模式的情况：
- 你想要一个黑盒：任务进去 → 结果出来；
- 网页任务自包含（搜索、抽取、填表），不需要对每一步动作进行干预；
- 你不需要 action-by-action 的细粒度控制。
应改用 tools integration（工具集成）的情况：
- 你的 Agent 需要独立做出单个浏览器决策（先点这个、再检查那个）；
- 你希望 Agent 自己的推理循环来驱动浏览器，而非整体移交。
两种模式的分界线非常清晰：subagent 模式把「怎么浏览」交给 browser-use，工具集成模式把「怎么浏览」留给你自己的 Agent。仓库中的 skills/cloud/SKILL.md 也将这两种集成分别列为独立指南（references/guides/subagent.md与references/guides/tools-integration.md），二者是互补关系而非替代关系。
选择你的集成方式
先根据你的 Agent 形态选定最合适的接入路径，这是本指南的核心决策表：
| 你的 Agent 类型 | 推荐方案 |
|---|---|
| 沙箱/VM 中的 CLI 编码 Agent（Claude Code、Codex、OpenCode、Cline、Windsurf、Cursor bg、Hermes、OpenClaw） | CLI 云透传（Shell 命令） |
| Python 框架（LangChain、CrewAI、AutoGen、PydanticAI 或自研） | Python Agent 封装（Cloud SDK） |
| TypeScript/JS（Vercel AI SDK、LangChain.js 或自研） | Cloud SDK |
| MCP 客户端（Claude Desktop、启用 MCP 的 Cursor） | MCP browser_task 工具 |
| 工作流引擎（n8n、Make、Zapier、Temporal）或任意 HTTP 客户端 | Cloud REST API |
选择依据很简单：有终端就选 CLI，是 Python 框架就选 Python SDK，是 TS 生态就选 TS SDK，是 MCP 客户端就选 MCP，其余一切走 REST。Cloud 版本统一使用X-Browser-Use-API-Key请求头认证（见 skills/cloud/SKILL.md），本地开源版本则无需 API Key。
Shell Command Agents（CLI）
适用对象：拥有终端访问权限的沙箱/VM 中的编码 Agent。
CLI 方案让 Agent 通过命令行把完整任务委托给云端执行，无需任何 Python 导入。文档给出的四步标准流程如下：
# 1. 设置 API Key（一次性） browser-use cloud login $BROWSER_USE_API_KEY # 2. 提交一个任务 browser-use cloud v2 POST /tasks '{"task": "Find the top HN post and return title and URL"}' # 返回: {"id": "<task-id>", "sessionId": "<session-id>"} # 3. 轮询直到完成（阻塞） browser-use cloud v2 poll <task-id> # 4. 获取结果 browser-use cloud v2 GET /tasks/<task-id> # 返回完整的 TaskView：output、steps、outputFiles其中BROWSER_USE_API_KEY应作为环境变量注入（保持服务端持有，绝不要写进提示词或客户端代码）。Cloud API 的基址与认证约定为：v2https://api.browser-use.com/api/v2/、v3https://api.browser-use.com/api/v3、v4https://api.browser-use.com/api/v4，请求头统一为X-Browser-Use-API-Key: <key>（见 skills/cloud/SKILL.md）。
需要结构化输出时，直接传 JSON Schema：
browser-use cloud v2 POST /tasks '{ "task": "Find the CEO of OpenAI", "structuredOutput": "{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"company\":{\"type\":\"string\"}},\"required\":[\"name\",\"company\"]}" }'补充说明（仓库现状）：当前仓库的 CLI（browser_use/cli.py）采用「stdin 管道 Python」模型——把 Python 代码通过 heredoc 管道输入执行，浏览器常驻后台 daemon。CLI 3.0 已移除旧的
open/state/click/eval/--json/--headed/--profile等子命令；旧cloud子命令的迁移提示是「用browser-use auth login认证，再start_remote_daemon("<name>")启动命名云浏览器」（见 browser_use/cli.py）。若你的集成目标是最新 CLI 形态，应以仓库 SKILL.md 的「CLI 管道 Python」用法为准。
Python Agents（Cloud SDK）
适用对象：LangChain、CrewAI、AutoGen、PydanticAI、Semantic Kernel 或自研 Python Agent。使用 Cloud SDK，无需本地浏览器。
from browser_use_sdk import AsyncBrowserUse from pydantic import BaseModel client = AsyncBrowserUse() # 简单用法 async def browse(task: str) -> str: result = await client.run(task) return result.output # 结构化输出 class SearchResult(BaseModel): title: str url: str async def browse_structured(task: str) -> SearchResult: result = await client.run(task, output_schema=SearchResult) return result.output # 返回 SearchResult 实例多步骤任务可通过keep_alive复用同一个云会话（session），从而保留登录态与页面上下文：
session = await client.sessions.create(proxy_country_code="us") await client.run("Log into site", session_id=str(session.id), keep_alive=True) result = await client.run("Extract data", session_id=str(session.id)) await client.sessions.stop(str(session.id))proxy_country_code="us"指定住宅代理出口国家（默认即美国住宅代理，默认开启防指纹、验证码处理、广告/Cookie 拦截与 Cloudflare 绕过等 stealth 能力，见 skills/cloud/references/features.md）。
关于 SDK 版本，skills/cloud/SKILL.md 给出了清晰对照：
- Python v2：
from browser_use_sdk import AsyncBrowserUse - Python v3：
from browser_use_sdk.v3 import AsyncBrowserUse - Python v4：
from browser_use_sdk.v4 import BrowserUse或AsyncBrowserUse
安装：uv pip install browser-use-sdk。若你的集成是新项目，推荐直接使用 v4 的runs资源（一个 run 即一次 Agent 回合，session 是被多次 run 共享的会话，workspace 是可跨会话复用的持久化文件系统），参考 skills/cloud/references/api-v4.md：
from browser_use_sdk.v4 import BrowserUse with BrowserUse() as client: created = client.runs.create( "Open https://example.com and return its title", max_cost_usd=1.00 ) run = client.runs.wait_for_completion(created.id) if run.status.value != "completed": raise RuntimeError(f"Run {run.id}: {run.status}") print(run.result)TypeScript/JS Agents
适用对象：Vercel AI SDK、LangChain.js 或自研 TypeScript Agent。
import { BrowserUse } from "browser-use-sdk"; import { z } from "zod"; const client = new BrowserUse(); // 简单用法 async function browse(task: string): Promise<string> { const result = await client.run(task); return result.output; } // 结构化输出（用 Zod schema 定义） const SearchResult = z.object({ title: z.string(), url: z.string(), }); async function browseStructured(task: string) { const result = await client.run(task, { schema: SearchResult }); return result.output; // { title: string, url: string } }多步骤 + 会话复用的写法（对应 Python 的keep_alive，TS 侧为keepAlive）：
const session = await client.sessions.create({ proxyCountryCode: "us" }); await client.run("Log into site", { sessionId: session.id, keepAlive: true }); const result = await client.run("Extract data", { sessionId: session.id }); await client.sessions.stop(session.id);TypeScript 的 v2/v3/v4 导入路径分别为browser-use-sdk、browser-use-sdk/v3、browser-use-sdk/v4（见 skills/cloud/SKILL.md），v4 示例见 skills/cloud/references/api-v4.md：
import { BrowserUse } from "browser-use-sdk/v4"; const client = new BrowserUse(); const created = await client.runs.create({ task: "Open https://example.com and return its title", maxCostUsd: 1.00, }); const run = await client.runs.waitForCompletion(created.id); if (run.status !== "completed") { throw new Error(`Run ${run.id}: ${run.status}`); } console.log(run.result);MCP-Native Agents
适用对象：Claude Desktop、启用 MCP 的 Cursor，以及任何通过协议发现工具的 MCP 客户端。MCP 方案分云端与本地两种。
云端 MCP（整体任务委托）
在 MCP 配置中加入 browser-use 服务器：
{ "mcpServers": { "browser-use": { "url": "https://api.browser-use.com/mcp", "headers": { "X-Browser-Use-API-Key": "YOUR_KEY" } } } }配置完成后，Agent 会获得一个browser_task工具：传入一段任务描述，即可拿到结果。根据 skills/cloud/references/features.md 中的 MCP 工具清单，云端 MCP 还提供execute_skill（$0.02 执行技能）、list_skills（免费）、get_cookies（免费）、list_browser_profiles（免费）、monitor_task（免费检查任务进度）等工具，browser_task的计费为 $0.01 + 每步费用。
本地 MCP（开源、免费）
本地启动 MCP 服务器后，Agent 会获得retry_with_browser_use_agent工具，它把整个任务委托给本地 Agent 执行：
uvx --from 'browser-use[cli]' browser-use --mcp该工具在当前仓库中的实现位于 browser_use/mcp/server.py：它的描述明确写着「仅在多次与页面交互失败后作为最后手段使用」，输入参数包括：
task（string，必填）：高层目标 + 详细的分步描述，以及完成所需的数据与之前尝试的信息；max_steps（integer，默认 100）：Agent 最大步数；model（string，可选）：使用的 LLM 模型（如gpt-4o、claude-3-opus-20240229），默认取配置中的模型；allowed_domains（array，可选）：允许访问的域名白名单（安全特性），省略时使用服务器配置的默认 profile；空列表与省略等价，不会关闭服务端配置的域名限制；use_vision（boolean，默认 true）：是否启用视觉能力。
其执行逻辑（browser_use/mcp/server.py）会先解析 LLM 配置（支持 Bedrock 与 OpenAI 兼容通道），再合并 profile 配置创建BrowserProfile，最终构造Agent并运行agent.run(max_steps=max_steps)，返回包含步数、成功标志与最终结果的摘要。从源码结构看，这个工具适合「主 Agent 兜底失败后把整个任务降级交给自研 Agent」的场景。
另外，CLI 中--mcp标志会直接调度到 MCP 的 stdio 服务（browser_use/cli.py），而--cli-mcp则启动 CLI 专用 MCP 服务（browser_use/mcp/cli_mcp.py），后者把 CLI 3.0 的浏览器助手以 MCP 工具形式暴露给客户端。
HTTP / Workflow Engines
适用对象：n8n、Make、Zapier、Temporal、Serverless 函数以及任意 HTTP 客户端。此方案只依赖 REST API，语言无关。
创建任务 → 轮询 → 获取结果
# 1. 创建任务 curl -X POST https://api.browser-use.com/api/v2/tasks \ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"task": "Find the top HN post and return title+URL"}' # → {"id": "task-uuid", "sessionId": "session-uuid"} # 2. 轮询状态（轻量接口） curl https://api.browser-use.com/api/v2/tasks/<task-id>/status \ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" # → {"status": "finished"} # 3. 获取结果 curl https://api.browser-use.com/api/v2/tasks/<task-id> \ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" # → 完整 TaskView：output、steps、outputFiles建议的轮询节奏是先打轻量的/status接口，仅在状态变为completed/failed/cancelled后再拉取完整结果，避免反复轮询大对象（v4 的 SDK wait 辅助方法即采用此策略，见 skills/cloud/references/api-v4.md）。v4 的 REST 流程与之对应：
curl -X POST https://api.browser-use.com/api/v4/runs \ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"task":"Find the top Hacker News story"}'事件驱动型工作流可改用Webhook（详见 skills/cloud/references/features.md）：任务状态变化时云端会推送agent.task.status_update事件（status 为 started/finished/stopped），负载中包含task_id、session_id与status；webhook 使用 HMAC-SHA256 签名（请求头X-Browser-Use-Signature与X-Browser-Use-Timestamp），验签需对{timestamp}.{body}（body 为按键排序、无多余空白的 JSON）计算 HMAC，并拒绝超过 5 分钟的旧请求以防重放攻击。这样可以让 n8n / Temporal 的工作流完全事件驱动，省去轮询。
横向工程要点（Cross-Cutting Concerns）
结构化输出
三种接入方式的统一约定：
- Cloud SDK Python：
output_schema=MyPydanticModel→result.output（类型化对象） - Cloud SDK TypeScript：
{ schema: ZodSchema }→result.output（类型化对象） - Cloud REST：请求体传
"structuredOutput": "<json-schema-string>"→ 响应中的output字段
注意 REST 的structuredOutput是字符串化的 JSON Schema，需要先JSON.stringify(...)再放入请求体（如本指南 CLI 一节所示）。
错误处理
from browser_use_sdk import AsyncBrowserUse, BrowserUseError try: result = await client.run(task, max_cost_usd=0.10) except TimeoutError: pass # 轮询超时（默认 5 分钟） except BrowserUseError as e: pass # API 错误需要特别留意的两个边界（见 skills/cloud/references/api-v4.md）：
- 轮询超时 ≠ 任务取消：本地轮询超时不会取消远端 run；若决定放弃，应显式调用
client.runs.cancel； - 不要盲目重试模糊的创建请求：对结果不确定的 create 请求直接重试可能启动多份付费任务；
- 轮询只打 status 轻量接口，SDK 的 wait 辅助方法正是「status 轮询 + 最后拉取一次完整 run」。
成本控制
- Cloud v2：按步骤计费，用
max_steps限制最大步数； - Cloud v3/v4：
max_cost_usd=0.10直接封顶花费，事后可通过result.total_cost_usd核对实际支出。
v4 还支持maxCostUsd（TS 侧同名参数），示例见上文 v4 代码块。此外，会话与浏览器计费的边界也要注意：SDK 3.11.3+ 的 v4 命名空间暴露了browsers.create/browsers.stop，关闭 CDP 客户端并不会停止云浏览器及其计费，必须显式停止浏览器（参见 skills/cloud/references/api-v4.md 与 skills/cloud/SKILL.md）。
资源清理
任务结束务必停止会话，用try/finally保证异常路径也完成清理：
session = await client.sessions.create(proxy_country_code="us") try: result = await client.run(task, session_id=str(session.id)) finally: await client.sessions.stop(str(session.id))同样的原则适用于 v4 的浏览器资源（client.browsers.stop(browser.id)应放入finally块）与 CLI 的远程 daemon（stop_remote_daemon(name)，远程浏览器在停止或超时前持续计费）。对于多步骤交互场景，skills/cloud/references/features.md 还展示了keep_alive=True与liveUrl的组合用法——Agent 在敏感步骤（如支付页）暂停，由真人通过liveUrl接管鼠标键盘，随后 Agent 继续完成任务，这是 subagent 模式在高风险流程中的实用变体。
- 人工智能
- AI Agent
- 浏览器控制
- GUI 自动化
- MCP 服务
【免费下载链接】browser-use
Agents that use the browser.
相关推荐
Browser-Use：让AI成为你的网页操作智能助理
Browser Use：让AI成为你的网页操作智能助理 还在为每天重复的网页操作而烦恼吗？填写表单、数据抓取、价格监控...这些枯燥的工作现在可以完全交给AI来
人工智能AI Agent浏览器控制GUI 自动化MCP 服务Paseo Workspaces 完全指南：以工作区为核心的任务编排模型
Paseo Workspaces 完全指南：以工作区为核心的任务编排模型 本指南深入讲解 Paseo 的核心组织概念 —— Workspace（工作区）。Pas
Camunda服务任务：Java委托与表达式执行
Camunda服务任务：Java委托与表达式执行 引言 在企业级业务流程管理（BPM）中，服务任务（Service Task）是实现自动化业务逻辑的核心组件。C
后端工作流自动化流程编排
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
