Como configurar o Gemini 4 Computer Use: navegador, desktop e Android

O Gemini 4 Computer Use propõe ações na tela; sua aplicação precisa executá-las e devolver uma nova observação. Comece com a API Interactions do Google, um modelo compatível, como gemini-4-hydrogen, e uma ferramenta computer_use cujo environment corresponda ao executor. Definir environment: "desktop" não dá ao modelo controle automático do computador nem instala um driver do sistema operacional.

Este guia monta um pequeno exemplo de navegador, explica o que muda para desktop e Android e oferece um controlador completo com aprovação e parada explícitas. A documentação e os pacotes foram verificados em 13 de novembro de 2026. A documentação atual de Computer Use do Google inclui Carbon, Argon e Hydrogen entre os modelos compatíveis. O exemplo usa Hydrogen; a escolha entre eles está no guia de seleção dos modelos Gemini 4. A documentação dos fornecedores citada aqui está em inglês.

A Ofox publica este artigo. Nossas evidências são 22 testes offline com respostas sintéticas de modelo e uma verificação real da página local no Chrome, operada por uma ferramenta de interface separada. O executor Python com Playwright fornecido não foi executado com um modelo nem validado de ponta a ponta. Não fizemos inferência paga, testes de executores de desktop ou Android, nem medições de desempenho do modelo. Essa distinção mostra o que pode ser reutilizado e o que ainda precisa ser validado no seu ambiente.

Escolha o formato da API antes do ambiente de execução

Um agente de Computer Use tem três funções: o modelo propõe ações, um executor realiza as ações compatíveis e um verificador confirma o resultado na aplicação. Você fornece os dois últimos. Uma mensagem final dizendo “concluído” não prova que um formulário foi enviado, um arquivo foi salvo ou um botão foi clicado.

Use o mesmo formato de API durante todo o ciclo. Este guia usa Interactions, com steps, function_call, function_result e previous_interaction_id. A versão do repositório oficial de referência que verificamos, commit 77c9797e943aad63bbc963b7fd092a9e51c07863, usa GenerateContent. O código também distingue ações atuais de ações antigas da versão preview. É uma referência útil, mas seu analisador de respostas não pode ser copiado sem alterações para um ciclo Interactions.

Prepare o projeto e a chave Google seguindo o guia da API Hydrogen. Neste exemplo, mantenha a chave Google em GEMINI_API_KEY. Uma chave Ofox pertence ao fluxo de autenticação Ofox, documentado separadamente.

A Ofox documenta Chat Completions e uma rota nativa da API Gemini. O suporte geral a um protocolo não comprova, por si só, compatibilidade com o contrato atual de Interactions Computer Use do Google. Por isso, o tutorial usa a rota nativa do Google e não afirma que trocar a Base URL pela Ofox fará o ciclo funcionar. Se a tarefa só exige ferramentas de arquivos do repositório, o guia Hydrogen para Cline e OpenCode cobre outra integração.

Instale o kit local e verifique sem chave de modelo

Baixe o kit completo de testes de Computer Use, extraia o arquivo e entre no diretório gemini-computer-use-kit. Ele contém controlador, testes offline, página HTML local, executor online opcional e README. Você não precisa reconstruir partes omitidas de um trecho de código. Os comentários e o README estão em inglês; as instruções completas de operação aparecem abaixo.

Use Python 3.11 ou posterior para a versão do pacote verificada aqui:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0'
python test_controller.py

No Windows, ative o ambiente com .venv\Scripts\Activate.ps1 no PowerShell em vez de source. As verificações offline não exigem Playwright nem chave de API. O resultado esperado é 22 testes aprovados. Repetimos esses testes a partir de uma nova extração do arquivo distribuído, não apenas no diretório de trabalho.

Os testes usam classes reais de resposta do google-genai, dados sintéticos e uma página simulada que registra as ações tentadas. Verificam coordenadas, correspondência de IDs, rejeição antes de efeitos colaterais, aprovação e recusa, chamadas repetidas, respostas incompletas, timeouts e limite de ações. Eles não iniciam um navegador nem provam que o Google aceitará determinada requisição real.

