Navegador | Firecrawl

Para fluxos de trabalho com agentes, use Interact. Interact é a opção compatível para CLI/MCP e pode ser usado com prompts ou código após um scraping; o MCP também oferece suporte para abrir diretamente de uma URL.

Superfície	Use para	Ponto de entrada	Superfície do agente
Sandbox de Navegador	Sessões de navegador independentes para usuários de API/SDK que precisam de um sandbox, URL de CDP, visualização em tempo real ou ciclo de vida persistente da sessão	`POST /v2/interact`	API e SDKs; o comando oculto de navegador da CLI é legado
Interact	Executar ações em uma página extraída; o MCP também pode abrir a partir de uma URL com o modo URL do `firecrawl_interact`	`POST /v2/scrape/{scrapeId}/interact`, CLI `interact` após o scraping ou MCP `firecrawl_interact`	Recomendado para fluxos de trabalho com agentes em CLI/MCP

O Firecrawl Sandbox de Navegador oferece aos usuários de API e SDK um ambiente de navegador seguro onde agentes podem interagir com a web. Preencha formulários, clique em botões, autentique-se e muito mais. Sem configuração local, sem instalações do Chromium, sem problemas de compatibilidade de driver. Agent browser e playwright vêm pré-instalados. Disponível via API, Node SDK, Python SDK e Vercel AI SDK. O comando oculto firecrawl browser da CLI é legado; os fluxos de agentes em CLI e MCP devem usar scraping + interact. Para adicionar suporte ao Interact a um agente de codificação com IA (Claude Code, Codex, Open Code, Cursor etc.), instale a skill do Firecrawl:

npx -y firecrawl-cli@latest init --all --browser

Cada sessão é executada em um sandbox isolado, descartável ou persistente, que escala sem gerenciar infraestrutura.

Início rápido

Crie uma sessão, execute código e feche-a:

// npm install firecrawl
import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

// 1. Launch a session
const session = await firecrawl.browser();
console.log(session.cdpUrl); // wss://cdp-proxy.firecrawl.dev/cdp/...

// 2. Execute code
const result = await firecrawl.browserExecute(session.id, {
  code: `
    await page.goto("https://news.ycombinator.com");
    const title = await page.title();
    console.log(title);
  `,
  language: "node",
});
console.log(result.result); // "Hacker News"

// 3. Close
await firecrawl.deleteBrowser(session.id);

Sem instalação de drivers - Sem binário do Chromium, sem playwright install, sem problemas de compatibilidade de drivers
Python, JavaScript e Bash - Envie código via API, CLI ou SDK e receba os resultados de volta. As três linguagens são executadas remotamente no sandbox
agent-browser - CLI pré-instalada com mais de 60 comandos. Agentes de IA escrevem comandos Bash simples em vez de código Playwright
Playwright carregado - Playwright vem pré-instalado no sandbox. Agentes podem escrever código Playwright se preferirem.
Acesso ao CDP - Conecte sua própria instância do Playwright via WebSocket quando precisar de controle total
Visualização em tempo real - Assista às sessões em tempo real por meio de uma URL de transmissão incorporável
Visualização em tempo real interativa - Permita que os usuários interajam diretamente com o navegador por meio de uma transmissão interativa incorporável

Iniciar uma sessão

Retorna um ID de sessão, uma URL do CDP e uma URL de visualização em tempo real.

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const session = await firecrawl.browser({
  ttl: 120,
  activityTtl: 60,
});

console.log(session.id);
console.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...
console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...

Response

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "expiresAt": "2025-01-15T10:40:00Z"
}

Executar código

Execute código Python, JavaScript ou bash na sua sessão. O resultado é retornado via stdout; no Node.js, o valor da última expressão também fica disponível em result.

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const result = await firecrawl.browserExecute("YOUR_SESSION_ID", {
  code: 'await page.goto("https://example.com"); const title = await page.title(); console.log(title);',
  language: "node",
});

console.log(result);

Response

{
  "success": true,
  "stdout": "",
  "result": "Example Domain",
  "stderr": "",
  "exitCode": 0,
  "killed": false
}

Como lidar com downloads de arquivos

