Saltar al contenido principal
Extrae 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.

Prompts de IA

Describe qué acción quieres realizar en la página

Ejecución de código

Interactúa de forma segura mediante la ejecución de código con playwright, agent-browser

Vista en vivo

Observa o interactúa con el browser en tiempo real mediante un stream incrustable

Cómo funciona

  1. Haz scraping de una URL con POST /v2/scrape. La respuesta incluye un scrapeId en data.metadata.scrapeId. Opcionalmente, pasa un profile para conservar el estado del navegador entre sesiones.
  2. Interactúa llamando a POST /v2/scrape/{scrapeId}/interact con un prompt o con código de Playwright code. En la primera llamada, se reanuda la sesión de scraping y puedes empezar a interactuar con la página.
  3. Detén la sesión con DELETE /v2/scrape/{scrapeId}/interact cuando hayas terminado.

Inicio rápido

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

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

# 1. Extraer la página principal de Amazon
result = app.scrape("https://www.amazon.com", formats=["markdown"])
scrape_id = result.metadata["scrapeId"]

# 2. Interactuar — buscar un producto y obtener su precio
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. Detener la sesión
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
}

Interactúa mediante prompts

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.
response = app.interact(scrape_id, prompt="What are the customer reviews saying about battery life?")
print(response.output)
La respuesta incluye un campo output con la respuesta del 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
}

Mantén los prompts pequeños y enfocados

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.

Ejecución de código

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.

Node.js (Playwright)

