Construir un bucle de agente de navegador para computadora desde cero

Resumen:

• Un agente de uso de computadora se puede reducir a un ciclo percibir-decidir-actuar limitado. El navegador captura la página actual, un modelo de visión elige una acción y Playwright la ejecuta antes de que el ciclo comience de nuevo.
• El esquema de acción mantiene la salida del modelo ejecutable. Restringir cada decisión a click, type, scroll o done convierte la respuesta del modelo en un pequeño despachador determinista.
• Capturas de pantalla frescas evitan decisiones obsoletas. Cada llamada al modelo ve la página después de la acción anterior, por lo que el agente razona a partir del estado actual del navegador.
• Un límite de pasos controla tanto la autonomía como el costo. El ejemplo permite un máximo de cuatro iteraciones y termina en dos: hacer clic en Siguiente, confirmar la nueva primera cita, y luego parar.
• Un ciclo personalizado es mejor cuando la lógica de decisión necesita permanecer visible. Utiliza una sola llamada de visión para extracción de una sola vez y un agente empaquetado cuando el ciclo ya no necesita ajustes frecuentes.
• Gratis para empezar. Las nuevas cuentas de Scrapeless incluyen tiempo de ejecución gratuito del Navegador de Scraping — regístrate en app.scrapeless.com.

Introducción: El Pequeño Ciclo Detrás del Uso de la Computadora

Un agente de uso de computadora hace tres cosas en repetición: mira la pantalla, decide una acción y ejecuta esa acción. Productos como la herramienta de Uso de Computadora de OpenAI y el modo de uso de computadora Gemini de Google empaquetan ese ciclo detrás de una sola llamada API. Los marcos de agentes como Skyvern lo agrupan detrás de un ejecutor de tareas. Debajo de cualquiera de los dos, el ciclo en sí es una pequeña cantidad de código: una captura de pantalla, una llamada a un modelo de visión restringido a una lista corta de acciones y un comando del navegador que realiza lo que el modelo eligió.

Esta guía escribe ese ciclo directamente, sin un agente empaquetado entre medio. Se conecta al Navegador de Scraping de Scrapeless a través del Protocolo DevTools de Chrome, captura la página, envía la imagen a un modelo capaz de visión con cuatro opciones — clic, escribir, desplazarse o hecho — y ejecuta lo que el modelo devuelve con Playwright, y luego repite. Cada paso a continuación se ejecuta contra una página real, capturando las decisiones reales del modelo a medida que sucedieron.

El Ciclo a Primera Vista

Cada iteración tiene una fuente de verdad: la página tal como aparece en la última captura de pantalla.

La demostración utiliza un sitio público de citas y un objetivo estrecho: salir de la primera página solo cuando la primera cita sea escrita por Albert Einstein, luego detenerse tan pronto como aparezca un autor diferente.

¿Por Qué Construir el Ciclo Tú Mismo?

Escribir el ciclo directamente te da control sobre el formato de percepción, el vocabulario de acciones y la regla de parada.

Un agente de instantánea estructurada y un marco de visión empaquetado resuelven el mismo problema a un nivel más alto. El primero puede entregar a un LLM un árbol de roles, etiquetas y estados construidos a partir de el árbol de accesibilidad WAI-ARIA en lugar de píxeles, lo cual es más barato y más exacto en una página con un marcado limpio. El uso del navegador que se ejecuta en el Navegador de Scraping sigue ese camino: controla el mismo Chromium en la nube a través de la misma conexión CDP, pero su agente razona sobre el texto de la página extraído, no sobre una imagen.

El otro atajo entrega todo el ciclo a un marco de visión empaquetado, que toma capturas de pantalla, razona y actúa de la misma manera que esta demostración, excepto que el prompt, el esquema de acción y el código de decisión viven dentro de la biblioteca en lugar de en el script de llamada.

Cada parte de una decisión personalizada permanece visible y editable: el vocabulario de acción, el prompt que solicita una acción, el límite de pasos y la línea que convierte la decisión en una llamada a Playwright. Un objetivo, destino o modelo diferente cambia una parte del script en lugar de una superficie de configuración a nivel de marco.