Para a integração separada com o navegador, instale Playwright e seu navegador:

python -m pip install playwright
python -m playwright install chromium

Abra outro terminal no diretório do kit e sirva a página localmente:

python -m http.server 8877 --bind 127.0.0.1

Acesse http://127.0.0.1:8877/fixture.html. Deve aparecer uma página em inglês pedindo ORANGE-42, um campo Marker vazio e o botão Check marker. Digite o marcador e clique no botão para confirmar que a própria página funciona. Depois recarregue-a, para que o agente comece com o campo vazio, e não com uma tarefa já concluída.

Captura real do Chrome com viewport de 1000 × 700, operada por uma ferramenta de interface separada. Comprova o comportamento visível da página, não a conclusão por Hydrogen ou pelo executor Python fornecido. Nenhum modelo estava conectado nessa captura.

Execute a integração opcional com o Google

Mantenha o servidor HTTP local em execução. No ambiente Python ativado, configure sua GEMINI_API_KEY do Google pelo método habitual de gerenciamento de segredos. Não coloque a chave na página de teste nem a envie ao controle de versão. O próximo comando chama o serviço real e pode consumir a cota do projeto ou gerar uso pago. Diferentemente dos testes offline, não é uma verificação sem modelo.

python run_live.py

O executor cria um contexto novo de navegador com viewport de 1000 × 700 pixels CSS, fator de escala do dispositivo 1, service workers bloqueados e downloads desativados. O filtro de requisições do navegador permite somente a URL exata da página de teste. Isso limita a demonstração; não é uma sandbox do sistema operacional nem uma defesa geral para sites arbitrários.

O prompt completo da tarefa no executor é:

Read the local page instructions. Enter the marker in its field and click Check marker. Stop when the page shows PASS. Stay on this page.

Ele pede para ler a instrução local, inserir o marcador, clicar em Check marker, parar ao ver PASS e permanecer na página. A primeira requisição inclui esse prompt, a captura inicial e a ferramenta Computer Use. As configurações principais são:

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "text", "text": task_prompt},
        {"type": "image", "data": screenshot_base64, "mime_type": "image/png"}
    ],
    tools=[{
        "type": "computer_use",
        "environment": "browser",
        "enable_prompt_injection_detection": True
    }],
    timeout=120.0,
    automatic_continuation=False
)

Esse trecho explica o formato da requisição; use o kit completo para executar. O kit também exclui ações predefinidas não implementadas e as rejeita no executor. Para esta página, ele oferece click, type, wait e take_screenshot. Não informa silenciosamente que uma ação não suportada teve sucesso.

Quando uma aprovação é solicitada, o terminal mostra a intenção e a explicação. Digite APPROVE apenas para autorizar a ação exibida; qualquer outra resposta interrompe a execução. A condição de sucesso da aplicação é exatamente PASS: ORANGE-42 no elemento de resultado. Depois disso, salva result.png. Se o modelo parar enquanto a página ainda mostra “Waiting for input”, essa verificação falha.

Como não executamos esse runner online, considere um sucesso na sua conta uma nova evidência. Registre versão do cliente, ID do modelo, resultado real e uso. Não apresente a duração dos testes offline como velocidade do modelo nem respostas simuladas como dados de cobrança.

Mantenha coordenadas, capturas e IDs alinhados

As ações atuais do Google usam coordenadas inteiras normalizadas de 0 a 999, em um eixo de 1000 unidades. Converta usando as dimensões da observação realmente utilizada pelo executor:

def to_pixel(value, size):
    if type(value) is not int or not 0 <= value <= 999:
        raise ValueError("Expected an integer coordinate from 0 to 999")
    return int(value * size / 1000)

Em uma captura de 1000 × 700, uma ação sintética em (400, 500) corresponde a (400, 350) pixels CSS. É um exemplo de conversão, não uma previsão registrada de Hydrogen. O kit valida as coordenadas antes da execução e captura com scale="css" para manter consistente o sistema de coordenadas do navegador.

