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);

# pip install firecrawl
from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

# 1. Iniciar uma sessão
session = app.browser()
print(session.cdp_url)  # wss://cdp-proxy.firecrawl.dev/cdp/...

# 2. Execute code
result = app.browser_execute(
    session.id,
    code='await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
    language="python",
)
print(result.result)  # "Hacker News"

# 3. Close
app.delete_browser(session.id)

# Install the Firecrawl CLI
npm install -g firecrawl-cli

# Atalho - inicia uma sessão automaticamente, sem necessidade de "execute"
firecrawl browser "open https://news.ycombinator.com"
firecrawl browser "snapshot"
firecrawl browser "scrape"

# Close when done
firecrawl browser close

# 1. Iniciar uma sessão
curl -X POST "https://api.firecrawl.dev/v2/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json"

# 2. Execute code
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": "await page.goto(\"https://news.ycombinator.com\")\ntitle = await page.title()\nprint(title)"
  }'

# 3. Close
curl -X DELETE "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

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/...

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

session = app.browser(
    ttl=120,
    activity_ttl=60,
)

print(session.id)
print(session.cdp_url)        # wss://cdp-proxy.firecrawl.dev/cdp/...
print(session.live_view_url)  # https://liveview.firecrawl.dev/...

# Iniciar com visualização em tempo real e TTL personalizado
firecrawl browser launch-session --stream --ttl 120 --ttl-inactivity 60

# Iniciar e salvar informações da sessão em arquivo
firecrawl browser launch-session -o session.json --json

curl -X POST "https://api.firecrawl.dev/v2/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 120,
    "activityTtl": 60
  }'

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);

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

result = app.browser_execute(
    "YOUR_SESSION_ID",
    code='await page.goto("https://example.com")\ntitle = await page.title()\nprint(title)',
    language="python",
)

print(result)

# comandos agent-browser (padrão - "agent-browser" é prefixado automaticamente)
firecrawl browser execute "open https://example.com"
firecrawl browser execute "snapshot"
firecrawl browser execute "scrape"

# Execute Playwright Python code
firecrawl browser execute --python 'await page.goto("https://example.com")
print(await page.title())'

# Execute Playwright JavaScript code
firecrawl browser execute --node 'await page.goto("https://example.com"); document.title'

# Execute arbitrary bash in the sandbox
firecrawl browser execute --bash 'ls /tmp'

# Target a specific session
firecrawl browser execute --session <id> "snapshot"

# Execute Playwright Python code
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": "await page.goto(\"https://example.com\")\ntitle = await page.title()\nprint(title)",
    "language": "python"
  }'

# Executar código Playwright JavaScript
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": "await page.goto(\"https://example.com\"); const title = await page.title(); console.log(title);",
    "language": "node"
  }'

# Navegar para uma página
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 open https://example.com", "language": "bash" }'

# Obter snapshot de acessibilidade com IDs @ref
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" }'

# Interagir usando IDs @ref do snapshot
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 click @e5", "language": "bash" }'

# Extrair conteúdo da página como markdown
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 scrape", "language": "bash" }'

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)

// Obtenha a URL de download a partir do elemento de link
const href = await page.getAttribute('a#download-link', 'href');

// Busque o arquivo no contexto do navegador e converta-o em base64
const b64 = await page.evaluate(async (url) => {
  const resp = await fetch(url);
  const blob = await resp.blob();
  return new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(blob);
  });
}, href);

process.stdout.write(b64);

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"

firecrawl browser execute "click @e5"
firecrawl browser execute "fill @e3 'termo de busca'"
firecrawl browser execute "scrape"

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

const result = await app.browserExecute(sessionId, {
  code: "agent-browser snapshot",
  language: "bash",
});

result = app.browser_execute(
    session_id,
    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,
  },
});

session = app.browser(
    ttl=600,
    profile={
        "name": "my-profile",
        "save_changes": True,
    },
)

curl -X POST "https://api.firecrawl.dev/v2/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 600,
    "profile": {
      "name": "my-profile",
      "saveChanges": true
    }
  }'

# Iniciar com um perfil (salva alterações por padrão)
firecrawl browser launch-session --profile my-profile

# Iniciar com um perfil em modo somente leitura
firecrawl browser launch-session --profile my-profile --no-save-changes

# Atalho: iniciar com perfil + executar em uma etapa
firecrawl browser --profile my-profile "open https://example.com"

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");

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

app.delete_browser("YOUR_SESSION_ID")

# Fecha a sessão ativa
firecrawl browser close

# Fecha uma sessão específica
firecrawl browser close --session <id>

curl -X DELETE "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

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);

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

response = app.list_browsers()
print(response.sessions)

firecrawl browser list
firecrawl browser list active

curl -X GET "https://api.firecrawl.dev/v2/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# Filtrar por status
curl -X GET "https://api.firecrawl.dev/v2/interact?status=active" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

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");

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

app.delete_browser("YOUR_SESSION_ID")

# Fecha a sessão ativa
firecrawl browser close

# Fecha uma sessão específica
firecrawl browser close --session <id>

curl -X DELETE "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

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);

from firecrawl import Firecrawl
from playwright.sync_api import sync_playwright

app = Firecrawl(api_key="fc-YOUR-API-KEY")
session = app.browser()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(session.cdp_url)
    context = browser.contexts[0]
    page = context.pages[0] if context.pages else context.new_page()

    page.goto("https://example.com")
    print(page.title())

    browser.close()

app.delete_browser(session.id)

# Use o cdpUrl retornado na resposta da sessão
agent-browser open https://example.com --cdp "$CDP_URL"
agent-browser snapshot --cdp "$CDP_URL"

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.

Get Started

Core Endpoints

More

Quickstarts

Developer Guides

Webhooks

Use Cases

Other

Contributing

Sandbox de Navegador

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

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