Requisitos Previos

Necesitas Python 3.9 o superior, los paquetes playwright y requests, una clave API de Scrapeless para la sesión del navegador, y una clave para un modelo capaz de visión. Obtén la clave de Scrapeless en el plan gratuito en app.scrapeless.com. El ejemplo a continuación enruta las llamadas al modelo a través de OpenRouter, que actúa como intermediario de varios proveedores de modelos detrás de una sola clave y un solo punto de entrada.

Configurar el Proyecto

Instalar las Dependencias

pip install playwright requests

Configurar las Claves API

export SCRAPELESS_API_KEY="tu_clave_api_de_scrapeless"

export OPENROUTER_API_KEY="tu_model_api_key"

Construir el bucle Perceber–Decidir–Actuar

El script completo conecta un navegador remoto, define un contrato de cuatro acciones y ejecuta el contrato hasta que el modelo devuelve done o se alcanza el límite de pasos.

Conectar al Navegador Remoto

El Navegador de Scraping expone un endpoint CDP sobre una conexión WebSocket — el protocolo WebSocket transporta tráfico de Chrome DevTools Protocol en ambas direcciones. El método connect_over_cdp de Playwright se conecta a ese endpoint de la misma manera que lo haría con una instancia local de Chromium iniciada con un puerto de depuración abierto; el navegador en sí se ejecuta en la nube de Scrapeless, no en la máquina que ejecuta este script. La guía de proxy de Playwright cubre el mismo patrón de conexión remota-CDP con más detalle.

Definir el Contrato de Decisión

Tres funciones llevan las tres partes del bucle: perceive toma la captura de pantalla, decide la envía al modelo y analiza la respuesta, y act convierte esa respuesta en una llamada de Playwright. La solicitud pide al modelo que complete un pequeño objeto JSON en un orden de campos fijo — nombrar un hecho concreto de la imagen antes de elegir una acción mantiene la decisión enraizada en lo que la captura de pantalla realmente muestra, en lugar de en una suposición abierta sobre si se ha cumplido el objetivo:

Ejecutar el Ejemplo Completo

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

GOAL = (
    'Objetivo: llegar a una página donde la PRIMERA tarjeta de cita no esté escrita por "Albert Einstein". '
    'Leer el nombre del autor en la primera tarjeta de cita. Si es "Albert Einstein", hacer clic en el '
    '"siguiente" enlace de paginación. De lo contrario, el objetivo ya está completo.'
)
SCHEMA_PROMPT = (
    GOAL + "\n\nResponde con UNICAMENTE un objeto JSON, llenando cada campo en orden:\n"
    '{"first_quote_author": "<el nombre del autor en la primera tarjeta de cita, leído de la imagen>", '
    '"action": "click" | "type" | "scroll" | "done", '
    '"target": "<texto visible del elemento a hacer clic o escribir, omitir para scroll/done>", '
    '"value": "<texto a escribir, solo cuando la acción sea escribir>", '
    '"reason": "<menos de 8 palabras>"}'
)


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"paso {step}: autor={decision['first_quote_author']!r} "
              f"acción={decision['action']} razón={decision['reason']!r}")
        if decision["action"] == "done":
            break
        act(page, decision)

    print("URL final:", page.url)
    print("pasos tomados:", step)
    browser.close()

Obtén tu clave API en el plan gratuito: app.scrapeless.com

Verificar la Ejecución

Contra la página en vivo, el ejemplo navegó una vez y se detuvo en la siguiente iteración:

paso 1: autor='Albert Einstein' acción=hacer clic razón='El primer autor de la cita es Albert Einstein, necesita hacer clic en siguiente.'
paso 2: autor='Marilyn Monroe' acción=hecho razón='La primera cita no es de Albert Einstein.'
URL final: https://quotes.toscrape.com/page/2/
pasos tomados: 2

Rastrear la Decisión de Dos Pasos

El rastreo muestra por qué el bucle necesita una captura de pantalla fresca después de cada acción.