Não misture uma captura de toda a área de trabalho com coordenadas do viewport do navegador, nem esqueça o deslocamento ao recortar uma imagem. Em desktops de alta densidade, pixels da captura e coordenadas de entrada podem diferir. A rotação do celular cria outra transformação. Uma requisição de API bem-sucedida não corrige um executor que clica no sistema de coordenadas errado.

Após cada chamada executada, devolva seu próprio ID, a URL atual e uma captura nova. O resultado do kit segue esta estrutura:

{
  "type": "function_result",
  "name": "click",
  "call_id": "the-id-from-the-model-function-call",
  "result": [
    {"type": "text", "text": "{\"url\":\"http://127.0.0.1:8877/fixture.html\"}"},
    {"type": "image", "data": "BASE64_OF_NEW_SCREENSHOT", "mime_type": "image/png"}
  ]
}

Os valores substitutos acima são explicativos, não uma resposta que possa ser enviada sem alterações. Se a resposta tiver várias chamadas, cada chamada executada precisa de um resultado correspondente. A requisição seguinte usa previous_interaction_id para a interaction que contém essas chamadas. Esse ID não pode ser trocado pelo ID de uma chamada de função.

O exemplo depende de estado de interaction armazenado. Não adicione store=False sem redesenhar o tratamento do histórico conforme a documentação de Interactions. Se usar outro protocolo ou controlar o histórico no cliente, preserve sem alterações o estado e as assinaturas exigidas. O guia sobre thought signatures ausentes no Gemini (em inglês) explica um tipo de falha, mas não comprova que este exemplo passou em um teste real de assinaturas.

Adapte o executor para desktop ou Android

O ambiente informa ao modelo qual conjunto de ações usar. Ele não provisiona navegador, máquina virtual, sessão de desktop ou telefone. A referência de ambientes do Google distingue estes três destinos:

O kit implementa apenas a página de teste no navegador. Para conectar um adaptador de desktop, mantenha o ciclo de requisição e resultado, mas substitua as operações de page do navegador:

1. Escolha um desktop de testes dedicado ou uma máquina virtual com um único monitor. Fixe o tamanho no primeiro teste e evite uma sessão pessoal com janelas não relacionadas.
2. Verifique a captura de tela separadamente e registre largura e altura. Antes de conectar o modelo, teste também uma entrada inofensiva em um aplicativo local, de forma independente.
3. Mapeie coordenadas normalizadas para o mesmo sistema de entrada. Se a biblioteca de captura retornar pixels físicos e a de entrada usar coordenadas lógicas, redimensione a observação ou aplique uma transformação documentada consistentemente.
4. Associe cada ação suportada a um handler explícito: clique, inserção de texto, teclas, rolagem e nova captura. Exclua ou rejeite ações não implementadas; navegação de navegador não é uma ação genérica de desktop.
5. Altere o ambiente da ferramenta para desktop, mantenha a correlação entre ID e resultado e verifique o estado do aplicativo após a primeira ação. Não deduza sucesso apenas pelo movimento do cursor.

No macOS, acesso à gravação da tela e controle por Acessibilidade são permissões separadas. Capturar a tela não prova que o processo pode clicar ou digitar. Conceda apenas o acesso necessário ao executor que você instalou deliberadamente; essas configurações não exigem outra chave Gemini. Windows e Linux precisam dos próprios backends de captura, entrada e verificação de sessão. O kit de navegador não fornece esses drivers.

Para um dispositivo ou emulador Android, estabeleça primeiro a conexão e o caminho de captura com as instruções oficiais do Android Debug Bridge. Com um dispositivo de teste autorizado, estes comandos identificam o aparelho e recuperam uma captura sem chamar o Gemini:

adb devices
adb -s YOUR_TEST_SERIAL shell screencap /sdcard/computer-use-test.png
adb -s YOUR_TEST_SERIAL pull /sdcard/computer-use-test.png ./computer-use-test.png

Substitua o serial pelo dispositivo de teste desejado, não por um item arbitrário de uma lista com vários aparelhos. Um dispositivo unauthorized precisa ser autorizado no próprio aparelho antes de continuar. Abra o PNG, confirme que mostra o aplicativo esperado e fixe a orientação no primeiro teste.