Arquivos baixados dentro de uma sessão podem ser capturados e retornados em base64. Use a API de download do Playwright por meio do endpoint execute:

import base64

async with page.expect_download() as download_info:
    await page.click('a#download-link')  # Clique no elemento que aciona o download

download = download_info.value
path = await download.path()

# Opcionalmente, salve em um caminho conhecido
# await download.save_as('/tmp/myfile.pdf')

# Leia e gere o conteúdo do arquivo em base64
with open(path, "rb") as f:
    content = base64.b64encode(f.read()).decode()
    print(content)

O sistema de arquivos do sandbox é efêmero — os arquivos baixados são perdidos quando a sessão termina. Para persistir arquivos, leia o conteúdo deles durante a sessão e salve-o no seu próprio armazenamento. Perfis persistentes preservam o estado do navegador (cookies, localStorage), mas não os arquivos em disco.

agent-browser (Modo Bash)

agent-browser é uma CLI de navegador headless pré-instalada em cada sandbox. Em vez de escrever código em Playwright, os agentes enviam comandos bash simples. A CLI injeta automaticamente --cdp para que o agent-browser se conecte automaticamente à sua sessão ativa.

Os exemplos da CLI firecrawl browser abaixo são para sessões legadas do Sandbox de Navegador. Para fluxos de trabalho de agentes com CLI/MCP, prefira firecrawl interact ou a ferramenta MCP firecrawl_interact.

Forma abreviada

A maneira mais rápida de usar o browser. Tanto a forma abreviada quanto execute enviam comandos para o agent-browser automaticamente. A forma abreviada apenas ignora o execute e inicia uma sessão automaticamente, se necessário:

firecrawl browser "open https://example.com"
firecrawl browser "snapshot"
firecrawl browser "click @e5"

CLI

A forma explícita usa execute. Os comandos são enviados automaticamente ao agent-browser — você não precisa digitar agent-browser nem usar --bash:

firecrawl browser execute "open https://example.com"
firecrawl browser execute "snapshot"

API & SDK

Use language: "bash" para executar comandos do agent-browser por meio da API ou dos SDKs:

curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "agent-browser snapshot",
    "language": "bash"
  }'

Gerenciamento de sessões

Sessões persistentes

Por padrão, cada sessão do navegador começa em um estado limpo. Com profile, você pode salvar e reutilizar o estado do navegador entre sessões. Isso é útil para permanecer logado e preservar preferências. Para salvar ou selecionar um perfil, use o parâmetro profile ao criar uma sessão.

const session = await firecrawl.browser({
  ttl: 600,
  profile: {
    name: "my-profile",
    saveChanges: true,
  },
});

Parâmetro	Padrão	Descrição
`name`	—	Um nome para o perfil persistente. Sessões com o mesmo nome compartilham o armazenamento.
`saveChanges`	`true`	Quando `true`, o estado do navegador é salvo de volta no perfil ao encerrar. Defina como `false` para carregar dados existentes sem gravar — útil quando você precisa de vários leitores simultâneos.

Apenas uma sessão pode salvar em um perfil por vez. Se outra sessão já estiver salvando, você receberá um erro 409. Você ainda pode abrir o mesmo perfil com saveChanges: false, ou tentar novamente mais tarde.

O estado da sessão do navegador só é salvo quando a sessão é encerrada. Portanto, recomendamos encerrar a sessão do navegador quando terminar de usá-la, para que ela possa ser reutilizada. Depois que uma sessão é encerrada, seu ID de sessão não é mais válido — você não pode reutilizá-lo. Em vez disso, crie uma nova sessão com o mesmo nome de perfil e use o novo ID de sessão retornado na resposta. Para salvar e encerrar:

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

await firecrawl.deleteBrowser("YOUR_SESSION_ID");

Listar sessões

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const { sessions } = await firecrawl.listBrowsers();
console.log(sessions);

// Filtrar por status
const { sessions: active } = await firecrawl.listBrowsers({ status: "active" });
console.log(active);

Response

{
  "success": true,
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "active",
      "cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...",
      "liveViewUrl": "https://liveview.firecrawl.dev/...",
      "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
      "createdAt": "2025-01-15T10:30:00Z",
      "lastActivity": "2025-01-15T10:35:00Z"
    }
  ]
}