Paso 1: Leer la Primera Tarjeta y Hacer Clic en Siguiente

El paso 1 captura la pantalla de la página principal, y el modelo lee "Albert Einstein" de la primera tarjeta de cita — un hecho que cualquier persona que mire la misma imagen confirmaría — y devuelve {"acción": "hacer clic", "objetivo": "Siguiente →"}. La función act resuelve ese objetivo con page.get_by_text("Siguiente →", exact=False), el mismo patrón de localizador que un script escrito contra el DOM usaría directamente, y hace clic en él. El clic navega a /page/2/.

Paso 2: Confirmar el Nuevo Estado y Detenerse

El paso 2 captura la pantalla de la nueva página. La primera tarjeta de cita ahora pertenece a Marilyn Monroe, el modelo informa de ese hecho, y la acción que devuelve es hecho. El bucle sale por sí mismo después de dos de los cuatro pasos asignados — nunca necesitó alcanzar el límite, y nunca necesitó la acción de desplazamiento tampoco, porque perceive captura la página completa en una imagen en lugar de solo el área visible. Para una página que carga más contenido a medida que el usuario se desplaza — desplazamiento infinito, secciones de carga perezosa — una captura de pantalla completa no puede ver contenido que no se ha cargado todavía, razón por la cual scroll permanece en el vocabulario de acciones aunque este objetivo nunca lo active. La rama type funciona de la misma manera, llenando cualquier elemento que coincida con target con value; el objetivo de este recorrido nunca necesita un campo de formulario, por lo que esa rama ejecuta la lógica de despacho idéntica sin que esta ejecución particular la ejercite.

Mantener el Bucle Limitado y Actual

Las dos elecciones de diseño evitan que un bucle como este se descontrole. El límite max_steps significa que un modelo que nunca devuelve hecho aún se detiene por sí mismo, y un ciclo de captura de pantalla más una única decisión significa que el bucle nunca actúa sobre información obsoleta — cada decisión se toma contra la página tal como existe en ese momento, no contra una suposición sobre lo que ha cambiado desde la última revisión.

Elegir la Forma Correcta del Agente del Navegador

El enfoque correcto depende de si la tarea necesita una observación o varias y de si necesitas inspeccionar la lógica de decisión.

Una llamada a visión única lee una captura de pantalla y devuelve datos estructurados sin tomar una acción. Lo que hace un scraper LLM cubre el patrón de extracción más amplio. Usa esa forma cuando la tarea sea simplemente leer un valor.

El bucle personalizado es para objetivos que requieren más de una mirada para satisfacerse. Cada captura de pantalla depende de la acción anterior, y la lógica de decisión exacta permanece en un código que se puede inspeccionar y modificar.

Un marco de agente empaquetado envuelve el mismo bucle — o una variante basada en texto de él, en el caso de Uso del Navegador — detrás de un ejecutor de tareas. Ese intercambio es útil una vez que la forma del bucle se ha estabilizado y el trabajo principal consiste en ejecutar muchos objetivos en muchas páginas.

Conclusión: Mantener el Bucle Pequeño y Observable

La mecánica detrás de un agente de "uso de computadora" es una captura de pantalla, una llamada al modelo de visión limitada a una breve lista de acciones, y un comando del navegador que lleva a cabo el resultado. El ciclo se repite hasta que el modelo informa que el objetivo se ha cumplido o se alcanza un límite de pasos.

La ejecución anterior tomó dos turnos para pasar de una página frente a Albert Einstein a una frente a Marilyn Monroe. La decisión del modelo se mantuvo visible en cada paso, y la llamada de Playwright que la ejecutó siguió siendo código de aplicación ordinario.

Lee lo que ofrece el tiempo de ejecución en la página del producto Scraping Browser y pesa el recuento de pasos contra el costo del modelo en la página de precios antes de escalar un bucle como este más allá de un puñado de objetivos.

¿Listo para Construir un Bucle de Agente del Navegador?

Únete a nuestra comunidad para reclamar un plan gratuito y comparar notas con otros desarrolladores que construyen agentes del navegador: Discord · Telegram.

