Plugins de Provedor de Navegador

Criar um plugin de provedor de navegador

Plugins de provedor de navegador registram um backend de navegador na nuvem que atende às chamadas de ferramenta browser_* no modo nuvem (navegar, clicar, tirar captura de tela, …). Os provedores embutidos — Browserbase, Browser Use e Firecrawl — são todos entregues como plugins em plugins/browser/<name>/. Você pode adicionar um novo, ou sobrescrever um dos que vêm de fábrica, largando um diretório ao lado deles.

dica

Backends de navegador são um dos vários plugins de backend que o Hermes suporta. Os outros (com as próprias ABCs) são Plugins de Busca na Web (que esta ABC espelha de propósito), Geração de Imagem, Geração de Vídeo, Provedores de Memória, Motores de Contexto, Fontes de Segredo e Provedores de Modelo. Plugins gerais de ferramenta/hook/CLI estão em Criar um plugin do Hermes.

Como as peças se encaixam

Um provedor de navegador não implementa a navegação. Ele implementa o ciclo de vida da sessão: criar uma sessão de navegador remota, devolver uma URL de websocket CDP e derrubar a sessão. A pilha de navegador do próprio Hermes (agent-browser + tools/browser_tool.py) se conecta a qualquer URL CDP que você devolver e dirige a página a partir dali — todo provedor ganha o conjunto completo de ferramentas browser_* de graça.

O provedor ativo é escolhido por browser.cloud_provider no config.yaml; o dispatcher em tools/browser_tool.py é uma consulta pura ao registro, sem condicionais por provedor.

Descoberta

O Hermes procura backends de navegador em três lugares:

1. Embutido — <repo>/plugins/browser/<name>/ (carregado automaticamente com kind: backend)
2. Usuário — ~/.hermes/plugins/browser/<name>/ (habilitação opcional via plugins.enabled ou hermes plugins enable <name>)
3. Pip — pacotes que declaram um entry point hermes_agent.plugins

O register(ctx) de cada plugin chama ctx.register_browser_provider(...), que coloca a instância no registro em agent/browser_registry.py.

Estrutura de diretórios

plugins/browser/my-backend/
├── __init__.py     # entry point register()
├── provider.py     # subclasse de BrowserProvider
└── plugin.yaml     # Manifesto com kind: backend e provides_browser_providers

plugin.yaml:

name: browser-my-backend
version: 1.0.0
description: "Meu backend de navegador na nuvem. Requer MY_BACKEND_API_KEY."
author: voce
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())

A ABC BrowserProvider

Implemente agent.browser_provider.BrowserProvider. Três métodos de ciclo de vida mais a identidade:

from agent.browser_provider import BrowserProvider


class MyBackendProvider(BrowserProvider):
    @property
    def name(self) -> str:
        return "my-backend"          # o valor de configuração de browser.cloud_provider

    @property
    def display_name(sel### `get_setup_schema()` — a linha no seletor do `hermes tools` {#getsetupschema-the-hermes-tools-picker-row}
        """Só verificação barata — variável de ambiente presente, dependência importável.
        SEM chamadas de rede: roda na hora de registrar a ferramenta e a cada
        repintura de `hermes tools`."""
        return bool(os.environ.get("MY_BACKEND_API_KEY"))

    def create_session(self, task_id: str) -> dict:
        """Cria uma sessão de navegador remota; devolve o contrato de metadados da sessão."""
        session = my_api.create_browser(...)
        return {
            "session_name": f"my-backend-{task_id}",  # nome único de sessão do agent-browser
            "bb_session_id": session.id,              # ID de sessão do provedor (para limpeza)
            "cdp_url": session.cdp_ws_url,            # URL de websocket CDP
            "features": {"stealth": True},            # flags de recurso que você habilitou
        }

    def close_session(self, session_id: str) -> bool:
        """Encerra pelo ID de sessão do provedor. Em caso de erro, registre no log e devolva
        False — nunca levante exceção, para o laço de limpeza do dispatcher seguir em frente."""
        ...

    def emergency_cleanup(self, session_id: str) -> None:
        """Desmontagem de melhor esforço a partir de handlers de atexit/sinal. Não pode levantar exceção."""
        ...

O contrato de metadados da sessão

create_session() precisa devolver pelo menos session_name, bb_session_id, cdp_url e features. Duas esquisitices que vale conhecer:

• bb_session_id é um nome de chave legado, mantido literalmente por compatibilidade retroativa com tools/browser_tool.py — ele guarda o ID de sessão do seu provedor, independentemente do fornecedor. Não renomeie.
• create_session() pode levantar exceção — ValueError para credenciais faltando, RuntimeError para falhas de rede/API. O dispatcher mostra isso ao usuário. Isso é diferente de close_session/emergency_cleanup, que nunca podem levantar exceção.

Uma chave opcional external_call_id dá suporte à cobrança do gateway gerenciado.

get_setup_schema() — a linha no seletor do hermes tools

Sobrescreva este método para aparecer como opção de primeira classe no seletor de Automação de Navegador, com prompts de chave de API e um hook de instalação:

def get_setup_schema(self) -> dict:
    return {
        "name": "My Backend",
        "badge": "paid",
        "tag": "Navegador na nuvem com stealth e proxies",
        "env_vars": [
            {"key": "MY_BACKEND_API_KEY",
             "prompt": "Chave de API do My Backend",
             "url": "https://mybackend.example"},
        ],
        "post_setup": "agent_browser",   # garante que o Chromium local esteja instalado (o próprio agent-browser resolve via npx)
    }

Pelo padrão do projeto para backends de ferramenta: se um backend não pode ser escolhido e configurado pelo hermes tools, ele não está pronto — "defina esta variável de ambiente na mão" não é uma integração.

Como os usuários configuram

browser:
  cloud_provider: my-backend

Implementações de referência

Os três provedores que vêm de fábrica em plugins/browser/ são os exemplos canônicos, em ordem crescente de complexidade: firecrawl (o mais simples), browser_use e browserbase (flags de recurso de stealth/proxy/keep-alive, com degradação suave quando os recursos pagos não estão disponíveis). Copie o mais próximo do seu caso.

Checklist

• name está em minúsculas e é estável (é um valor de configuração que os usuários escrevem)
• is_available() não faz nenhuma chamada de rede
• create_session() devolve o contrato de metadados completo (com o nome de chave bb_session_id intacto)
• close_session() / emergency_cleanup() nunca levantam exceção
• get_setup_schema() expõe as suas variáveis de ambiente para o hermes tools conseguir configurar o backend
• plugin.yaml declara kind: backend + provides_browser_providers

---