Interaja após o scraping

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.

Use o interagir vinculado ao scraping quando o fluxo de trabalho começar com POST /v2/scrape e a resposta incluir data.metadata.scrapeId. Use o Browser Sandbox quando precisar de uma sessão autônoma com seu próprio ciclo de vida. O SDK Python usa os equivalentes em snake_case (browser(), browser_execute(), list_browsers(), delete_browser(), interact(), stop_interaction()).

1. Faça o scraping de uma URL com POST /v2/scrape. A resposta inclui um scrapeId em data.metadata.scrapeId. Se você quiser persistir o estado do navegador, passe profile nesta solicitação.
2. Interaja chamando POST /v2/scrape/{scrapeId}/interact com um prompt ou com code do Playwright. Não passe profile aqui; a sessão de interação herda o perfil do job de scraping.
3. Encerre a sessão com DELETE /v2/scrape/{scrapeId}/interact quando terminar. Para perfis graváveis, as mudanças são salvas quando a sessão é encerrada.

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

{  "success": true,  "cdpUrl": "wss://browser.firecrawl.dev/...",  "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}

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.

A resposta inclui um campo output com a resposta do agente:

{  "success": true,  "cdpUrl": "wss://browser.firecrawl.dev/...",  "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}

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.

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. Você também pode fazer capturas de tela na sessão: use (await page.screenshot()).toString("base64") em Node.js, await page.screenshot(path="/tmp/screenshot.png") em Python ou agent-browser screenshot no Bash.

A linguagem padrão. Escreva código Playwright diretamente. page já está conectado ao navegador.

Defina language como "python" para a API do Python do Playwright.

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, ...), o que é ideal para automação conduzida por LLM.

Comandos comuns do agent-browser:

Toda resposta de interact retorna uma liveViewUrl que você pode incorporar para acompanhar o navegador em tempo real. Útil para depuração, demonstrações ou para criar UIs com navegador.

{  "success": true,  "cdpUrl": "wss://browser.firecrawl.dev/...",  "liveViewUrl": "https://liveview.firecrawl.dev/...",  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",  "stdout": "",  "result": "...",  "exitCode": 0}

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

A resposta também inclui uma interactiveLiveViewUrl. Diferentemente da visualização em tempo real padrão, que é somente para visualização, a visualização em tempo real interativa permite que os usuários cliquem, digitem e interajam com a sessão do navegador diretamente pelo stream incorporado. Isso é útil para criar interfaces de navegador voltadas para o usuário final, como fluxos de login ou fluxos de trabalho guiados em que os usuários finais precisam controlar o navegador.

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

Toda resposta de interação também retorna uma cdpUrl: a URL WebSocket bruta do Chrome DevTools Protocol (CDP) da sessão do navegador. Use-a para se conectar diretamente à sessão ativa pelo Playwright, Puppeteer ou qualquer cliente CDP e controlar o navegador com seu próprio código.

import { chromium } from "playwright";const browser = await chromium.connectOverCDP(cdpUrl);const context = browser.contexts()[0];const page = context.pages()[0];

A primeira POST /v2/scrape/{scrapeId}/interact dá continuidade à sessão de scraping e inicia a interaçã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 abaapp.interact(scrape_id, code="await page.click('#tab-2')")# Segunda chamada: a aba ainda está selecionada, extrair seu conteúdoresult = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")print(result.result)

Encerre a sessão explicitamente quando terminar:

As sessões também expiram automaticamente com base no TTL (padrão: 10 minutes) ou no tempo limite de inatividade (padrão: 5 minutes).

Por padrão, cada sessão de scraping + interagir 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 objeto profile na requisição inicial POST /v2/scrape. Não passe profile para POST /v2/scrape/{scrapeId}/interact; a sessão de interagir reutiliza a sessão do navegador e as configurações de perfil do scrape job. Encerre a sessão de interagir com DELETE /v2/scrape/{scrapeId}/interact para que mudanças graváveis no perfil possam ser salvas.

curl -X POST "https://api.firecrawl.dev/v2/scrape" \  -H "Authorization: Bearer fc-YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com",    "formats": ["markdown"],    "profile": {      "name": "my-profile",      "saveChanges": true    }  }'curl -X POST "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \  -H "Authorization: Bearer fc-YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "prompt": "Click the login button"  }'curl -X DELETE "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \  -H "Authorization: Bearer fc-YOUR_API_KEY"

O ciclo de vida do perfil é:

1. Crie o scraping com profile.name e saveChanges: true.
2. Execute interações por prompt ou código usando o scrapeId retornado.
3. Encerre a sessão para salvar cookies, localStorage e outros estados do navegador.
4. Inicie um scraping posterior com o mesmo profile.name. Use saveChanges: false quando quiser apenas ler o estado existente sem gravar as mudanças de volta.

O estado do navegador é salvo quando a sessão de interagir é encerrada. Sempre encerre a sessão quando terminar para que o perfil possa ser reutilizado.

Você pode testar a persistência sem depender de um fluxo de login real gravando um valor no localStorage em uma sessão, encerrando-a e, em seguida, lendo esse valor em uma segunda sessão com o mesmo perfil.

# Sessão 1: gravar o estado do navegador e salvá-loRESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com",    "formats": ["markdown"],    "profile": { "name": "profile-validation", "saveChanges": true }  }')SCRAPE_ID=$(echo "$RESPONSE" | jq -r ".data.metadata.scrapeId")curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "code": "await page.evaluate(() => { localStorage.setItem(\"firecrawlProfileCheck\", \"saved\"); document.cookie = \"firecrawl_profile_check=saved; path=/; max-age=3600\"; return localStorage.getItem(\"firecrawlProfileCheck\"); });"  }'curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

A segunda resposta do Interagir deve mostrar localStorage como "saved" e cookie como true.

• Somente código (sem prompt): 2 créditos por minuto de sessão
• Com prompts de IA: 7 créditos por minuto de sessão
• Scraping: cobrado separadamente (1 crédito por scraping, além de quaisquer custos específicos do formato)

• Execute Interagir: POST /v2/scrape/{scrapeId}/interact
• Stop Interagir: DELETE /v2/scrape/{scrapeId}/interact

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