> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/es/agent-browser.md).

# Agent Browser

Un navegador sin interfaz basado en la nube con seguridad adaptativa integrada, gestión de CAPTCHA y Residential Proxies. Pruébalo con ejemplos de código y personalízalo con funciones avanzadas.

Agent Browser te permite ejecutar y controlar instancias remotas para automatización basada en navegador, pruebas y web scraping sin gestionarlas localmente. Ofrece seguridad adaptativa integrada, gestión automática de CAPTCHA, geolocalización, proxies residenciales integrados, grabación de sesiones, sesiones persistentes y perfiles persistentes.

## Bibliotecas compatibles

Agent Browser funciona con cualquier biblioteca que admita el **Chrome DevTools Protocol (CDP)**, incluidas:

* [Playwright](https://playwright.dev/) (Python y Node.js)
* [Puppeteer](https://pptr.dev/) (Node.js)
* Frameworks de agentes de IA como [Stagehand](https://github.com/browserbase/stagehand) y [browser-use](https://github.com/browser-use/browser-use). Consulta [Integración de CDP](https://developers.oxylabs.io/products/es/agent-browser/integracion-cdp.md).
* Otros frameworks de automatización compatibles con CDP

## Detalles de conexión

<table><thead><tr><th width="161">Campo</th><th>Descripción</th></tr></thead><tbody><tr><td><strong>Protocolo</strong></td><td><code>wss://</code> (WebSocket seguro)</td></tr><tr><td><strong>Host (Chromium)</strong></td><td><code>hb.oxylabs.io</code></td></tr><tr><td><strong>Autenticación</strong></td><td>En la URL, la información de usuario – <code>wss://USERNAME:PASSWORD@host</code>. Debe incluir el token de sufijo del nombre de usuario (p. ej., <code>user_ab12</code>). Crear <code>Autorización</code> encabezados personalizados no se recomienda.</td></tr><tr><td><strong>Transporte</strong></td><td>CDP – <code>chromium.connectOverCDP</code> (Playwright) / <code>puppeteer.connect</code> (Puppeteer).</td></tr><tr><td><strong>Dominio</strong></td><td><code>oxylabs.io</code> – se usa para los endpoints de conexión (p. ej. <a href="http://hb.oxylabs.io">hb.oxylabs.io</a>), el Dashboard (<a href="http://hb.oxylabs.io/dashboard">hb.oxylabs.io/dashboard</a>), y la inspección de sesión (<a href="http://hb.oxylabs.io/novnc">hb.oxylabs.io/novnc</a>).</td></tr><tr><td><strong>Límites de velocidad</strong></td><td><code>100</code> sesiones concurrentes, <code>10</code> sesión por segundo. <a href="#need-a-feature-enabled-1">Ver más</a>.</td></tr></tbody></table>

## Características

Oxylabs Agent Browser incluye funciones integradas y nativas de la nube diseñadas para usarse mediante parámetros de consulta en tu URL de conexión WebSocket.

<table data-header-hidden><thead><tr><th width="250"></th><th></th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/manejador-de-paginas.md"><strong>Manejador de páginas</strong></a></td><td>Identifica cada página, gestiona los desafíos compatibles y rastrea el estado de la página (predeterminado – desactivado).</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/captcha-handling.md"><strong>Gestión de CAPTCHA</strong></a></td><td>Identifica páginas y gestiona automáticamente los desafíos de acceso (predeterminado – desactivado).</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/motor-y-huellas-digitales.md"><strong>Motor y huellas digitales</strong></a></td><td>Selecciona el motor del navegador y los perfiles de fingerprint.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/geolocation-and-proxy-selection.md"><strong>Enrutamiento de proxy y geolocalización</strong></a></td><td>Enruta las sesiones a través de países, estados o ciudades específicas.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/device-type.md"><strong>Emulación de dispositivo</strong></a></td><td>Emula fingerprints y viewports específicos del dispositivo.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/session-inspection-and-recording.md#session-inspection-vnc"><strong>Inspección de sesión (VNC)</strong></a></td><td>Supervisa sesiones en vivo de un navegador sin interfaz.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/session-inspection-and-recording.md#session-recording"><strong>Grabación de sesión</strong></a></td><td>Graba sesiones del navegador en formato de video.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/persistent-sessions-and-profiles.md#persistent-sessions"><strong>Sesiones persistentes</strong></a></td><td>Crea y administra instancias persistentes del navegador.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/persistent-sessions-and-profiles.md#persistent-profiles"><strong>Perfiles persistentes</strong></a></td><td>Guarda y restaura cookies/localStorage entre sesiones.</td></tr></tbody></table>

{% hint style="success" %}
**¿Usas un asistente de programación con IA?** Configura [Habilidades del agente](https://developers.oxylabs.io/ai-workflows/es/habilidades-de-agente.md) o el [servidor MCP](https://developers.oxylabs.io/ai-workflows/es/mcp.md).
{% endhint %}

### Pasar parámetros

Todas las funciones se habilitan y configuran agregando parámetros de consulta directamente a tu endpoint WebSocket Secure, encadenando varias funciones con ampersands (`&`).

```bash
# Ejemplo: conexión a Chrome con geolocalización en EE. UU. y gestión de CAPTCHA activada
wss://USER:PASS@hb.oxylabs.io?p_cc=US&solve_captcha=true
```

## Integraciones

<table data-header-hidden><thead><tr><th width="154.5"></th><th></th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/es/agent-browser/integracion-cdp.md"><strong>Integración de CDP</strong></a></td><td>Conecta Stagehand y browser-use para abrir la inspección de sesión en vivo.</td></tr><tr><td><a href="https://developers.oxylabs.io/ai-workflows/es/habilidades-de-agente.md"><strong>Habilidades del agente</strong></a></td><td>Configura Agent Browser en Claude Code, Cursor y otros asistentes de programación con IA.</td></tr><tr><td><a href="https://developers.oxylabs.io/ai-workflows/es/mcp.md"><strong>Servidor MCP</strong></a></td><td>Proporciona a los asistentes de IA compatibles con MCP un Agent Browser remoto.</td></tr></tbody></table>

## Ejemplos de código

A continuación se muestran ejemplos básicos para inicializar una sesión de navegador alojada en la nube:

{% tabs %}
{% tab title="Python (Playwright)" %}

```python
from playwright.sync_api import sync_playwright

username = "USERNAME" # include any account suffix
password = "PASSWORD"
endpoint = "hb.oxylabs.io"
browser_url = f"wss://{username}:{password}@{endpoint}?p_cc=US"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url)
    page = browser.new_page()
    page.goto("https://ip.oxylabs.io/location")
    print(page.title())
    browser.close()
```

{% endtab %}

{% tab title="JavaScript (Playwright)" %}

```javascript
process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import { chromium } from "playwright";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();
```

{% endtab %}

{% tab title="JavaScript (Puppeteer)" %}

```javascript
process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import puppeteer from "puppeteer";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: browserUrl });
    const page = await browser.newPage();
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Nota:** Los ejemplos usan `USERNAME` y `PASSWORD` solo para facilitar la lectura. En proyectos reales, cárgalos desde variables de entorno (p. ej., `process.env.OXYLABS_USERNAME` / `process.env.OXYLABS_PASSWORD`) mediante un `.env` archivo.
{% endhint %}

{% hint style="warning" %}
**JavaScript:** Use `NODE_TLS_REJECT_UNAUTHORIZED="0"` activa la bandera antes de requerir Playwright en Node.js si encuentras errores de TLS/certificado. Solo para pruebas locales. En producción, limita la confianza a la conexión específica o añade el certificado CA del proveedor a tu almacén de confianza en su lugar.
{% endhint %}

## Referencia de parámetros <a href="#need-a-feature-enabled" id="need-a-feature-enabled"></a>

<table><thead><tr><th width="184">Parámetro</th><th width="467">Descripción</th><th>Tipo</th></tr></thead><tbody><tr><td><code>p_cc</code></td><td>Geolocalización por país en <code>ISO 3166-1 alpha-2</code> código de 2 letras (p. ej., <code>US</code>, <code>DE</code>).</td><td>cadena</td></tr><tr><td><code>p_state</code></td><td>Geolocalización por estado en minúsculas (p. ej., <code>texas</code>). Sobrescribe <code>p_cc</code> si se usan ambos. <a href="https://content.gitbook.com/content/BQ7Zf9paoN3FTeGcyfY1/blobs/cVjpiu1GKicluiVIT9og/us_states.txt">Lista de estados compatibles</a>.</td><td>cadena</td></tr><tr><td><code>p_city</code></td><td>Geolocalización por ciudad, en minúsculas, <code>_</code> para espacios (p. ej., <code>new_york</code>). <code>p_cc</code> / <code>p_state</code> requerido.</td><td>cadena</td></tr><tr><td><code>p_device</code></td><td>Configura fingerprints del dispositivo, viewports y user-agents. Admite <code>escritorio</code> (predeterminado) y <code>búsqueda</code>.</td><td>cadena</td></tr><tr><td><code>p_src</code></td><td>Motor del navegador. Admite <code>oxybrowser</code> motor propietario. Si se omite, se usa el motor estándar. Ver <a href="https://developers.oxylabs.io/products/es/agent-browser/motor-y-huellas-digitales.md">Motor y huellas digitales</a>.</td><td>cadena</td></tr><tr><td><code>p_fp_tag</code></td><td>Perfil de fingerprint: <code>oxyfp_win</code> (predeterminado), <code>oxyfp_mac</code>, <code>oxyfp_mac_optimized</code> (solo con <code>p_src=oxybrowser</code>), <code>oxyfp_win_v1</code> (heredado). Ver <a href="https://developers.oxylabs.io/products/es/agent-browser/motor-y-huellas-digitales.md">Motor y huellas digitales</a>.</td><td>cadena</td></tr><tr><td><code>page_handler</code></td><td>Identifica páginas y gestiona automáticamente los desafíos de acceso. Predeterminado: <code>false</code>. Consulta <a href="https://developers.oxylabs.io/products/es/agent-browser/manejador-de-paginas.md">Manejador de páginas</a>.</td><td>booleano</td></tr><tr><td><code>solve_captcha</code></td><td>Resolución automática de CAPTCHA en tiempo real al cargar páginas. Predeterminado: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>record</code></td><td>Graba video de la sesión del navegador sin interfaz. Predeterminado: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>record_name</code></td><td>Asigna un nombre a la grabación para facilitar la búsqueda (<code>^[a-zA-Z0-9_-]{1,64}$</code>).</td><td>cadena</td></tr><tr><td><code>session_name</code></td><td>Sesiones persistentes. Se reconecta al mismo navegador remoto en vivo (<code>^[A-Za-z0-9-]{3,36}$</code>, admite guiones, no guiones bajos). TTL máximo – 24 h.</td><td>cadena</td></tr><tr><td><code>keep_alive</code></td><td>Mantiene activa la instancia remota del navegador al desconectarse el cliente cuando se establece en <code>true</code>. Requiere <code>session_name</code>. Predeterminado: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>o_profile</code></td><td>Perfiles persistentes – guardar/restaurar cookies y <code>localStorage</code> con un perfil con nombre (<code>^[a-zA-Z0-9][a-zA-Z0-9_-]{2,35}$</code>).</td><td>cadena</td></tr><tr><td><code>o_profile_save</code></td><td>Perfiles persistentes – fuerza el guardado del perfil durante o al final de la sesión. Requiere <code>o_profile</code>. Predeterminado: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>proxy_resi_ses_id</code></td><td>ID de sesión personalizado para fijar la IP de salida residencial entre sesiones (<code>^[A-Za-z0-9]{3,36}$</code>).</td><td>cadena</td></tr><tr><td><code>proxy_resi_ses_time</code></td><td>Duración para mantener fija la IP de salida del proxy residencial en minutos. Mín <code>1</code>, máx. <code>1440</code> (24 h).</td><td>entero</td></tr></tbody></table>

## Configuración recomendada

### Optimización del tráfico

El raspado de páginas dinámicas a menudo hace que el navegador descargue recursos innecesarios como medios pesados, scripts de seguimiento, imágenes y fuentes. Esto consume ancho de banda y ralentiza los tiempos de ejecución.

Puedes interceptar y abortar estas solicitudes programáticamente antes de que consuman recursos:

{% tabs %}
{% tab title="Python (Playwright)" %}

```python
# Abort heavy assets to save bandwidth and improve speeds
def block_resources(route):
    if route.request.resource_type in ["image", "stylesheet", "media", "font"]:
        route.abort()
    else:
        route.continue_()

page.route("**/*", block_resources)
```

{% endtab %}

{% tab title="JavaScript (Playwright)" %}

```javascript
// Abort heavy assets to save bandwidth and improve speeds
await page.route("**/*", (route) => {
    const type = route.request().resourceType();
    if (["image", "stylesheet", "media", "font"].includes(type)) {
        return route.abort();
    }
    return route.continue();
});
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Si usas Page Handler, no bloquees hojas de estilo, imágenes, medios ni fuentes para el destino. Bloquearlos puede impedir que se cargue un widget de desafío.
{% endhint %}

### Manejo de errores y reintentos <a href="#error-handling-and-retries" id="error-handling-and-retries"></a>

Los problemas de red y el límite de 10 sesiones por segundo hacen que una sola `connectOverCDP` llamada puede fallar de forma transitoria. Encapsula la conexión en un `reintento` con `backoff exponencial`, y limita cada intento con un timeout. El ejemplo siguiente usa la API estándar de Playwright.

```javascript
const { chromium } = require("playwright");

const MAX_RETRIES = 5;
const BASE_DELAY_MS = 1000;

async function connectWithRetry(endpoint, { maxRetries = MAX_RETRIES } = {}) {
    let lastError;
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            // Cap how long a single connection attempt may take.
            return await chromium.connectOverCDP(endpoint, { timeout: 60_000 });
        } catch (err) {
            lastError = err;
            // Exponential backoff with jitter — backs off when you hit the
            // 10-new-sessions/second rate limit instead of hammering the endpoint.
            const delay = BASE_DELAY_MS * 2 ** attempt + Math.random() * 250;
            console.warn(
                `connect attempt ${attempt + 1} failed: ${err.message}; ` +
                `retrying in ${Math.round(delay)}ms`
            );
            await new Promise((resolve) => setTimeout(resolve, delay));
        }
    }
    throw lastError;
}
```

{% hint style="info" %}
Para la lista completa de errores de handshake, cierre de WebSocket y en la página, consulta [Códigos de respuesta](https://developers.oxylabs.io/products/es/agent-browser/codigos-de-respuesta.md).
{% endhint %}

### Limpieza de recursos <a href="#resource-cleanup" id="resource-cleanup"></a>

Cierra siempre el navegador cuando termines, incluso si tu automatización falla a mitad de camino. Usa un `try { ... } finally { ... }` bloque para que la limpieza se ejecute en todos los casos:

```javascript
const browser = await connectWithRetry(endpoint);
try {
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    // ... your automation ...
} finally {
    // Runs even if the block above throws. Without this, a session left open
    // after an exception lingers and counts against your 100 concurrent-session limit.
    await browser.close();
}
```

Si se produce una excepción entre connect y close y no limpias, la sesión remota permanece abierta y consume una de tus **100 sesiones concurrentes** hasta que se recupere. Las sesiones filtradas bajo carga pueden agotar el límite y bloquear nuevas conexiones.

## ¿Necesita habilitar una función? <a href="#need-a-feature-enabled" id="need-a-feature-enabled"></a>

Algunas funciones de Agent Browser están limitadas de forma predeterminada. Para ajustar sus límites, contacte con el soporte de Oxylabs ([chat en vivo](https://oxylabs.io/) o [correo electrónico](mailto:support@oxylabs.io)) o con su gestor de cuenta dedicado:

* **Más perfiles persistentes** – aumente el límite predeterminado de su cuenta de 5 perfiles guardados.
* **Más sesiones persistentes** – aumente el límite predeterminado de su cuenta de 5 sesiones persistentes simultáneas.
* **Destinos restringidos** – desbloquee más categorías de objetivos mediante el proceso KYC.
* **Límites de tasa más altos** – aumente por encima de 100 sesiones simultáneas / 10 por segundo.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/es/agent-browser.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
