Construa um Loop de Agente de Navegador de Computador do Zero

TL;DR:

• Um agente de uso de computador pode ser reduzido a um laço percebido–decidir–agir limitado. O navegador captura a página atual, um modelo de visão escolhe uma ação, e o Playwright a executa antes que o ciclo comece novamente.
• O esquema de ação mantém a saída do modelo executável. Restringir cada decisão a clique, digite, role, ou feito transforma a resposta do modelo em um pequeno despachante determinístico.
• Capturas de tela frescas evitam decisões obsoletas. Cada chamada ao modelo vê a página após a ação anterior, então o agente raciocina a partir do estado atual do navegador.
• Um limite de etapas controla tanto a autonomia quanto o custo. O exemplo permite no máximo quatro iterações e termina em duas: clique em Próximo, confirme a nova primeira citação, e então pare.
• Um laço personalizado é melhor quando a lógica de decisão precisa permanecer visível. Use uma única chamada de visão para extração de uma vez e um agente empacotado quando o laço não precisar de ajustes frequentes.
• Gratuito para começar. Novas contas Scrapeless incluem execução gratuita do navegador de raspagem — inscreva-se em app.scrapeless.com.

Introdução: O Pequeno Laço por Trás do Uso de Computadores

Um agente de uso de computador faz três coisas repetidamente: ele observa a tela, decide sobre uma ação e executa essa ação. Produtos como a ferramenta de Uso de Computador da OpenAI e o modo de uso de computador Gemini do Google empacotam esse laço atrás de uma única chamada de API. Estruturas de agentes como a Skyvern empacotam isso atrás de um executor de tarefas. Abaixo de qualquer um dos dois, o próprio laço é uma pequena quantidade de código — uma captura de tela, uma chamada ao modelo de visão restrita a uma lista curta de ações e um comando do navegador que executa o que quer que o modelo tenha escolhido.

Este guia escreve esse laço diretamente, sem um agente empacotado no meio. Ele se conecta ao Navegador de Raspagem Scrapeless através do Protocolo DevTools do Chrome, captura a tela da página, envia a imagem para um modelo com capacidade de visão com quatro escolhas — clique, digite, role ou feito — e executa o que quer que o modelo retorne com o Playwright, em seguida repete. Cada passo abaixo é executado contra uma página real, com as decisões reais do modelo capturadas à medida que acontecem.

O Laço em Resumo

Cada iteração tem uma única fonte de verdade: a página como aparece na captura de tela mais recente.

O walkthrough usa um site público de citações e um objetivo restrito: sair da primeira página apenas quando a primeira citação for escrita por Albert Einstein, então parar assim que um autor diferente aparecer.

Por Que Construir o Laço Você Mesmo?

Escrever o laço diretamente dá a você controle sobre o formato de percepção, o vocabulário de ação e a regra de parada.

Um agente com captura estruturada e uma estrutura de visão empacotada resolvem o mesmo problema em um nível mais alto. O primeiro pode fornecer a um LLM uma árvore de papéis, rótulos e estados construídos a partir de a árvore de acessibilidade WAI-ARIA, em vez de pixels, que é mais barato e mais exato em uma página com marcação limpa. O Uso do Navegador em execução no Navegador de Raspagem segue esse caminho — ele utiliza o mesmo Chromium em nuvem sobre a mesma conexão CDP, mas seu agente raciocina sobre o texto extraído da página, não uma imagem.

O outro atalho entrega todo o laço a uma estrutura de visão empacotada, que captura tela, raciocina e age da mesma forma que este walkthrough faz, exceto que o prompt, o esquema de ação e o código de decisão vivem dentro da biblioteca, em vez de no script de chamada.

Cada parte de uma decisão personalizada permanece visível e editável: o vocabulário de ação, o prompt que solicita uma ação, o limite de etapas e a linha que transforma a decisão em uma chamada do Playwright. Um objetivo, alvo ou modelo diferente muda uma parte do script em vez de uma superfície de configuração em toda a estrutura.

Pré-requisitos

Você precisa do Python 3.9 ou mais recente, dos pacotes playwright e requests, uma chave de API Scrapeless para a sessão do navegador e uma chave para um modelo com capacidade de visão. Obtenha a chave Scrapeless no plano gratuito em app.scrapeless.com. O exemplo abaixo roteia chamadas de modelo através do OpenRouter, que conecta vários provedores de modelo atrás de uma chave e um endpoint.