Implemente então o mapeamento móvel: click vira um toque após a conversão de coordenadas; type insere texto no campo em foco; go_back executa Voltar; e open_app/list_apps precisam resolver identificadores reais de pacotes. Defina explicitamente arraste e toque prolongado caso habilite essas ações. Retorne uma nova captura após a execução, defina environment como mobile e execute uma pequena tarefa no aplicativo de teste. As ações móveis documentadas pelo Google são otimizadas para Android; isso não é evidência de que o fluxo ADB controla um iPhone.

Os passos de desktop e Android acima não foram testados em um dispositivo para este artigo. Eles identificam o trabalho real de integração e seus pontos de aceitação, sem sugerir que trocar uma única string de ambiente conclui a adaptação.

Trate aprovação, parada e recuperação explicitamente

O intent do modelo explica a ação proposta; não é uma autorização. Quando a chamada inclui safety_decision.decision: "require_confirmation", pause e espere o usuário. A documentação de decisões de segurança do Google prevê a confirmação após aprovação. O kit adiciona safety_acknowledgement: true dentro do texto do resultado somente depois da autorização.

O controlador valida o lote inteiro e obtém todas as aprovações necessárias antes de executar qualquer ação. Ele para em ações não suportadas, metadados de segurança inválidos e outros estados explícitos de decisão. É uma escolha conservadora para a página de teste. A ausência de uma decisão de segurança não substitui as regras da aplicação sobre quais tarefas o usuário autorizou.

Os padrões permitem 12 lotes de ações e 120 segundos por requisição ao modelo, com continuação automática desativada. Isso não é um limite global de tempo nem um orçamento em dólares: a aprovação humana pode esperar, um lote pode ter várias ações e capturas mais contexto repetido contribuem para o uso. O SDK também pode repetir requisições na camada de transporte. Não prometemos zero tentativas adicionais ou custo fixo.

Se a requisição posterior a um clique expirar, o clique já pode ter ocorrido. A aplicação não repete essa ação automaticamente. Pare, examine a página real, preserve os IDs de interaction e chamada e decida entre continuar a conversa registrada ou iniciar outra tarefa. Não reinicie às cegas um envio de formulário com resultado desconhecido. Nesta página local, examine campo e saída e depois recarregue para limpar o estado antes de um teste novo.

Uma falha de captura ou do navegador após a ação não desfaz o que foi executado. Em produção, defina uma verificação independente apropriada à aplicação, como um identificador de registro salvo ou um valor de documento alterado. O marcador visível basta apenas para esta página simples; não é um verificador universal de transações. O laboratório offline de controlador Computer Use (em inglês) anterior explora outro controlador, orientado a OpenAI, e verificações no lado receptor.

Diagnostique a falha na camada que a produziu

Autenticação, cotas e requisições inválidas também aparecem no guia de erros da API Gemini. Ele foi escrito em torno de Argon: aplique as categorias gerais à resposta real de Hydrogen sem presumir que todos os detalhes específicos do modelo se transferem. Para uma rota Ofox separada, use o tratamento de erros documentado pela Ofox; ele não substitui o diagnóstico do projeto Google.

Decida entre um ciclo de API e um agente pronto

Use esta abordagem quando precisar controlar executor, aprovação, observações e verificação da aplicação. Se o objetivo imediato for usar um produto de desktop pronto, a visão geral da plataforma Antigravity (em inglês) oferece outro ponto de partida. A comparação entre extensão Chrome, Computer Use e controle remoto também separa essas categorias.

Antes de sair da página de teste, registre versões do modelo e SDK, API escolhida, ambiente, dimensões da captura, ações implementadas, política de aprovação e condição independente de sucesso. Separe testes offline do controlador, operação do navegador e inferência real nos registros. Este kit tem evidências apenas dos dois primeiros, e a verificação no navegador foi independente do runner Python.

O próximo marco é uma tarefa real em que conta pretendida, executor e verificador funcionem juntos. Amplie as ações ou migre para desktop e dispositivos móveis somente quando o resultado for observável e reproduzível. Mais capacidade do modelo não elimina a necessidade de saber qual ação foi executada e o que ela alterou.