Pular para o conteúdo principal
Faça o scraping de uma página para obter dados limpos e, em seguida, chame /interact para começar a realizar ações nessa página - clicar em botões, preencher formulários, extrair conteúdo dinâmico ou navegar mais profundamente. Basta descrever o que você quer, ou escrever código se precisar de controle total.

Prompts de IA

Descreva a ação que você quer executar na página

Execução de código

Interaja com segurança por meio da execução de código usando playwright, agent-browser

Visualização em tempo real

Assista ou interaja com o navegador em tempo real por meio de um stream incorporável

Como funciona

  1. Faça o scraping de uma URL com POST /v2/scrape. A resposta inclui um scrapeId em data.metadata.scrapeId. Opcionalmente, passe um profile para persistir o estado do navegador entre sessões.
  2. Interaja chamando POST /v2/scrape/{scrapeId}/interact com um prompt ou com code do Playwright. Na primeira chamada, a sessão extraída é retomada e você pode começar a interagir com a página.
  3. Encerre a sessão com DELETE /v2/scrape/{scrapeId}/interact quando terminar.

Início rápido

Faça o scraping de uma página, interaja com ela e encerre a sessão:
from firecrawl import Firecrawl

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

# 1. Fazer scraping da página inicial da Amazon
result = app.scrape("https://www.amazon.com", formats=["markdown"])
scrape_id = result.metadata["scrapeId"]

# 2. Interagir — buscar um produto e obter seu preço
app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max")
response = app.interact(scrape_id, prompt="Click on the first result and tell me the price")
print(response.output)

# 3. Encerrar a sessão
app.stop_interaction(scrape_id)
Response
{
  "success": true,
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "The iPhone 16 Pro Max (256GB) is priced at $1,199.00.",
  "exitCode": 0,
  "killed": false
}

Interaja usando prompts

A forma mais simples de interagir com uma página. Descreva o que você quer em linguagem natural, e ele clicará, digitará, rolará a página e extrairá dados automaticamente.
response = app.interact(scrape_id, prompt="What are the customer reviews saying about battery life?")
print(response.output)
A resposta inclui um campo output com a resposta do agente:
Response
{
  "success": true,
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "Customers are generally positive about battery life. Most reviewers report 8-10 hours of use on a single charge. A few noted it drains faster with heavy multitasking.",
  "stdout": "...",
  "result": "...",
  "stderr": "",
  "exitCode": 0,
  "killed": false
}

Mantenha os Prompts Pequenos e Focados

Prompts funcionam melhor quando cada um é uma tarefa única e clara. Em vez de pedir ao agente para executar um fluxo de trabalho complexo com várias etapas de uma só vez, divida isso em chamadas interact separadas. Cada chamada reutiliza a mesma sessão do navegador, então o estado é mantido entre elas.

Executando código

Para ter controle total, você pode executar código diretamente no sandbox do navegador. A variável page (um objeto Page do Playwright) está disponível tanto em Node.js quanto em Python. O modo Bash vem com agent-browser pré-instalado.

Node.js (Playwright)

A linguagem padrão. Escreva código Playwright diretamente — page já está conectado ao navegador.
response = app.interact(scrape_id, code="""
// Clique em um botão e aguarde a navegação
await page.click('#next-page');
await page.waitForLoadState('networkidle');

// Extraia o conteúdo da nova página
const title = await page.title();
const content = await page.$eval('.article-body', el => el.textContent);
JSON.stringify({ title, content });
""")
print(response.result)

Python

Defina language como "python" para a API do Python do Playwright.
response = app.interact(
    scrape_id,
    code="""
import json

await page.click('#load-more')
await page.wait_for_load_state('networkidle')

items = await page.query_selector_all('.item')
data = []
for item in items:
    text = await item.text_content()
    data.append(text.strip())

print(json.dumps(data))
""",
    language="python",
)
print(response.stdout)

Bash (agent-browser)

agent-browser é uma CLI pré-instalada no sandbox com mais de 60 comandos. Ela fornece uma árvore de acessibilidade com refs de elementos (@e1, @e2, …) — ideal para automação conduzida por LLM.
# Tire um snapshot para ver elementos interativos
snapshot = app.interact(
    scrape_id,
    code="agent-browser snapshot -i",
    language="bash",
)
print(snapshot.stdout)
# Resultado:
# [document]
#   @e1 [input type="text"] "Search..."
#   @e2 [button] "Search"
#   @e3 [link] "About"

# Interaja com elementos usando @refs
app.interact(
    scrape_id,
    code='agent-browser fill @e1 "firecrawl" && agent-browser click @e2',
    language="bash",
)
Comandos comuns do agent-browser:
ComandoDescrição
snapshotÁrvore de acessibilidade completa com refs de elementos
snapshot -iApenas elementos interativos
click @e1Clica no elemento pela ref
fill @e1 "text"Limpa o campo e digita o texto
type @e1 "text"Digita sem limpar
press EnterPressiona uma tecla do teclado
scroll down 500Rola 500 pixels para baixo
get text @e1Obtém o conteúdo de texto
get urlObtém a URL atual
wait @e1Aguarda o elemento
wait --load networkidleAguarda a rede ficar inativa
find text "X" clickEncontra o elemento pelo texto e clica
eval "js code"Executa JavaScript na página

visualização em tempo real

