Cómo Usar la API Cloud del Navegador

Este tutorial le guiará a través de todo lo que necesita saber para aprovechar el poder de la automatización del navegador impulsada por IA. Ya sea que busque automatizar la extracción de datos, probar sus aplicaciones web o crear herramientas de monitoreo sofisticadas, esta guía le proporcionará el conocimiento y los ejemplos para empezar.

¿Qué es Browser Use Cloud?

Browser Use Cloud es una potente plataforma que le permite crear y gestionar agentes inteligentes de automatización del navegador de forma programática. Piense en ello como tener una flota de asistentes virtuales que pueden navegar por la web, interactuar con sitios web y realizar tareas complejas en su nombre.

En el núcleo de la plataforma se encuentra el concepto de "tarea". Una tarea es un conjunto de instrucciones que usted proporciona a un agente en lenguaje natural. Por ejemplo, podría dar a un agente una tarea como: "Vaya a hacker-news.com, encuentre los 5 artículos principales y guarde sus títulos y URLs en un archivo". El agente utilizará entonces un modelo de lenguaje grande (LLM) para comprender y ejecutar estas instrucciones en un entorno de navegador real.

Una de las características más interesantes de Browser Use Cloud es el bucle de retroalimentación en tiempo real. Cada tarea que crea viene con una live_url. Esta URL proporciona una vista previa interactiva y en vivo de lo que el agente está haciendo. Puede ver al agente navegar en tiempo real e incluso tomar el control si es necesario. Esto hace que la depuración y el monitoreo sean increíblemente intuitivos.

Cómo obtener su clave API

Antes de poder empezar a crear agentes, necesitará una clave API. La clave API autentica sus solicitudes y las vincula a su cuenta.

<Nota> Para obtener su clave API, necesitará una suscripción activa a Browser Use Cloud. Puede gestionar su suscripción y obtener su clave API desde la página de facturación: cloud.browser-use.com/billing. </Nota>

Una vez que tenga su clave API, asegúrese de mantenerla segura. Trátela como una contraseña y nunca la exponga en código del lado del cliente ni la incluya en el control de versiones. Es mejor almacenarla en una variable de entorno segura.

export BROWSER_USE_API_KEY="your_api_key_here"

Entendiendo el modelo de precios

La API de Browser Use Cloud tiene un modelo de precios simple de pago por uso. Esto garantiza que solo pague por lo que utiliza, lo que lo hace rentable tanto para proyectos pequeños como a gran escala. El precio se compone de dos partes principales:

1. Costo de inicialización de tarea: Se cobra una tarifa fija de $0.01 por cada tarea que inicia. Esto cubre el costo de iniciar el entorno del navegador para su agente.
2. Costo por paso de tarea: Este es el costo por cada acción o "paso" que realiza el agente. El costo por paso depende del LLM que elija para potenciar su agente.

Precios por paso de LLM

Diferentes LLMs tienen diferentes capacidades y puntos de precio. Puede elegir el modelo que mejor se adapte a sus necesidades de rendimiento y costo. Aquí tiene un desglose del costo por paso para cada modelo disponible:

Ejemplo de cálculo de costos

Imaginemos que desea automatizar una tarea que implica iniciar sesión en un sitio web, navegar a una página específica y extraer algunos datos. Estima que esto tomará alrededor de 15 pasos. Si elige utilizar el potente modelo GPT-4o, el costo total se calcularía de la siguiente manera:

• Inicialización de tarea: $0.01
• Pasos de tarea: 15 pasos × $0.03/paso = $0.45
• Costo total: $0.01 + $0.45 = $0.46

Este precio transparente le permite predecir y controlar sus costos de manera efectiva.

Creando su primer agente: Un ejemplo de "¡Hola, Mundo!"

¡Ahora viene la parte emocionante! Vamos a crear su primer agente de automatización del navegador. Empezaremos con una tarea muy simple: ir a Google y buscar "Browser Use".

Usaremos curl para hacer una solicitud POST al endpoint /api/v1/run-task. Este es el endpoint principal para crear nuevas tareas.

curl -X POST <https://api.browser-use.com/api/v1/run-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task": "Go to google.com and search for Browser Use"
  }'

Analicemos este comando:

• curl -X POST ...: Estamos enviando una solicitud HTTP POST a la URL especificada.
• H "Authorization: Bearer $BROWSER_USE_API_KEY": Este es el encabezado de autenticación. Incluye su clave API. Estamos utilizando la variable de entorno que configuramos anteriormente.
• H "Content-Type: application/json": Este encabezado indica a la API que estamos enviando datos en formato JSON.
• d '{ "task": "..." }': Este es el cuerpo de nuestra solicitud. El campo task contiene las instrucciones en lenguaje natural para nuestro agente.

Entendiendo la respuesta de la API

Cuando envíe esta solicitud, la API responderá con un objeto JSON que contiene información sobre la tarea recién creada. Aquí tiene un ejemplo de cómo podría ser esa respuesta:

{
  "task_id": "ts_2a9b4e7c-1d0f-4g8h-9i1j-k2l3m4n5o6p7",
  "status": "running",
  "live_url": "<https://previews.browser-use.com/ts_2a9b4e7c-1d0f-4g8h-9i1j-k2l3m4n5o6p7>"
}

• task_id: Este es un identificador único para su tarea. Usará este ID para gestionar la tarea más tarde (por ejemplo, para pausarla, reanudarla o detenerla).
• status: Esto indica el estado actual de la tarea. Inicialmente será running (en ejecución).
• live_url: Esta es la URL para la vista previa en vivo. ¡Copie y pegue esta URL en su navegador para ver a su agente en acción!

Vistas previas interactivas en vivo

La live_url es una de las características más potentes de Browser Use Cloud. No es solo una transmisión de video de solo lectura; es una sesión completamente interactiva.

Puede incrustar la live_url directamente en sus propias aplicaciones utilizando un iframe. Esto le permite construir paneles personalizados y herramientas de monitoreo que incluyen una vista en tiempo real de sus agentes.

Aquí tiene un fragmento simple de HTML para incrustar la vista previa en vivo:

<!DOCTYPE html>
<html>
<head>
  <title>Agent Live Preview</title>
  <style>
    body, html { margin: 0; padding: 0; height: 100%; overflow: hidden; }
    iframe { width: 100%; height: 100%; border: none; }
  </style>
</head>
<body>
  <iframe src="YOUR_LIVE_URL_HERE"></iframe>
</body>
</html>

Reemplace YOUR_LIVE_URL_HERE con la live_url de la respuesta de la API. Cuando abra este archivo HTML en un navegador, verá la pantalla del agente. Puede hacer clic, escribir y desplazarse como si estuviera navegando en su propio ordenador. Esto es increíblemente útil para:

• Depuración: Si un agente se queda atascado, puede ver inmediatamente por qué y qué hay en su pantalla.
• Intervención manual: Si una tarea requiere un paso difícil de automatizar (como resolver un CAPTCHA complejo), puede tomar el control, completar el paso manualmente y luego dejar que el agente reanude su trabajo.
• Demostraciones: Es una excelente manera de mostrar a las partes interesadas lo que está haciendo su automatización.

Gestionando el ciclo de vida de la tarea

Una vez que una tarea está en ejecución, tiene control total sobre su ciclo de vida. Puede pausar, reanudar y detener tareas utilizando la API. Necesitará el task_id para todas las operaciones de gestión.

Pausando y reanudando una tarea

Hay muchas razones por las que podría querer pausar una tarea. Quizás necesite inspeccionar la página web manualmente, o tal vez quiera esperar a que ocurra un evento externo antes de continuar.

Para pausar una tarea, envíe una solicitud POST al endpoint /api/v1/pause-task:

curl -X POST <https://api.browser-use.com/api/v1/pause-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

El agente terminará su paso actual y luego entrará en un estado paused (pausado).

Para reanudar la tarea, envíe una solicitud POST al endpoint /api/v1/resume-task:

curl -X POST <https://api.browser-use.com/api/v1/resume-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

El agente continuará justo donde lo dejó.

Deteniendo una tarea

Si desea finalizar una tarea permanentemente, puede usar el endpoint /api/v1/stop-task. Esto es útil si la tarea está completa, ha fallado o ya no es necesaria.

curl -X POST <https://api.browser-use.com/api/v1/stop-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

<Nota> Una vez que una tarea se detiene, no se puede reanudar. El entorno del navegador se destruye y todos los recursos asociados se limpian. </Nota>