Configurar o Projeto

Instalar as Dependências

pip install playwright requests

Configurar as Chaves da API

export SCRAPELESS_API_KEY="sua_chave_api_scrapeless"

export OPENROUTER_API_KEY="sua_chave_api_do_modelo"

## Construir o Loop Perceber-Decidir-Agir

O script completo conecta um navegador remoto, define um contrato de quatro ações e executa o contrato até que o modelo retorne `feito` ou o limite de passos seja alcançado.

### Conectar ao Navegador Remoto

O Scraping Browser expõe um endpoint CDP através de uma conexão WebSocket — <a href="https://datatracker.ietf.org/doc/html/rfc6455" rel="nofollow"><strong>o protocolo WebSocket</strong></a> transporta o tráfego <a href="https://chromedevtools.github.io/devtools-protocol/" rel="nofollow"><strong>do Protocolo DevTools do Chrome</strong></a> em ambas as direções. O `connect_over_cdp` do Playwright se conecta a esse endpoint da mesma forma que se conectaria a uma instância local do Chromium iniciada com uma porta de depuração aberta; o próprio navegador roda na nuvem do Scrapeless, e não na máquina que executa este script. O [guia de proxy do Playwright](https://www.scrapeless.com/pt/blog/playwright-proxy?utm_source=website&utm_medium=blog&utm_campaign=scrapingbrowser&utm_term=computer-use-browser-agent-loop) cobre o mesmo padrão de conexão remota-CDP em mais detalhes.

### Definir o Contrato de Decisão

Três funções abrangem as três partes do loop: `perceive` tira a captura de tela, `decide` a envia para o modelo e analisa a resposta, e `act` transforma essa resposta em uma chamada do Playwright. O prompt pede ao modelo para preencher um pequeno <a href="https://datatracker.ietf.org/doc/html/rfc8259" rel="nofollow"><strong>objeto JSON</strong></a> em uma ordem de campo fixo — nomear um fato concreto da imagem antes de escolher uma ação mantém a decisão fundamentada no que a captura de tela realmente mostra, em vez de um palpite aberto sobre se o objetivo foi alcançado:

### Executar o Exemplo Completo

```python
import os
import json
import base64
import requests
from urllib.parse import urlencode
from playwright.sync_api import sync_playwright

GOAL = (
    'Objetivo: chegar a uma página onde o PRIMEIRO cartão de citação não é escrito por "Albert Einstein". '
    'Leia o nome do autor no primeiro cartão de citação. Se for "Albert Einstein", clique no '
    '"link de paginação Próximo". Caso contrário, o objetivo já está completo.'
)
SCHEMA_PROMPT = (
    GOAL + "\n\nResponda com APENAS um objeto JSON, preenchendo todos os campos na ordem:\n"
    '{"first_quote_author": "<o nome do autor no primeiro cartão de citação, lido da imagem>", '
    '"action": "click" | "type" | "scroll" | "done", '
    '"target": "<texto visível do elemento a clicar ou digitar, omita para scroll/done>", '
    '"value": "<texto a digitar, apenas quando a ação for digitar>", '
    '"reason": "<menos de 8 palavras>"}'
)


def browser_url():
    return "wss://browser.scrapeless.com/api/v2/browser?" + urlencode(
        {"token": os.environ["SCRAPELESS_API_KEY"], "sessionTTL": 180, "proxyCountry": "US"})


def perceive(page):
    return page.screenshot(full_page=True)


def decide(png_bytes):
    img = "data:image/png;base64," + base64.b64encode(png_bytes).decode()
    resp = requests.post(
        "https://openrouter.ai/api/v1/chat/completions",
        headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}", "Content-Type": "application/json"},
        json={"model": "google/gemini-2.5-flash-lite",
              "messages": [{"role": "user", "content": [
                  {"type": "text", "text": SCHEMA_PROMPT},
                  {"type": "image_url", "image_url": {"url": img}}]}],
              "temperature": 0, "max_tokens": 300},
        timeout=120,
    )
    resp.raise_for_status()
    return json.loads(resp.json()["choices"][0]["message"]["content"])


def act(page, decision):
    action = decision["action"]
    if action == "click":
        page.get_by_text(decision["target"], exact=False).first.click(timeout=5000)
        page.wait_for_load_state("networkidle")
    elif action == "type":
        page.get_by_text(decision["target"], exact=False).first.fill(decision["value"], timeout=5000)
    elif action == "scroll":
        page.mouse.wheel(0, 900)
        page.wait_for_timeout(300)
    return action


with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url())
    page = browser.new_page(viewport={"width": 1280, "height": 900})
    page.goto("https://quotes.toscrape.com/", wait_until="networkidle")

    max_steps = 4
    for step in range(1, max_steps + 1):
        decision = decide(perceive(page))
        print(f"passo {step}: autor={decision['first_quote_author']!r} "
              f"ação={decision['action']} razão={decision['reason']!r}")
        if decision["action"] == "done":
            break
        act(page, decision)

    print("url final:", page.url)
    print("passos realizados:", step)
    browser.close()

Obtenha sua chave de API no plano gratuito: app.scrapeless.com

Verificar a Execução

Contra a página ao vivo, o exemplo navegou uma vez e parou na próxima iteração:

etapa 1: autor='Albert Einstein' ação=clicar razão='O autor da primeira citação é Albert Einstein, é necessário clicar em seguir.'
etapa 2: autor='Marilyn Monroe' ação=feito razão='A primeira citação não é de Albert Einstein.'
url final: https://quotes.toscrape.com/page/2/
passos dados: 2

Rastrear a Decisão de Duas Etapas

O rastreamento mostra por que o loop precisa de uma captura de tela atualizada após cada ação.

Etapa 1: Ler o Primeiro Cartão e Clicar em Seguir

A Etapa 1 captura a tela da página inicial, e o modelo lê "Albert Einstein" do primeiro cartão de citação — um fato que qualquer um olhando a mesma imagem confirmaria — e retorna {"action": "click", "target": "Next →"}. A função act resolve esse alvo com page.get_by_text("Next →", exact=False), o mesmo padrão de localizador que um script escrito diretamente contra o DOM usaria, e clica nele. O clique navega para /page/2/.

Etapa 2: Confirmar o Novo Estado e Parar

A Etapa 2 captura a nova página. O primeiro cartão de citação agora pertence a Marilyn Monroe, o modelo relata esse fato, e a ação que ele retorna é feito. O loop sai por conta própria após duas das quatro etapas alocadas — ele nunca precisou atingir o limite, e nunca precisou da ação de rolar também, porque perceive captura a página inteira em uma imagem em vez de apenas a área visível. Para uma página que carrega mais conteúdo à medida que o usuário rola — rolagem infinita, seções carregadas sob demanda — uma captura de página completa não consegue ver conteúdo que ainda não foi carregado, razão pela qual scroll permanece no vocabulário de ações, mesmo que este alvo nunca o acione. O ramo type funciona da mesma maneira, preenchendo qualquer elemento que corresponda ao target com value; o objetivo deste guia nunca precisa de um campo de formulário, então esse ramo executa a lógica de despacho idêntica sem que essa execução específica o exerça.

Manter o Loop Limitado e Atual

Duas escolhas de design impedem que um loop como este se desvie. O limite max_steps significa que um modelo que nunca retorna feito ainda para por conta própria, e um ciclo de captura de tela mais uma decisão única significa que o loop nunca age com informações obsoletas — cada decisão é tomada contra a página como ela existe naquele momento, não contra uma suposição sobre o que mudou desde a última visão.

Escolha a Forma de Agente de Navegador Certa

A abordagem certa depende de o tarefa precisar de uma observação ou várias e se você precisa inspecionar a lógica de decisão.

Uma chamada de visão única lê uma captura de tela e retorna dados estruturados sem tomar uma ação. O que um scraper LLM faz cobre o padrão de extração mais amplo. Use essa forma quando a tarefa é simplesmente ler um valor.

O loop personalizado é para objetivos que exigem mais de uma visão para serem satisfeitos. Cada captura de tela depende da ação anterior e a lógica de decisão exata permanece em um código que pode ser inspecionado e alterado.

Um framework de agente empacotado envolve o mesmo loop — ou uma variante baseada em texto dele, no caso do Uso de Navegador — atrás de um executor de tarefas. Essa troca é útil uma vez que a forma do loop se estabilizou e o trabalho principal é executar muitos objetivos contra muitas páginas.

Conclusão: Mantenha o Loop Pequeno e Observável

A mecânica por trás de um agente "uso de computador" é uma captura de tela, uma chamada de modelo de visão restrita a uma lista curta de ações e um comando de navegador que executa o resultado. O ciclo se repete até que o modelo reporte que o objetivo foi alcançado ou um limite de etapa seja atingido.

A execução acima levou duas voltas para passar de uma página apresentada por Albert Einstein para uma apresentada por Marilyn Monroe. A decisão do modelo permaneceu visível a cada passo, e a chamada Playwright que a executou continuou sendo código de aplicação comum.

Leia o que o tempo de execução oferece na página do produto Scraping Browser e pese a contagem de etapas em relação ao custo do modelo na página de preços antes de escalar um loop como este além de um punhado de objetivos.

Pronto para Construir um Loop de Agente de Navegador?

Junte-se à nossa comunidade para reivindicar um plano gratuito e comparar notas com outros desenvolvedores que estão construindo agentes de navegador: Discord · Telegram.

Inscreva-se em app.scrapeless.com para obter a execução gratuita do Scraping Browser e adaptar o loop delimitado a uma página pública e a um objetivo que você pode verificar passo a passo.

FAQ

P: O que é um loop de agente de navegador no estilo de uso de computador?

Um loop de agente de navegador no estilo de uso de computador é um ciclo de três etapas repetidas até que um objetivo seja alcançado: perceber a página com uma captura de tela, decidir uma ação enviando essa captura de tela para um modelo capaz de visão e agir executando essa decisão com um comando de navegador real. A ferramenta de Uso de Computador da OpenAI e o pacote de modo de uso de computador do Google Gemini encapsulam o mesmo ciclo por trás de uma API hospedada.

P: Como isso é diferente de executar Skyvern ou Browser Use no mesmo navegador?

Essas estruturas executam o mesmo tipo de loop internamente, mas o prompt, o esquema de ação e o código de decisão estão contidos na biblioteca. Este guia escreve essas três partes diretamente, de modo que cada parte da decisão é visível e editável no script de chamada, em vez de estar na superfície de configuração de uma estrutura.

P: Como isso é diferente de uma única chamada de extração de captura de tela para JSON?

Uma única chamada de visão lê uma imagem e retorna dados, sem ação tomada e sem loop. Este guia repete perceber, decidir e agir até que o modelo informe que o objetivo foi alcançado, e a captura de tela de cada etapa reflete o resultado da ação da etapa anterior.

P: Por que restringir a resposta do modelo a um esquema de ação fixo em vez de instruções livres?

Um vocabulário pequeno e fixo — clicar, digitar, rolar, feito — transforma a resposta do modelo em algo que o código de chamada pode despachar de forma determinística com uma cadeia if/elif. Uma resposta não restrita precisaria de sua própria camada de análise e interpretação antes que pudesse dirigir um navegador com segurança.

P: Por que o loop pede ao modelo que nomeie um fato concreto antes de escolher uma ação?

Pedir ao modelo que declare um detalhe verificável da imagem — o autor no primeiro cartão, neste exemplo — mantém a ação ancorada no que a captura de tela realmente mostra. Um campo que pede ao modelo para raciocinar abertamente sobre se o objetivo foi alcançado é mais propenso a se desviar da imagem à sua frente.

P: Por que tirar uma captura de tela de página inteira em vez de apenas da área visível?

Para que o modelo possa ver elementos abaixo da dobra, como um link de paginação na parte inferior de uma longa lista, sem uma etapa de rolagem dedicada primeiro. Uma página que carrega mais conteúdo apenas à medida que o usuário rola — rolagem infinita ou seções carregadas sob demanda — é o caso em que uma captura de página inteira fica aquém e a ação de rolagem ganha seu lugar no loop.

P: Por que limitar o número de etapas?

max_steps limita quantos ciclos perceber-decidir-agir um único objetivo pode executar, de modo que um modelo que nunca retorna feito ainda pare em vez de agir indefinidamente. Cada etapa é uma captura de tela e uma chamada de modelo, então o limite também controla o custo da execução.

P: Qual modelo de visão o exemplo usa, e outro modelo pode substituí-lo?

O exemplo roteia para google/gemini-2.5-flash-lite através do OpenRouter. Qualquer modelo capaz de visão acessível através do mesmo formato de chat-completions pode substituí-lo alterando o campo modelo.

P: É seguro apontar um loop como este para um site real?

Sim, quando o alvo é público, a contagem de etapas é limitada e o objetivo exclui logins, pagamentos e dados privados. O exemplo acima executa duas etapas limitadas contra um site público de citações construído para prática de raspagem.