构建 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 会在三个位置扫描浏览器后端:
- 内置(Bundled) ——
<repo>/plugins/browser/<name>/(随kind: backend自动加载) - 用户(User) ——
~/.kopi/plugins/browser/<name>/(通过plugins.enabled或kopi plugins enable <name>选择启用) - Pip —— 声明了
kopi_agent.pluginsentry 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