Integração Mbbrowser ControlV2

A razão pela qual o MBAgent pode "realmente operar o Mbbrowser" reside num protocolo de comunicação chamado Mbbrowser Client ControlV2. Este artigo detalha como o MBAgent estabelece ligação com o Mbbrowser e a resolução de problemas comuns.

NOTE

Descrição da captura de ecrã: A captura de ecrã de "controlo duplo" quando o MBAgent e o Mbbrowser correm em simultâneo (janela principal Mbbrowser + janela principal MBAgent lado a lado) será progressivamente suplementada na v1.x. Esta secção começa por descrever em texto a colaboração entre os dois.

---

1. O Que É o Mbbrowser ControlV2?

Mbbrowser ControlV2 é um protocolo de comunicação bidirecional fornecido pelo Mbbrowser a programas externos (incluindo o MBAgent) que permite:

• 🔍 Descobrir instâncias Mbbrowser em execução localmente
• 🤝 Fazer handshake com instâncias Mbbrowser
• 🔑 Iniciar sessão via conta Mbbrowser
• 📦 Carregar config Mbbrowser (ambientes, proxy, impressão digital)
• 🚀 Iniciar / parar ambientes Mbbrowser
• 🌐 Operar páginas dentro dos ambientes Mbbrowser

NOTE

Analogia: Pode compreender o ControlV2 como o "protocolo de controlo remoto" do Mbbrowser. O MBAgent é o controlo remoto; o Mbbrowser é a TV.

---

2. Três Modos de Ligação Entre MBAgent e Mbbrowser

1. Controlo MBAgent (Recomendado)

O MBAgent inicia automaticamente um serviço de controlo Mbbrowser localmente ao arrancar; o Mbbrowser liga-se como cliente.

Cenários de utilização:

• Instância Mbbrowser única
• A maioria dos utilizadores individuais
• Mbbrowser + MBAgent em execução na mesma máquina

2. Controlo ApiServer