Toda resposta do interact inclui URLs para acompanhar a sessão do navegador em tempo real.
FieldDescription
liveViewUrlTransmissão somente leitura — incorpore para assistir à sessão
interactiveLiveViewUrlTransmissão interativa — os espectadores podem clicar, digitar e interagir
<!-- Visualização somente leitura -->
<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

<!-- Visualização interativa — os usuários podem controlar o navegador -->
<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />
A visualização em tempo real interativa é útil para criar UIs voltadas ao usuário final, nas quais os usuários precisam ver e interagir com o navegador — como em fluxos de login, resolução de CAPTCHA ou fluxos de trabalho guiados.

Ciclo de vida da sessão

Criação

A primeira chamada POST /v2/scrape/{scrapeId}/interact cria uma sessão do navegador em sandbox no mesmo estado da página que o seu scrape.

Reutilização

Chamadas subsequentes de interact no mesmo scrapeId reutilizam a sessão existente. O navegador permanece aberto e mantém seu estado entre as chamadas, para que você possa encadear várias interações:
# Primeira chamada — clicar em uma aba
app.interact(scrape_id, code="await page.click('#tab-2')")

# Segunda chamada — a aba ainda está selecionada, extrair seu conteúdo
result = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")
print(result.result)

Limpeza

Encerre a sessão explicitamente quando terminar:
app.stop_interaction(scrape_id)
As sessões também expiram automaticamente com base no TTL (default: 10 minutes) ou no tempo limite de inatividade (default: 5 minutes).
Sempre encerre as sessões quando terminar para evitar cobrança desnecessária. Os créditos são rateados por segundo.

Perfis persistentes

Por padrão, cada sessão de scraping + interact começa com um navegador limpo. Com profile, você pode salvar e reutilizar o estado do navegador (cookies, localStorage, sessões) entre scrapes. Isso é útil para continuar conectado e preservar preferências. Passe o parâmetro profile ao chamar o scraping. Sessões com o mesmo nome de perfil compartilham o estado.
from firecrawl import Firecrawl

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

# Sessão 1: Scraping com um perfil, faça login e pare (o estado é salvo)
result = app.scrape(
    "https://app.example.com/login",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": True},
)
scrape_id = result.metadata["scrapeId"]

app.interact(scrape_id, prompt="Fill in user@example.com and password, then click Login")
app.stop_interaction(scrape_id)

# Sessão 2: Scraping com o mesmo perfil — já autenticado
result = app.scrape(
    "https://app.example.com/dashboard",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": True},
)
scrape_id = result.metadata["scrapeId"]

response = app.interact(scrape_id, prompt="Extract the dashboard data")
print(response.output)
app.stop_interaction(scrape_id)
ParâmetroPadrãoDescrição
nameUm nome para o perfil persistente. Scrapes com o mesmo nome compartilham o estado do navegador.
saveChangestrueQuando true, o estado do navegador é salvo novamente no perfil quando a sessão de interact é encerrada. 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 do navegador é salvo quando a sessão de interact é encerrada. Sempre encerre a sessão quando terminar para que o perfil possa ser reutilizado.

Quando usar o quê

Use CaseRecommendedWhy
Busca na webSearchEndpoint de busca dedicado
Obter conteúdo limpo de uma URLScrapeUma chamada de API, sem necessidade de sessão
Clicar, digitar e navegar em uma páginaInteract (prompt)Basta descrever em inglês
Extrair dados por trás das interaçõesInteract (prompt)Não são necessários seletores
Lógica de scraping complexaInteract (code)Controle total do Playwright
Interact vs Browser Sandbox: O Interact é construído sobre a mesma infraestrutura que o Browser Sandbox, mas oferece uma interface melhor para o padrão mais comum — fazer scrape de uma página e depois se aprofundar. O Browser Sandbox é melhor quando você precisa de uma sessão do navegador independente que não esteja vinculada a um scrape específico.

Preços

2 créditos por minuto de sessão, cobrados proporcionalmente por segundo. O scraping em si é cobrado separadamente (1 crédito por scraping, além de quaisquer custos específicos do formato).

Referência da API

Corpo da Requisição (POST)

CampoTipoPadrãoDescrição
promptstringTarefa em linguagem natural para o agente de IA. Obrigatório se code não estiver definido. Máx. 10.000 caracteres.
codestringCódigo a ser executado (Node.js, Python ou Bash). Obrigatório se prompt não estiver definido. Máx. 100.000 caracteres.
languagestring"node""node", "python" ou "bash". Usado apenas com code.
timeoutnumber30Tempo limite em segundos (1–300).
originstringIdentificador do chamador para acompanhamento de atividades.

Resposta

FieldDescription
successtrue se a execução for concluída sem erros
liveViewUrlURL de visualização ao vivo somente leitura para a sessão do navegador
interactiveLiveViewUrlURL de visualização ao vivo interativa (os visualizadores podem controlar o navegador)
outputA resposta em linguagem natural do agente ao seu prompt. Presente apenas ao usar prompt.
stdoutSaída padrão da execução do código
resultValor bruto retornado do sandbox. Para code: a última expressão avaliada. Para prompt: o snapshot bruto da página que o agente usou para produzir output.
stderrSaída de erro padrão
exitCodeCódigo de saída (0 = sucesso)
killedtrue se a execução tiver sido encerrada devido a tempo limite

Tem feedback ou precisa de ajuda? Envie um e-mail para help@firecrawl.com ou entre em contato no Discord.