Configuração de TTL

As sessões têm dois controles de TTL:

Parâmetro	Padrão	Descrição
`ttl`	600s (10 min)	Tempo máximo de duração da sessão (30-3600s)
`activityTtl`	300s (5 min)	Encerramento automático após inatividade (10-3600s)

Encerrar a sessão

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

await firecrawl.deleteBrowser("YOUR_SESSION_ID");

Visualização em tempo real

Toda sessão retorna uma liveViewUrl na resposta que você pode incorporar para acompanhar o navegador em tempo real. Útil para depuração, demonstrações ou para criar interfaces baseadas em navegador.

Response

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...",
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "expiresAt": "2025-01-15T10:40:00Z"
}

<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

Visualização Interativa Ao Vivo

A resposta também inclui um interactiveLiveViewUrl. Diferente da visualização ao vivo padrão, que é apenas para consulta, a visualização interativa ao vivo permite que os usuários cliquem, digitem e interajam com a sessão do navegador diretamente por meio do streaming incorporado. Isso é útil para construir interfaces de navegador voltadas para o usuário final, depuração colaborativa ou qualquer cenário em que quem estiver visualizando precise controlar o navegador.

<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />

Conectando-se ao CDP

Cada sessão expõe uma URL de WebSocket do CDP. A API execute e a opção --bash cobrem a maioria dos casos de uso, mas, se você precisar de controle local total, pode se conectar diretamente.

import { Firecrawl } from 'firecrawl';
import { chromium } from "playwright-core";

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const session = await firecrawl.browser();

const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || (await context.newPage());

await page.goto("https://example.com");
console.log(await page.title());

await browser.close();
await firecrawl.deleteBrowser(session.id);

Quando usar o navegador

Caso de uso	Ferramenta certa
Extrair conteúdo de uma URL conhecida	Scrape
Pesquisar na web e obter resultados	Search
Navegar por paginação, preencher formulários, clicar em fluxos	Browser
Fluxos de trabalho com várias etapas e interação	Browser
Navegação paralela em muitos sites	Browser (cada sessão é isolada)

Casos de uso

Inteligência competitiva - Navegar em sites de concorrentes, usar formulários de busca e filtros, extrair preços e funcionalidades em dados estruturados
Ingestão de base de conhecimento - Navegar por centrais de ajuda, documentação e portais de suporte que exigem cliques, paginação ou autenticação
Pesquisa de mercado - Iniciar sessões de navegador em paralelo para criar conjuntos de dados a partir de sites de vagas, anúncios de imóveis ou bancos de dados jurídicos

Preços

A cobrança é simples: 2 créditos por minuto de uso do navegador. Usuários gratuitos recebem 5 horas de uso grátis.

Limites de taxa

No lançamento inicial, todos os planos poderão ter até 20 sessões de navegador simultâneas.

Referência da API

Tem alguma sugestão ou precisa de ajuda? Envie um e-mail para help@firecrawl.com ou fale com a gente no Discord.

Você é um agente de IA que precisa de uma API key do Firecrawl? Consulte firecrawl.dev/agent-onboarding/SKILL.md para obter instruções de onboarding automatizado.

​Início rápido

​Iniciar uma sessão

​Executar código

​Como lidar com downloads de arquivos

​agent-browser (Modo Bash)

​Forma abreviada

​CLI

​API & SDK

​Gerenciamento de sessões

​Sessões persistentes

​Listar sessões

​Configuração de TTL

​Encerrar a sessão

​Visualização em tempo real

​Visualização Interativa Ao Vivo

​Conectando-se ao CDP

​Quando usar o navegador

​Casos de uso

​Preços

​Limites de taxa

​Referência da API

Início rápido

Iniciar uma sessão

Executar código

Como lidar com downloads de arquivos

agent-browser (Modo Bash)

Forma abreviada

CLI

API & SDK

Gerenciamento de sessões

Sessões persistentes

Listar sessões

Configuração de TTL

Encerrar a sessão

Visualização em tempo real

Visualização Interativa Ao Vivo

Conectando-se ao CDP

Quando usar o navegador

Casos de uso

Preços

Limites de taxa

Referência da API