El lenguaje predeterminado. Escribe código de Playwright directamente — page ya está conectado al navegador.
response = app.interact(scrape_id, code="""
// Hacer clic en un botón y esperar la navegación
await page.click('#next-page');
await page.waitForLoadState('networkidle');

// Extraer contenido de la nueva 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

Configura language como "python" para usar la API de Python de 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 es una CLI preinstalada en el sandbox con más de 60 comandos. Proporciona un árbol de accesibilidad con referencias de elementos (@e1, @e2, …) — ideal para la automatización controlada por LLM.
# Tomar una instantánea para ver los elementos interactivos
snapshot = app.interact(
    scrape_id,
    code="agent-browser snapshot -i",
    language="bash",
)
print(snapshot.stdout)
# Salida:
# [document]
#   @e1 [input type="text"] "Search..."
#   @e2 [button] "Search"
#   @e3 [link] "About"

# Interactuar con elementos usando @refs
app.interact(
    scrape_id,
    code='agent-browser fill @e1 "firecrawl" && agent-browser click @e2',
    language="bash",
)
Comandos comunes de agent-browser:
ComandoDescripción
snapshotÁrbol de accesibilidad completo con referencias de elementos
snapshot -iSolo elementos interactivos
click @e1Hacer clic en un elemento por referencia
fill @e1 "text"Borrar el campo y escribir texto
type @e1 "text"Escribir sin borrar
press EnterPulsar una tecla del teclado
scroll down 500Desplazarse 500 píxeles hacia abajo
get text @e1Obtener el contenido de texto
get urlObtener la URL actual
wait @e1Esperar a que aparezca el elemento
wait --load networkidleEsperar a que la red quede inactiva
find text "X" clickBuscar un elemento por texto y hacer clic
eval "js code"Ejecutar JavaScript en la página

vista en vivo

Cada respuesta de interact incluye URL para ver la sesión del navegador en tiempo real.
FieldDescription
liveViewUrlTransmisión de solo lectura — incrústala para ver la sesión
interactiveLiveViewUrlTransmisión interactiva — los espectadores pueden hacer clic, escribir e interactuar
<!-- Read-only view -->
<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

<!-- Interactive view — viewers can control the browser -->
<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />
La vista en vivo interactiva es útil para crear interfaces orientadas al usuario final, donde los usuarios necesitan ver e interactuar con el navegador, como en flujos de inicio de sesión, resolución de CAPTCHA o flujos de trabajo guiados.

Ciclo de vida de la sesión

Creación

La primera llamada POST /v2/scrape/{scrapeId}/interact crea una sesión del navegador aislada con el mismo estado de la página que tu scraping.

Reutilizació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ña
app.interact(scrape_id, code="await page.click('#tab-2')")

# Segunda llamada — la pestaña sigue seleccionada, extrae su contenido
result = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")
print(result.result)

Limpieza

Detén la sesión explícitamente al terminar:
app.stop_interaction(scrape_id)
Las sesiones también expiran automáticamente según el TTL (predeterminado: 10 minutos) o el timeout de inactividad (predeterminado: 5 minutos).
Detén siempre las sesiones al terminar para evitar Billing innecesario. Los credits se prorratean por segundo.

Perfiles persistentes

De forma predeterminada, cada sesión de scrape + interact se inicia con un navegador limpio. Con profile, puedes guardar y reutilizar el estado del navegador (cookies, localStorage, sesiones) entre scrapes. Esto resulta útil para mantener la sesión iniciada y conservar las preferencias. Pasa el parámetro profile al llamar a scrape. Las sesiones con el mismo nombre de perfil comparten estado.
from firecrawl import Firecrawl

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

# Sesión 1: Scrape con un perfil, iniciar sesión y luego detener (el estado se guarda)
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)

# Sesión 2: Scrape con el mismo perfil — ya con sesión iniciada
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ámetroPredeterminadoDescripción
nameNombre del perfil persistente. Los scrapes con el mismo nombre comparten el estado del navegador.
saveChangestrueCuando es true, el estado del navegador se vuelve a guardar en el perfil cuando se detiene la sesión de interact. Establécelo en false para cargar datos existentes sin escribir cambios, lo que resulta útil cuando necesitas varios lectores concurrentes.
Solo una sesión puede guardar en un perfil a la vez. Si otra sesión ya está guardando, recibirás un error 409. Aun así, puedes abrir el mismo perfil con saveChanges: false o volver a intentarlo más tarde.
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.

Cuándo usar cada opción

Caso de usoRecomendadoPor qué
Búsqueda webSearchEndpoint de búsqueda específico
Obtener contenido limpio de una URLScrapeUna llamada a la API, sin necesidad de sesión
Hacer clic, escribir y navegar en una páginaInteract (prompt)Solo descríbelo en inglés
Extraer datos tras interaccionesInteract (prompt)No se necesitan selectores
Lógica de scraping complejaInteract (code)Control total de Playwright
Interact vs Browser Sandbox: Interact se basa en la misma infraestructura que Browser Sandbox, pero ofrece una mejor interfaz para el patrón más común: hacer scraping de una página y luego profundizar. Browser Sandbox es mejor cuando necesitas una sesión del navegador independiente que no esté vinculada a un scraping específico.

Precios

2 credits por minuto de sesión, prorrateado por segundo. El scraping en sí se factura por separado (1 credit por scraping, más cualquier costo específico del formato).

Referencia de la API

Cuerpo de la solicitud (POST)

CampoTipoPredeterminadoDescripción
promptstringTarea en lenguaje natural para el agente de IA. Obligatorio si no se establece code. Máximo 10.000 caracteres.
codestringCódigo que se va a ejecutar (Node.js, Python o Bash). Obligatorio si no se establece prompt. Máximo 100.000 caracteres.
languagestring"node""node", "python" o "bash". Solo se usa con code.
timeoutnumber30Timeout en segundos (1–300).
originstringIdentificador del llamante para el seguimiento de la actividad.

Respuesta

FieldDescription
successtrue si la ejecución se completó sin errores
liveViewUrlURL de vista en vivo de solo lectura para la sesión del navegador
interactiveLiveViewUrlURL de vista en vivo interactiva (quienes la vean pueden controlar el navegador)
outputLa respuesta en lenguaje natural del agente a tu prompt. Solo está presente cuando se utiliza prompt.
stdoutSalida estándar de la ejecución del código
resultValor de retorno sin procesar del sandbox. Para code: la última expresión evaluada. Para prompt: la captura sin procesar de la página que el agente utilizó para producir output.
stderrSalida de error estándar
exitCodeCódigo de salida (0 = éxito)
killedtrue si la ejecución se finalizó debido a timeout

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