Como Usar a API Cloud do Navegador

Este tutorial irá guiá-lo por tudo o que você precisa saber para aproveitar o poder da automação de navegador impulsionada por IA. Se você está procurando automatizar a extração de dados, testar suas aplicações web ou criar ferramentas de monitoramento sofisticadas, este guia fornecerá o conhecimento e os exemplos para começar.

button

O que é o Browser Use Cloud?

Browser Use Cloud é uma plataforma poderosa que permite criar e gerenciar agentes de automação de navegador inteligentes programaticamente. Pense nisso como ter uma frota de assistentes virtuais que podem navegar na web, interagir com sites e realizar tarefas complexas em seu nome.

No centro da plataforma está o conceito de "tarefa". Uma tarefa é um conjunto de instruções que você fornece a um agente em linguagem natural. Por exemplo, você poderia dar a um agente uma tarefa como: "Vá para hacker-news.com, encontre os 5 artigos mais populares e salve seus títulos e URLs em um arquivo." O agente então usará um modelo de linguagem grande (LLM) para entender e executar essas instruções em um ambiente de navegador real.

Uma das funcionalidades mais empolgantes do Browser Use Cloud é o loop de feedback em tempo real. Cada tarefa que você cria vem com uma live_url. Esta URL fornece uma prévia interativa e ao vivo do que o agente está fazendo. Você pode observar o agente navegando em tempo real e até mesmo assumir o controle, se necessário. Isso torna a depuração e o monitoramento incrivelmente intuitivos.

Obtendo Sua Chave de API

Antes de começar a criar agentes, você precisará de uma chave de API. A chave de API autentica suas requisições e as vincula à sua conta.

Nota: Para obter sua chave de API, você precisará de uma assinatura ativa do Browser Use Cloud. Você pode gerenciar sua assinatura e obter sua chave de API na página de cobrança: cloud.browser-use.com/billing.

Assim que tiver sua chave de API, certifique-se de mantê-la segura. Trate-a como uma senha e nunca a exponha em código do lado do cliente ou a inclua no controle de versão. É melhor armazená-la em uma variável de ambiente segura.

export BROWSER_USE_API_KEY="your_api_key_here"

Entendendo o Modelo de Preços

A API do Browser Use Cloud possui um modelo de preços simples, pay-as-you-go (pague pelo uso). Isso garante que você pague apenas pelo que usar, tornando-o econômico tanto para projetos pequenos quanto em larga escala. O preço é composto por duas partes principais:

1. Custo de Inicialização da Tarefa: Uma taxa fixa de $0.01 é cobrada para cada tarefa que você inicia. Isso cobre o custo de inicialização do ambiente do navegador para seu agente.
2. Custo por Passo da Tarefa: Este é o custo para cada ação ou "passo" que o agente executa. O custo por passo depende do LLM que você escolher para impulsionar seu agente.

Preços por Passo do LLM

Diferentes LLMs possuem capacidades e preços diferentes. Você pode escolher o modelo que melhor se adapta às suas necessidades de desempenho e custo. Aqui está um detalhamento do custo por passo para cada modelo disponível:

Exemplo de Cálculo de Custo

Vamos imaginar que você queira automatizar uma tarefa que envolve fazer login em um site, navegar para uma página específica e extrair alguns dados. Você estima que isso levará cerca de 15 passos. Se você escolher usar o poderoso modelo GPT-4o, o custo total seria calculado da seguinte forma:

• Inicialização da Tarefa: $0.01
• Passos da Tarefa: 15 passos × $0.03/passo = $0.45
• Custo Total: $0.01 + $0.45 = $0.46

Este preço transparente permite que você preveja e controle seus custos de forma eficaz.

Criando Seu Primeiro Agente: Um Exemplo "Hello, World!"

Agora para a parte emocionante! Vamos criar seu primeiro agente de automação de navegador. Começaremos com uma tarefa muito simples: ir ao Google e procurar por "Browser Use".

Usaremos curl para fazer uma requisição POST para o endpoint /api/v1/run-task. Este é o endpoint principal para criar novas tarefas.

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"
  }'

Vamos detalhar este comando:

• curl -X POST ...: Estamos enviando uma requisição HTTP POST para a URL especificada.
• H "Authorization: Bearer $BROWSER_USE_API_KEY": Este é o cabeçalho de autenticação. Inclui sua chave de API. Estamos usando a variável de ambiente que definimos anteriormente.
• H "Content-Type: application/json": Este cabeçalho informa à API que estamos enviando dados no formato JSON.
• d '{ "task": "..." }': Este é o corpo da nossa requisição. O campo task contém as instruções em linguagem natural para o nosso agente.

Entendendo a Resposta da API

Ao enviar esta requisição, a API responderá com um objeto JSON contendo informações sobre a tarefa recém-criada. Aqui está um exemplo de como essa resposta pode parecer:

{
  "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 é um identificador único para sua tarefa. Você usará este ID para gerenciar a tarefa posteriormente (por exemplo, para pausá-la, retomá-la ou pará-la).
• status: Indica o estado atual da tarefa. Inicialmente, será running (em execução).
• live_url: Esta é a URL para a prévia ao vivo. Copie e cole esta URL em seu navegador para ver seu agente em ação!

Pré-visualizações Interativas ao Vivo

A live_url é uma das funcionalidades mais poderosas do Browser Use Cloud. Não é apenas um stream de vídeo somente leitura; é uma sessão totalmente interativa.

Você pode incorporar a live_url diretamente em suas próprias aplicações usando um iframe. Isso permite que você construa dashboards e ferramentas de monitoramento personalizados que incluem uma visualização em tempo real de seus agentes.

Aqui está um snippet HTML simples para incorporar a prévia ao 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>

Substitua YOUR_LIVE_URL_HERE pela live_url da resposta da API. Ao abrir este arquivo HTML em um navegador, você verá a tela do agente. Você pode clicar, digitar e rolar a página como se estivesse navegando em seu próprio computador. Isso é incrivelmente útil para:

• Depuração: Se um agente travar, você pode ver imediatamente porquê e o que está na tela dele.
• Intervenção Manual: Se uma tarefa exigir um passo difícil de automatizar (como resolver um CAPTCHA complexo), você pode assumir o controle, completar o passo manualmente e então deixar o agente retomar seu trabalho.
• Demonstrações: É uma ótima maneira de mostrar aos stakeholders o que sua automação está fazendo.

Gerenciando o Ciclo de Vida da Tarefa

Uma vez que uma tarefa esteja em execução, você tem controle total sobre seu ciclo de vida. Você pode pausar, retomar e parar tarefas usando a API. Você precisará do task_id para todas as operações de gerenciamento.

Pausando e Retomando uma Tarefa

Há muitas razões pelas quais você pode querer pausar uma tarefa. Talvez você precise inspecionar a página web manualmente, ou talvez queira esperar que um evento externo ocorra antes de continuar.

Para pausar uma tarefa, envie uma requisição POST para o 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"
  }'

O agente terminará seu passo atual e então entrará em um estado paused (pausado).

Para retomar a tarefa, envie uma requisição POST para o 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"
  }'

O agente continuará exatamente de onde parou.

Parando uma Tarefa

Se você quiser encerrar uma tarefa permanentemente, pode usar o endpoint /api/v1/stop-task. Isso é útil se a tarefa estiver completa, tiver dado errado ou não for mais necessária.

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: Uma vez que uma tarefa é parada, ela não pode ser retomada. O ambiente do navegador é destruído, e todos os recursos associados são limpos.

Criação Avançada de Tarefas

O exemplo "Hello, World!" foi apenas o começo. O endpoint run-task suporta mais do que apenas uma string simples de task. Você pode personalizar o comportamento do seu agente fornecendo parâmetros adicionais.

Escolhendo um LLM

Como vimos na seção de preços, você pode escolher entre vários LLMs diferentes para impulsionar seu agente. Você pode especificar o modelo na requisição run-task usando o parâmetro model.

Por exemplo, para usar o modelo Claude 3.7 Sonnet, você faria a seguinte requisição:

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"
  }'

Se você não especificar um modelo, a API usará um modelo padrão, que geralmente é uma opção econômica e performática como o GPT-4o mini.

Construindo Seu Próprio Cliente

Embora o curl seja ótimo para testes simples, você provavelmente desejará integrar a API do Browser Use Cloud em suas aplicações usando uma biblioteca cliente adequada. A melhor maneira de fazer isso é usar nossa especificação OpenAPI para gerar um cliente com segurança de tipo (type-safe).

A especificação OpenAPI é uma maneira padronizada de descrever APIs REST. Você pode encontrar nossa especificação aqui: http://api.browser-use.com/openapi.json.

Geração de Cliente Python

Para desenvolvedores Python, recomendamos o openapi-python-client. Ele gera um cliente moderno, focado em async, com dicas de tipo completas.

Primeiro, instale a ferramenta geradora:

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

Agora, gere o cliente:

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

Isso criará um novo diretório contendo seu pacote cliente Python. Você pode instalá-lo usando pip:

pip install .

Agora você pode usar o cliente em seu 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())

Geração de Cliente TypeScript/JavaScript

Para projetos de frontend ou Node.js, openapi-typescript é uma excelente ferramenta para gerar definições de tipo TypeScript a partir da especificação OpenAPI.

Primeiro, instale o gerador como uma dependência de desenvolvimento:

npm install -D openapi-typescript

Em seguida, execute o gerador:

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

Isso criará um único arquivo, src/browser-use-api.ts, contendo todas as definições de tipo para a API. Você pode então usar esses tipos com seu cliente HTTP preferido, como fetch ou axios, para fazer requisições com segurança de tipo.

Aqui está um exemplo usando fetch em um projeto 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();

button