Interact tras el scraping

Haz scraping de una página para obtener datos limpios y luego llama a /interact para empezar a realizar acciones en esa página: hacer clic en botones, completar formularios, extraer contenido dinámico o navegar más a fondo. Solo describe lo que quieres hacer, o escribe código si necesitas un control total.

Usa Interact vinculado al scraping cuando el flujo de trabajo comienza con POST /v2/scrape y la respuesta incluye data.metadata.scrapeId. Usa Browser Sandbox cuando necesites una sesión independiente con su propio ciclo de vida. El SDK de Python usa los equivalentes en snake_case (browser(), browser_execute(), list_browsers(), delete_browser(), interact(), stop_interaction()).

1. Haz scraping de una URL con POST /v2/scrape. La respuesta incluye un scrapeId en data.metadata.scrapeId. Si quieres conservar el estado del navegador, pasa profile en esta solicitud.
2. Interactúa llamando a POST /v2/scrape/{scrapeId}/interact con un prompt o con código de Playwright code. No pases profile aquí; la sesión de interacción hereda el perfil del trabajo de scraping.
3. Detén la sesión con DELETE /v2/scrape/{scrapeId}/interact cuando hayas terminado. En los perfiles con escritura, los cambios se guardan cuando la sesión se detiene.

Haz scraping de una página, interactúa con ella y detén la sesión:

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

La forma más simple de interactuar con una página. Describe lo que quieres en lenguaje natural y hará clic, escribirá, se desplazará y extraerá datos automáticamente.

La respuesta incluye un campo output con la respuesta del 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}

Los prompts funcionan mejor cuando cada uno consiste en una única tarea clara. En lugar de pedirle al agente que realice un flujo de trabajo complejo de varios pasos de una sola vez, divídelo en llamadas interact independientes. Cada llamada reutiliza la misma sesión del navegador, por lo que el estado se conserva entre una y otra.

Para tener control total, puedes ejecutar código directamente en el sandbox del navegador. La variable page (un objeto Page de Playwright) está disponible en Node.js y Python. El modo Bash incluye agent-browser preinstalado. También puedes hacer capturas de pantalla dentro de la sesión: usa (await page.screenshot()).toString("base64") en Node.js, await page.screenshot(path="/tmp/screenshot.png") en Python o agent-browser screenshot en Bash.

El lenguaje predeterminado. Escribe código de Playwright directamente. page ya está conectado al navegador.

Configura language como "python" para usar la API de Python de Playwright.

agent-browser es una CLI preinstalada en el sandbox con más de 60 comandos. Proporciona un árbol de accesibilidad con referencias de elementos (@e1, @e2, ...), lo que es ideal para la automatización controlada por LLM.

Comandos comunes de agent-browser:

Cada respuesta de interact devuelve una liveViewUrl que puedes incrustar para ver el navegador en tiempo real. Es útil para depuración, demos o para crear interfaces con 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" />

La respuesta también incluye un interactiveLiveViewUrl. A diferencia de la vista en vivo estándar, que es solo de visualización, la vista en vivo interactiva permite a los usuarios hacer clic, escribir e interactuar con la sesión del navegador directamente a través del stream integrado. Esto resulta útil para crear interfaces de navegador orientadas al usuario, como flujos de inicio de sesión o flujos de trabajo guiados en los que los usuarios finales necesitan controlar el navegador.

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

Cada respuesta de interact también devuelve una cdpUrl: la URL de WebSocket sin procesar del Chrome DevTools Protocol (CDP) para la sesión del navegador. Úsala para conectarte directamente a la sesión activa desde Playwright, Puppeteer o cualquier cliente CDP, y controlar el navegador con tu propio código.

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

La primera llamada POST /v2/scrape/{scrapeId}/interact continúa la sesión de scraping e inicia la interacción.

Las llamadas posteriores a interact sobre el mismo scrapeId reutilizan la sesión existente. El navegador permanece abierto y conserva su estado entre llamadas, por lo que puedes encadenar varias interacciones:

# Primera llamada: haz clic en una pestañaapp.interact(scrape_id, code="await page.click('#tab-2')")# Segunda llamada: la pestaña sigue seleccionada, extrae su contenidoresult = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")print(result.result)

Detén la sesión explícitamente al terminar:

Las sesiones también expiran automáticamente según el TTL (predeterminado: 10 minutos) o el timeout de inactividad (predeterminado: 5 minutos).

De forma predeterminada, cada sesión de scraping + interact se inicia con un navegador limpio. Con profile, puedes guardar y reutilizar el estado del navegador (cookies, localStorage, sesiones) entre scrapings. Esto resulta útil para mantener la sesión iniciada y conservar las preferencias.

Pasa el objeto profile en la solicitud inicial POST /v2/scrape. No pases profile a POST /v2/scrape/{scrapeId}/interact; la sesión de interact reutiliza la sesión del navegador y la configuración del perfil del trabajo de scraping. Detén la sesión de interact con DELETE /v2/scrape/{scrapeId}/interact para que puedan guardarse los cambios del perfil.

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"

El ciclo de vida del perfil es:

1. Crea el scraping con profile.name y saveChanges: true.
2. Ejecuta interacciones con prompt o código usando el scrapeId devuelto.
3. Detén la sesión para guardar cookies, localStorage y otro estado del navegador.
4. Inicia un scraping posterior con el mismo profile.name. Usa saveChanges: false cuando solo quieras leer el estado existente sin volver a escribir cambios.

El estado del navegador se guarda cuando se detiene la sesión de interact. Detén siempre la sesión cuando termines para que el perfil pueda reutilizarse.

Puedes probar la persistencia sin depender de un flujo de inicio de sesión real: escribe un valor en localStorage en una sesión, detenla y luego lee ese valor en una segunda sesión con el mismo perfil.

# Sesión 1: escribir el estado del navegador y guardarloRESPONSE=$(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"# Sesión 2: cargar el mismo perfil en modo de solo lectura y verificar el valorRESPONSE=$(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": false }  }')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: localStorage.getItem(\"firecrawlProfileCheck\"), cookie: document.cookie.includes(\"firecrawl_profile_check=saved\") }));"  }'curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

La segunda respuesta de Interact debería mostrar localStorage como "saved" y cookie como true.

• Solo código (sin prompt): 2 credits por minuto de sesión
• Con prompts de IA: 7 credits por minuto de sesión
• scraping: se factura por separado (1 credit por scraping, más cualquier costo específico del formato)

• Ejecutar Interact: POST /v2/scrape/{scrapeId}/interact
• Detener Interact: DELETE /v2/scrape/{scrapeId}/interact

¿Tienes comentarios o necesitas ayuda? Envía un correo a help@firecrawl.com o comunícate en Discord.