Ligar via interface ApiServer incorporada do Mbbrowser (http://127.0.0.1:8186).

Cenários de utilização:

• Controlar Mbbrowser remotamente
• Mbbrowser noutra máquina
• Scripts de automação (Selenium / Puppeteer / Playwright)

3. Mesma Instância

MBAgent e Mbbrowser estão na mesma instância cliente, comunicando internamente diretamente.

Cenários de utilização:

• Depuração de desenvolvimento
• Cenários sensíveis ao desempenho

---

3. Primeira Ligação com o Mbbrowser

Pré-requisitos

✅ Mbbrowser está iniciado e com sessão iniciada numa conta ✅ MBAgent está instalado ✅ O diretório de trabalho selecionado no arranque do MBAgent tem permissões

Fluxo de Ligação Automática

O MBAgent automaticamente executa o seguinte fluxo ao arrancar:

[1] Iniciar serviço ControlV2 local
    ↓
[2] Procurar instâncias Mbbrowser locais
    - Via broadcast UDP / scan de porta local
    - Encontrar a porta ControlV2 do Mbbrowser
    ↓
[3] Handshake
    - Trocar números de versão do protocolo
    - Negociar método de encriptação
    ↓
[4] Login de conta
    - O MBAgent inicia sessão no ControlV2 com a conta Mbbrowser
    - Auto-ler Token
    ↓
[5] Carregamento de config
    - Carregar todos os ambientes sob a conta Mbbrowser
    - Carregar configuração de proxy sob a conta Mbbrowser
    ↓
[6] Deteção de capacidades
    - Testar início / paragem de ambiente
    - Testar takeover de página
    - Testar operações de ficheiros
    ↓
[7] Sucesso de ligação ✅

Ver Estado de Ligação

1. Vá a "Definições → Deteção de Serviço Oficial"
2. Clique na opção "Mbbrowser Client ControlV2"
3. Clique em "Iniciar Deteção"
4. Exibido após alguns segundos:
   • ✅ Normal: Todas as verificações passadas
   • ⚠️ Anormal: Passo específico que falhou
   • ⚪ Não ativado: ControlV2 não ativado
   • ⏳ A detetar: Atualmente a detetar

---

4. Interpretação do Resultado da Deteção

✅ Normal

Exibe:

Mbbrowser Client ControlV2 está disponível
A deteção de ida-e-volta de prontidão em tempo real verificou ligação, login, configuração e capacidade executável.

Isto significa que o MBAgent pode operar normalmente o Mbbrowser.

⚠️ Anormal: Falha de Ligação

Possíveis causas:

• Mbbrowser não iniciado
• Porta ControlV2 ocupada
• Bloqueio por firewall

Resolução:

1. Confirme que o Mbbrowser está iniciado
2. Verifique Mbbrowser → Definições → se ControlV2 está ativado
3. Feche firewall / software antivírus e tente novamente

⚠️ Anormal: Conta Sem Sessão Iniciada

Possíveis causas:

• Token da conta Mbbrowser expirado
• MBAgent não leu o Token

Resolução:

1. Reinicie a sessão da conta dentro do Mbbrowser
2. Reinicie o MBAgent

⚠️ Anormal: Falha no Carregamento da Config

Possíveis causas:

• Sem ambientes criados sob a conta Mbbrowser
• Falha na ligação à base de dados Mbbrowser

Resolução:

1. Crie um ambiente dentro do Mbbrowser
2. Reinicie o MBAgent

⚠️ Anormal: Capacidade Executável Não Passou

Possíveis causas:

• Versão do Mbbrowser incompatível com MBAgent
• Permissões de sistema insuficientes

Resolução:

1. Confirme que o Mbbrowser é a versão mais recente
2. Inicie o MBAgent com privilégios de administrador
3. Contacte o suporte ao cliente Mbbrowser

---

5. Trocar Instâncias de Controlo Mbbrowser

Se tiver múltiplas instâncias Mbbrowser localmente (cenários de desenvolvimento), pode trocar:

Passo 1: Ver Todas as Instâncias Mbbrowser

1. Vá a "Definições → Mbbrowser Client ControlV2"
2. Clique na opção "Instância Mbbrowser"
3. Exibe a lista de instâncias Mbbrowser atualmente descobertas:

Instância Mbbrowser #1 (predefinida)
  - Porta: 8186
  - Versão: v3.0.0
  - Estado: Ligada

Instância Mbbrowser #2 (dev)
  - Porta: 8286
  - Versão: v3.0.0
  - Estado: Não ligada

Passo 2: Trocar

1. Selecione a instância Mbbrowser alvo
2. Clique no botão "Trocar"
3. O MBAgent desliga-se da instância atual e liga-se à nova
4. Nota: Trocar para todas as operações Mbbrowser atuais

TIP

Uso diário: 99% dos utilizadores só precisam de uma instância Mbbrowser; não precisam de trocar.

---

6. Como o AI Opera o Mbbrowser

Quando o MBAgent recebe uma instrução de "operar Mbbrowser", executa automaticamente o seguinte fluxo:

[1] O AI analisa a tarefa
    "Abrir loja Mbbrowser 223223, verificar encomendas de hoje"
    ↓
[2] Chamar interface ControlV2
    - control.browser.start({ environment_id: "223223" })
    ↓
[3] O Mbbrowser inicia o ambiente
    - Criar / reutilizar ambiente 223223
    - Aplicar impressão digital / proxy / cookie
    - Devolver browser_handle
    ↓
[4] O MBAgent assume a página via CDP
    - attach({ handle })
    - Receber captura de ecrã da página, estrutura DOM
    ↓
[5] O AI analisa a página + decide próximo passo
    "Vi a página de encomendas, agora extrair números"
    ↓
[6] Executar ações
    - click / type / extract
    ↓
[7] Completar tarefa, fechar ambiente (ou manter aberto)
    ↓
[8] Resumir resultado para o utilizador
    "Hoje 23 encomendas, valor $1234.56"

Conceitos Chave

• handle: O "handle de ambiente" devolvido pelo Mbbrowser ao MBAgent, usado para referenciar um ambiente específico
• attach: MBAgent assume a página de um ambiente Mbbrowser
• CDP: Chrome DevTools Protocol, o protocolo usado pelo Mbbrowser por baixo

---

7. FAQ

Q1: O MBAgent mostra "À espera do Mbbrowser CDP" após o arranque

Causa: O Mbbrowser não está iniciado, ou o ambiente não está iniciado.

Solução:

1. Confirme que o Mbbrowser está iniciado e com sessão iniciada
2. Inicie manualmente um ambiente dentro do Mbbrowser
3. O MBAgent assumirá automaticamente

Q2: As operações AI no ambiente Mbbrowser falham sempre

Possíveis causas:

• ControlV2 anormal (consulte a deteção de serviço oficial)
• Quota da conta Mbbrowser esgotada
• Ambiente Mbbrowser corrompido

Resolução:

1. Em Definições → Deteção de Serviço Oficial verifique se ControlV2 está normal
2. Verifique a quota AI da conta Mbbrowser
3. Teste manualmente o ambiente dentro do Mbbrowser

Q3: Ecrã fica preto após assumir a página Mbbrowser

Possíveis causas:

• Mbbrowser acabou de iniciar, ambiente ainda não está pronto
• Conta Mbbrowser requer verificação secundária

Solução:

1. Aguarde 5-10 segundos e tente novamente
2. Complete manualmente a verificação dentro do Mbbrowser

Q4: O MBAgent pode controlar um Mbbrowser remoto?

❌ Não. A ligação ControlV2 do Mbbrowser client do MBAgent é limitada a 127.0.0.1 na camada de implementação (ControlClientError::NonLoopbackEndpoint); qualquer endereço IP não-loopback é rejeitado. Mesmo que a porta ControlV2 do Mbbrowser seja exposta ao exterior (ex. 0.0.0.0:8186), o MBAgent recusará diretamente a ligação na etapa de handshake.

Forma correta de controlar Mbbrowser remotamente:

• Use scripts Selenium / Puppeteer / Playwright para chamar remotamente a ApiServer incorporada do Mbbrowser (http://127.0.0.1:8186) — consulte a Secção 2 acima "Três Modos de Ligação Entre MBAgent e Mbbrowser → 2. Controlo ApiServer"
• Neste cenário, o MBAgent não está envolvido; apenas um cliente HTTP regular a chamar interfaces Mbbrowser ApiServer

NOTE

Porquê limitado a loopback:

• O protocolo ControlV2 em si não tem verificação de identidade forte; expor porta TCP na rede pública equivale a "dar o controlo da conta Mbbrowser a qualquer pessoa"
• Assume-se que o MBAgent e o Mbbrowser correm na mesma máquina, mesmo contexto de conta; loopback é a fronteira de menor risco

Q5: O MBAgent pode ser usado sem operar o Mbbrowser?

✅ Absolutamente. As funções centrais do MBAgent (chat, documentos, código, base de conhecimento) não dependem do Mbbrowser. Só quando solicita explicitamente a operação de ambientes de conta Mbbrowser é que a ligação ControlV2 será estabelecida.

---

8. Melhores Práticas

Ordem de Arranque

Ordem de arranque recomendada:

1. Mbbrowser (arrancar primeiro e iniciar sessão)
2. MBAgent (arrancar depois, liga-se automaticamente)

Não inverta.

Quando Não Usado por Muito Tempo

Se não usar operações Mbbrowser por muito tempo:

1. Feche as entradas da barra lateral "Base de Conhecimento Mbbrowser RAG" e "Mbbrowser Client ControlV2" dentro do MBAgent
2. Reduza operações Mbbrowser em tarefas
3. Poupe uso de recursos da conta Mbbrowser

Colaboração Entre Várias Pessoas

Se vários membros da equipa partilham uma conta Mbbrowser:

1. O MBAgent de cada pessoa pode ligar-se independentemente
2. Mas operar em simultâneo um ambiente entrará em conflito
3. Recomenda-se uso escalonado, ou abrir sub-contas Mbbrowser independentes para cada pessoa

---

Próximo: Gestão de Permissões e Utilização Segura → Deixe o AI trabalhar com paz de espírito.