Creación avanzada de tareas

El ejemplo de "¡Hola, Mundo!" fue solo el principio. El endpoint run-task soporta más que una simple cadena task. Puede personalizar el comportamiento de su agente proporcionando parámetros adicionales.

Eligiendo un LLM

Como vimos en la sección de precios, puede elegir entre varios LLMs diferentes para potenciar su agente. Puede especificar el modelo en la solicitud run-task utilizando el parámetro model.

Por ejemplo, para usar el modelo Claude 3.7 Sonnet, haría la siguiente solicitud:

curl -X POST <https://api.browser-use.com/api/v1/run-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task": "Go to reddit.com/r/programming and find the top post of the day.",
    "model": "claude-3.7-sonnet-20250219"
  }'

Si no especifica un modelo, la API utilizará un modelo predeterminado, que suele ser una opción rentable y de alto rendimiento como GPT-4o mini.

Construyendo su propio cliente

Si bien curl es excelente para pruebas simples, es probable que desee integrar la API de Browser Use Cloud en sus aplicaciones utilizando una biblioteca cliente adecuada. La mejor manera de hacerlo es utilizar nuestra especificación OpenAPI para generar un cliente con tipado seguro.

La especificación OpenAPI es una forma estandarizada de describir APIs REST. Puede encontrar nuestra especificación aquí: http://api.browser-use.com/openapi.json.

Generación de cliente Python

Para desarrolladores de Python, recomendamos openapi-python-client. Genera un cliente moderno, async-first, con anotaciones de tipo completas.

Primero, instale la herramienta generadora:

# We recommend using pipx to keep your global environment clean
pipx install openapi-python-client --include-deps

Ahora, genere el cliente:

openapi-python-client generate --url <http://api.browser-use.com/openapi.json>

Esto creará un nuevo directorio que contiene su paquete cliente Python. Puede instalarlo usando pip:

pip install .

Ahora puede usar el cliente en su código Python:

import asyncio
from browser_use_api import Client
from browser_use_api.models import RunTaskRequest

async def main():
    client = Client(base_url="<https://api.browser-use.com/api/v1>")
    request = RunTaskRequest(task="Go to ycombinator.com and list the top 3 companies.")

    response = await client.run_task.api_v1_run_task_post(
        client=client,
        json_body=request,
        headers={"Authorization": f"Bearer {YOUR_API_KEY}"}
    )

    if response:
        print(f"Task created with ID: {response.task_id}")
        print(f"Live URL: {response.live_url}")

if __name__ == "__main__":
    asyncio.run(main())

Generación de cliente TypeScript/JavaScript

Para proyectos frontend o Node.js, openapi-typescript es una excelente herramienta para generar definiciones de tipo TypeScript a partir de la especificación OpenAPI.

Primero, instale el generador como una dependencia de desarrollo:

npm install -D openapi-typescript

Luego, ejecute el generador:

npx openapi-typescript <http://api.browser-use.com/openapi.json> -o src/browser-use-api.ts

Esto creará un único archivo, src/browser-use-api.ts, que contiene todas las definiciones de tipo para la API. Luego puede usar estos tipos con su cliente HTTP preferido, como fetch o axios, para realizar solicitudes con tipado seguro.

Aquí tiene un ejemplo usando fetch en un proyecto TypeScript:

import { paths } from './src/browser-use-api';

const API_URL = "<https://api.browser-use.com/api/v1>";

type RunTaskRequest = paths["/run-task"]["post"]["requestBody"]["content"]["application/json"];
type RunTaskResponse = paths["/run-task"]["post"]["responses"]["200"]["content"]["application/json"];

async function createTask(task: string, apiKey: string): Promise<RunTaskResponse> {
  const body: RunTaskRequest = { task };

  const response = await fetch(`${API_URL}/run-task`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    throw new Error(`API request failed with status ${response.status}`);
  }

  return response.json() as Promise<RunTaskResponse>;
}

async function run() {
  const apiKey = process.env.BROWSER_USE_API_KEY;
  if (!apiKey) {
    throw new Error("API key not found in environment variables.");
  }

  try {
    const result = await createTask("Find the current weather in New York City.", apiKey);
    console.log("Task created:", result);
  } catch (error) {
    console.error("Failed to create task:", error);
  }
}

run();