Regístrate en app.scrapeless.com para obtener un tiempo de ejecución gratuito del Scraping Browser y adaptar el bucle limitado a una página pública y un objetivo que puedas verificar paso a paso.

Preguntas frecuentes

P: ¿Qué es un bucle de agente del navegador de estilo de uso informático?

Un bucle de agente del navegador de estilo de uso informático es un ciclo de tres pasos repetidos hasta que se alcanza un objetivo: percibir la página con una captura de pantalla, decidir una acción enviando esa captura a un modelo capaz de visión, y actuar ejecutando esa decisión con un comando de navegador real. La herramienta de Uso Informático de OpenAI y el modo de uso informático de Gemini de Google empaquetan el mismo ciclo detrás de una API hospedada.

P: ¿En qué se diferencia esto de ejecutar Skyvern o Browser Use en el mismo navegador?

Esos marcos ejecutan el mismo tipo de bucle internamente, pero el aviso, el esquema de acción y el código de decisión viven dentro de la biblioteca. Este recorrido escribe esas tres piezas directamente, así que cada parte de la decisión es visible y editable en el script de llamada en lugar de en la superficie de configuración de un marco.

P: ¿En qué se diferencia esto de una llamada de extracción de captura de pantalla a JSON?

Una única llamada de visión lee una imagen y devuelve datos, sin que se tome ninguna acción y sin bucle. Este recorrido repite percibir, decidir y actuar hasta que el modelo informa que se ha alcanzado el objetivo, y la captura de pantalla de cada paso refleja el resultado de la acción del paso anterior.

P: ¿Por qué restringir la respuesta del modelo a un esquema de acción fijo en lugar de instrucciones en forma libre?

Un vocabulario pequeño y fijo — clic, escribir, desplazar, hecho — convierte la respuesta del modelo en algo que el código de llamada puede despachar de manera determinística con una cadena de if/elif. Una respuesta sin restricciones necesitaría su propia capa de análisis e interpretación antes de que pudiera conducir de manera segura un navegador.

P: ¿Por qué el bucle pide al modelo que nombre un hecho concreto antes de elegir una acción?

Pedir al modelo que declare un detalle verificable de la imagen — el autor en la primera tarjeta, en este ejemplo — mantiene la acción fundamentada en lo que la captura de pantalla realmente muestra. Un campo que pide al modelo razonar abiertamente sobre si se ha alcanzado el objetivo es más propenso a desviarse de la imagen que tiene frente a sí.

P: ¿Por qué tomar una captura de pantalla de toda la página en lugar de solo el área visible?

Para que el modelo pueda ver elementos por debajo del pliegue, como un enlace de paginación en la parte inferior de una lista larga, sin un paso de desplazamiento dedicado primero. Una página que carga más contenido solo cuando el usuario se desplaza — desplazamiento infinito o secciones cargadas de manera perezosa — es el caso en el que una captura de toda la página se queda corta y la acción de desplazamiento se gana su lugar en el bucle.

P: ¿Por qué limitar el número de pasos?

max_steps limita cuántos ciclos de percibir-decir-actuar puede realizar un solo objetivo, de modo que un modelo que nunca devuelve hecho se detiene en lugar de actuar indefinidamente. Cada paso es una captura de pantalla y una llamada de modelo, por lo que el límite también restringe el costo de la ejecución.

P: ¿Qué modelo de visión utiliza el ejemplo, y puede otro modelo reemplazarlo?

El ejemplo se dirige a google/gemini-2.5-flash-lite a través de OpenRouter. Cualquier modelo capaz de visión accesible a través de la misma forma de completado de chat puede reemplazarlo cambiando el campo modelo.

P: ¿Es seguro apuntar un bucle como este a un sitio real?

Sí, cuando el objetivo es público, el conteo de pasos está limitado y el objetivo excluye inicios de sesión, pagos y datos privados. El ejemplo anterior ejecuta dos pasos limitados contra un sitio de citas público construido para la práctica de scraping.