跳到主要内容

构建 Browser Provider 插件

Browser provider 插件用于注册 云端浏览器后端,为云端模式的 browser_* 工具调用(navigate、click、screenshot 等)提供服务。内置的 provider —— Browserbase、Browser Use 和 Firecrawl —— 都以插件形式打包在 plugins/browser/<name>/ 下。你可以添加一个全新的插件,或者通过在其旁边放置一个目录来覆盖某个内置插件。

提示

浏览器后端是 Kopi Agent 支持的多种后端插件之一。其他后端插件(各有自己的 ABC)包括:Web Search Provider 插件(本 ABC 有意与其保持一致)、图像生成、视频生成、Memory Provider、Context Engine、Secret Source 和 Model Provider。通用的 tool/hook/CLI 插件请参见构建 Kopi Agent 插件。

整体工作原理​

Browser provider 并不实现浏览功能本身。它实现的是会话生命周期:创建远程浏览器会话、返回 CDP websocket URL,以及销毁会话。Kopi Agent 自身的浏览器栈(agent-browser + tools/browser_tool.py)会连接到你返回的任意 CDP URL,并从那里驱动页面 —— 每个 provider 都能免费获得完整的 browser_* 工具集。

当前激活的 provider 由 config.yaml 中的 browser.cloud_provider 选择;tools/browser_tool.py 中的调度器是纯注册表查找,没有任何针对特定 provider 的条件分支。

发现机制​

Kopi Agent 会在三个位置扫描浏览器后端:

  1. 内置(Bundled) —— <repo>/plugins/browser/<name>/(随 kind: backend 自动加载)
  2. 用户(User) —— ~/.kopi/plugins/browser/<name>/(通过 plugins.enabled 或 kopi plugins enable <name> 选择启用)
  3. Pip —— 声明了 kopi_agent.plugins entry point 的包

每个插件的 register(ctx) 会调用 ctx.register_browser_provider(...),从而把实例放入 agent/browser_registry.py 中的注册表。

目录结构​

plugins/browser/my-backend/
├── __init__.py # register() entry point
├── provider.py # BrowserProvider subclass
└── plugin.yaml # Manifest with kind: backend and provides_browser_providers

plugin.yaml:

name: browser-my-backend
version: 1.0.0
description: "My cloud browser backend. Requires MY_BACKEND_API_KEY."
author: you
kind: backend
provides_browser_providers:
- my-backend

__init__.py:

from plugins.browser.my_backend.provider import MyBackendProvider


def register(ctx) -> None:
ctx.register_browser_provider(MyBackendProvider())

BrowserProvider ABC​

实现 agent.browser_provider.BrowserProvider。包含三个生命周期方法以及标识信息:

from agent.browser_provider import BrowserProvider


class MyBackendProvider(BrowserProvider):
@property
def name(self) -> str:
return "my-backend" # the browser.cloud_provider config value

@property
def display_name(self) -> str:
return "My Backend" # shown in `kopi tools`

def is_available(self) -> bool:
"""Cheap check only — env var present, dep importable.
NO network calls: runs at tool-registration time and on every
`kopi tools` paint."""
return bool(os.environ.get("MY_BACKEND_API_KEY"))

def create_session(self, task_id: str) -> dict:
"""Create a remote browser session; return the session-metadata contract."""
session = my_api.create_browser(...)
return {
"session_name": f"my-backend-{task_id}", # unique agent-browser session name
"bb_session_id": session.id, # provider session ID (for cleanup)
"cdp_url": session.cdp_ws_url, # CDP websocket URL
"features": {"stealth": True}, # feature flags you enabled
}

def close_session(self, session_id: str) -> bool:
"""Terminate by provider session ID. Log-and-return-False on error —
never raise, so the dispatcher's cleanup loop keeps moving."""
...

def emergency_cleanup(self, session_id: str) -> None:
"""Best-effort teardown from atexit/signal handlers. Must not raise."""
...

会话元数据契约​

create_session() 必须至少返回 session_name、bb_session_id、cdp_url 和 features。有两个需要了解的细节:

  • bb_session_id 是一个历史遗留的键名,为与 tools/browser_tool.py 保持向后兼容而原样保留 —— 无论使用哪家供应商,它保存的都是你的 provider 的会话 ID。请勿重命名它。
  • create_session() 可以抛出异常 —— 凭据缺失时抛出 ValueError,网络/API 故障时抛出 RuntimeError。调度器会将这些异常展示给用户。这一点不同于 close_session/emergency_cleanup,后两者绝不能抛出异常。

可选的 external_call_id 键用于支持托管网关计费。

get_setup_schema() —— kopi tools 选择器条目​

重写此方法后,你的 provider 将作为一等选项出现在浏览器自动化选择器中,并支持 API key 提示和安装钩子:

def get_setup_schema(self) -> dict:
return {
"name": "My Backend",
"badge": "paid",
"tag": "Cloud browser with stealth and proxies",
"env_vars": [
{"key": "MY_BACKEND_API_KEY",
"prompt": "My Backend API key",
"url": "https://mybackend.example"},
],
"post_setup": "agent_browser", # auto-installs the agent-browser npm dep
}

按照工具后端的项目标准:如果一个后端无法通过 kopi tools 被选择和配置,那它就不算完成 —— “请手动设置这个环境变量”不算是一个集成方案。

用户如何配置它​

browser:
cloud_provider: my-backend

参考实现​

plugins/browser/ 下的三个内置 provider 是规范示例,按复杂度递增排列:firecrawl(最简单)、browser_use,以及 browserbase(包含隐身/代理/保活特性开关,在付费功能不可用时能够优雅降级)。请复制与你需求最接近的那个。

检查清单​

  • name 为小写且保持稳定(它是用户会编写进配置的值)
  • is_available() 不发起任何网络调用
  • create_session() 返回完整的元数据契约(bb_session_id 键名保持不变)
  • close_session() / emergency_cleanup() 从不抛出异常
  • get_setup_schema() 暴露你的环境变量,以便 kopi tools 能够配置该后端
  • plugin.yaml 声明了 kind: backend + provides_browser_providers