Agent

Elegir la herramienta adecuada. Agent es la opción correcta cuando no conoces las URL o necesitas navegación autónoma por la web.

Para una única URL conocida, el modo JSON en /scrape es más económico y sincrónico.
Comparación completa: Cómo elegir el extractor de datos.

Firecrawl /agent es una API mágica que busca, navega y recopila datos desde la gama más amplia de sitios web, encontrando datos en lugares de difícil acceso y descubriéndolos de formas que ninguna otra API puede. Consigue en pocos minutos lo que a una persona le llevaría muchas horas: recopilación de datos de extremo a extremo, sin necesidad de scripts ni trabajo manual. Tanto si necesitas un solo dato como conjuntos de datos completos a escala, Firecrawl /agent trabaja para obtener tus datos. Piensa en /agent como una investigación profunda de datos, ¡estén donde estén!

Research Preview: Agent está en acceso anticipado. Es de esperar que tenga algunos detalles por pulir. Mejorará significativamente con el tiempo.

Agent se basa en todo lo bueno de /extract y lo lleva más allá:

No requiere URL: solo describe lo que necesitas mediante el parámetro prompt. Las URL son opcionales
Búsqueda web profunda: busca y navega de forma autónoma en lo más profundo de los sitios para encontrar tus datos
Fiable y preciso: funciona con una gran variedad de consultas y casos de uso
Más rápido: procesa múltiples fuentes en paralelo para obtener resultados más rápido

Pruébalo en el Playground

Prueba el agente en el Playground interactivo, sin necesidad de programar.

Uso de `/agent`

El único parámetro obligatorio es prompt. Describe simplemente qué datos quieres extraer. Para obtener salida estructurada, proporciona un esquema JSON. Los SDK son compatibles con Pydantic (Python) y Zod (Node) para definiciones de esquemas con tipado seguro:

from firecrawl import Firecrawl
from pydantic import BaseModel, Field
from typing import List, Optional

app = Firecrawl(api_key="fc-YOUR_API_KEY")

class Founder(BaseModel):
    name: str = Field(description="Full name of the founder")
    role: Optional[str] = Field(None, description="Role or position")
    background: Optional[str] = Field(None, description="Professional background")

class FoundersSchema(BaseModel):
    founders: List[Founder] = Field(description="Lista de fundadores")

result = app.agent(
    prompt="Find the founders of Firecrawl",
    schema=FoundersSchema,
    model="spark-2",
    max_credits=100
)

print(result.data)

import { Firecrawl } from 'firecrawl';
import { z } from 'zod';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

const result = await firecrawl.agent({
  prompt: "Find the founders of Firecrawl",
  schema: z.object({
    founders: z.array(z.object({
      name: z.string().describe("Full name of the founder"),
      role: z.string().describe("Role or position").optional(),
      background: z.string().describe("Professional background").optional()
    })).describe("List of founders")
  }),
  model: "spark-2",
  maxCredits: 100
});

console.log(result.data);

curl -X POST "https://api.firecrawl.dev/v2/agent" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find the founders of Firecrawl",
    "model": "spark-2",
    "maxCredits": 100,
    "schema": {
      "type": "object",
      "properties": {
        "founders": {
          "type": "array",
          "description": "List of founders",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string", "description": "Full name" },
              "role": { "type": "string", "description": "Role or position" },
              "background": { "type": "string", "description": "Professional background" }
            },
            "required": ["name"]
          }
        }
      },
      "required": ["founders"]
    }
  }'

Respuesta

JSON

{
  "success": true,
  "status": "completed",
  "data": {
    "founders": [
      {
        "name": "Eric Ciarla",
        "role": "Co-founder",
        "background": "Previously at Mendable"
      },
      {
        "name": "Nicolas Camara",
        "role": "Co-founder",
        "background": "Previously at Mendable"
      },
      {
        "name": "Caleb Peffer",
        "role": "Co-founder",
        "background": "Previously at Mendable"
      }
    ]
  },
  "expiresAt": "2024-12-15T00:00:00.000Z",
  "creditsUsed": 15
}

Proporcionar URLs (opcional)

Puedes proporcionar URLs opcionalmente para centrar al agente en páginas específicas:

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

result = app.agent(
    urls=["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    prompt="Compara las características y la información de precios de estas páginas"
)

print(result.data)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

const result = await firecrawl.agent({
  urls: ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
  prompt: "Compare the features and pricing information from these pages"
});

console.log(result.data);

curl -X POST "https://api.firecrawl.dev/v2/agent" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://docs.firecrawl.dev",
      "https://firecrawl.dev/pricing"
    ],
    "prompt": "Compare the features and pricing information from these pages"
  }'

Estado y finalización de trabajos

Los trabajos de agente se ejecutan de forma asíncrona. Cuando envíes un trabajo, recibirás un ID de trabajo que podrás usar para comprobar su estado:

Método predeterminado: agent() espera y devuelve los resultados finales
Iniciar y luego consultar: Usa start_agent (Python) o startAgent (Node) para obtener un ID de trabajo de inmediato y luego consulta su estado con get_agent_status / getAgentStatus
Push en lugar de consultar: Pasa un webhook al iniciar el trabajo para recibir eventos de agente a medida que la ejecución avanza y finaliza

Los resultados de los trabajos estarán disponibles a través de la API durante 24 horas después de su finalización. Pasado este período, aún puedes ver el historial y los resultados de tu agente en los registros de actividad.

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# Iniciar una tarea del agente
agent_job = app.start_agent(
    prompt="Find the founders of Firecrawl"
)

# Check the status
status = app.get_agent_status(agent_job.id)

print(status)
# Example output:
# status='completed'
# success=True
# data={ ... }
# expires_at=datetime.datetime(...)
# credits_used=15

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// Inicia una tarea de agente
const started = await firecrawl.startAgent({
  prompt: "Find the founders of Firecrawl"
});

// Verifica el estado
if (started.id) {
  const status = await firecrawl.getAgentStatus(started.id);
  console.log(status.status, status.data);
}

curl -X GET "https://api.firecrawl.dev/v2/agent/<jobId>" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

Posibles estados

Estado	Descripción
`processing`	El agente todavía está trabajando en tu solicitud
`completed`	La extracción finalizó correctamente
`failed`	Se produjo un error durante la extracción, o el trabajo fue cancelado (los trabajos cancelados informan `failed` con un mensaje de error de cancelación)

La cancelación es cooperativa. Cuando llamas al endpoint de cancelación, la solicitud se registra de inmediato, pero cualquier paso que ya esté en curso (un paso de razonamiento del LLM, una llamada a una herramienta o una acción del navegador) se ejecuta hasta completarse correctamente antes de que el trabajo se detenga. Los créditos pueden seguir acumulándose durante ese breve intervalo, por lo que el valor final de creditsUsed puede ser mayor que el valor informado en el momento en que hiciste clic en cancelar. Un trabajo cancelado informa el estado failed al consultarse y emite un evento de webhook agent.cancelled.

Ejemplo en estado pendiente

JSON

{
  "success": true,
  "status": "processing",
  "expiresAt": "2024-12-15T00:00:00.000Z"
}

Ejemplo completado

JSON

{
  "success": true,
  "status": "completed",
  "data": {
    "founders": [
      {
        "name": "Eric Ciarla",
        "role": "Co-founder"
      },
      {
        "name": "Nicolas Camara",
        "role": "Co-founder"
      },
      {
        "name": "Caleb Peffer",
        "role": "Co-founder"
      }
    ]
  },
  "expiresAt": "2024-12-15T00:00:00.000Z",
  "creditsUsed": 15
}

Listado de ejecuciones de agentes

GET /agent lista todas las ejecuciones de agentes de tu equipo, empezando por las más recientes, incluidas las iniciadas desde el playground o la API. Cada entrada incluye el ID de la ejecución, la hora de creación, el estado, una breve referencia al objetivo y las opciones con las que se inició. Los resultados se dividen en páginas fijas de 20 ejecuciones. Cuando hay más páginas, la respuesta incluye una URL next; pasa su marca de tiempo before para obtener la página siguiente. Los métodos del SDK no paginan automáticamente, por lo que tú decides hasta dónde retroceder.

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# Lista tus ejecuciones de agente más recientes
page = app.list_agents()

for run in page.agents:
    print(run.id, run.status, run.target_hint)

# Obtén la siguiente página utilizando el cursor de `next`
if page.next:
    before = int(page.next.split("before=")[-1])
    older = app.list_agents(before=before)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// Lista tus agent runs más recientes
const page = await firecrawl.listAgents();

for (const run of page.agents ?? []) {
  console.log(run.id, run.status, run.targetHint);
}

// Obtén la siguiente página utilizando el cursor de `next`
if (page.next) {
  const before = Number(new URL(page.next).searchParams.get("before"));
  const older = await firecrawl.listAgents({ before });
}

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

# Obtener la siguiente página (marca de tiempo unix en ms de la URL `next` de la página anterior)
curl -X GET "https://api.firecrawl.dev/v2/agent?before=1756600000000" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

Seguimiento de una ejecución en curso

Agent no mantiene abierta una conexión de streaming. No hay flujo de eventos enviados por el servidor ni websocket, por lo que puedes seguir una ejecución sondeando su traza o recibiendo webhooks.

Superficie	Lo que obtienes	Ideal para
Sondeo de trazas	Todos los detalles: cada evento que la ejecución ha emitido hasta el momento, incluidas las llamadas a herramientas, los resúmenes de razonamiento, las fases de progreso y los cambios en los artefactos	Crear tu propia interfaz de usuario de progreso o depurar lo que realmente hizo una ejecución
Webhooks	Entrega mediante push, de granularidad amplia: los cinco eventos del ciclo de vida del agente (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). Consulta eventos de webhook	Reaccionar cuando finalice una ejecución sin mantener abierto un bucle de sondeo
Vista en vivo	Una vista del navegador del agente que una persona puede observar. Solicita la traza con `?liveView=true` y cada entrada de `activeBrowserSessions` incluye una `liveViewUrl`	Observar cómo navega una ejecución en tiempo real

Si ordenas los eventos de traza por tu cuenta, agrúpalos primero por agent.id: producerSequence es monótona para cada agente emisor, por lo que una única ordenación global intercala incorrectamente los eventos de un orquestador con los de sus subagentes. Los eventos también pueden llegar brevemente después del evento terminal run.finished, así que continúa sondeando durante un breve periodo adicional antes de mostrar el estado final.

import time
from collections import defaultdict

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

agent_job = app.start_agent(prompt="Find the founders of Firecrawl")
seen = set()
finished = False
quiet_polls = 0

while True:
    trace = app.get_agent_trace(agent_job.id)

    # producer_sequence es monótono por agente emisor, así que primero agrupamos.
    by_agent = defaultdict(list)
    for event in trace.events or []:
        by_agent[event.agent.id].append(event)

    new_events = 0
    for agent_id, events in by_agent.items():
        for event in sorted(events, key=lambda e: e.producer_sequence):
            if event.event_id not in seen:
                seen.add(event.event_id)
                new_events += 1
                print(agent_id, event.producer_sequence, event.type)

    if not finished:
        finished = app.get_agent_status(agent_job.id).status != "processing"
    elif new_events:
        quiet_polls = 0
    else:
        # Ventana final: pueden llegar eventos durante un instante después de que termine la ejecución.
        quiet_polls += 1
        if quiet_polls == 3:
            break

    time.sleep(5)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

const started = await firecrawl.startAgent({ prompt: "Find the founders of Firecrawl" });
const seen = new Set();
let finished = false;
let quietPolls = 0;

for (;;) {
  const trace = await firecrawl.getAgentTrace(started.id);

  // producerSequence es monótono por agente emisor, así que primero agrupamos.
  const byAgent = new Map();
  for (const event of trace.events ?? []) {
    const bucket = byAgent.get(event.agent.id) ?? [];
    bucket.push(event);
    byAgent.set(event.agent.id, bucket);
  }

  let newEvents = 0;
  for (const [agentId, events] of byAgent) {
    for (const event of events.sort((a, b) => a.producerSequence - b.producerSequence)) {
      if (seen.has(event.eventId)) continue;
      seen.add(event.eventId);
      newEvents++;
      console.log(agentId, event.producerSequence, event.type);
    }
  }

  if (!finished) {
    finished = (await firecrawl.getAgentStatus(started.id)).status !== "processing";
  } else if (newEvents) {
    quietPolls = 0;
  } else {
    // Ventana final: aún pueden llegar eventos poco después de que termine la ejecución.
    if (++quietPolls === 3) break;
  }

  await new Promise((resolve) => setTimeout(resolve, 5000));
}

# Imprime solo los eventos que aún no has visto y sigue consultando durante una
# breve ventana final después de que termine la ejecución.
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
: > "$tmp/seen.txt"
finished=0
quiet=0

while [ "$quiet" -lt 3 ]; do
  curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID/trace" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  | jq -r '.events | group_by(.agent.id)[] | sort_by(.producerSequence)[]
           | "\(.eventId) \(.agent.id) \(.producerSequence) \(.type)"' > "$tmp/poll.txt"

  new=$(grep -vxF -f "$tmp/seen.txt" "$tmp/poll.txt")
  [ -n "$new" ] && echo "$new"
  cp "$tmp/poll.txt" "$tmp/seen.txt"

  if [ "$finished" = 0 ]; then
    status=$(curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID" \
      -H "Authorization: Bearer $FIRECRAWL_API_KEY" | jq -r '.status')
    [ "$status" = "processing" ] || finished=1
  elif [ -n "$new" ]; then
    quiet=0
  else
    quiet=$((quiet + 1))
  fi

  sleep 5
done

Trazas de ejecución y snapshots

Cada ejecución registra una traza de ejecución canónica: una secuencia ordenada de eventos que incluye llamadas a herramientas, resúmenes de razonamiento, actualizaciones de progreso, sesiones de navegador y cambios en los artefactos de salida. Consúltala para depurar una ejecución o crear una interfaz de usuario de progreso en tiempo real:

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# Traza de ejecución de una ejecución: eventos ordenados (tool calls, razonamiento, artefactos)
trace = app.get_agent_trace("JOB_ID")

for event in trace.events or []:
    print(event.type)

# Incluye las browser sessions activas mientras la ejecución sigue en curso
live = app.get_agent_trace("JOB_ID", live_view=True)
for session in live.active_browser_sessions or []:
    print(session.live_view_url)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// Traza de ejecución de una ejecución: eventos ordenados (tool calls, razonamiento, artefactos)
const trace = await firecrawl.getAgentTrace("JOB_ID");

for (const event of trace.events ?? []) {
  console.log(event.type);
}

// Incluye las browser sessions activas mientras la ejecución está en curso
const live = await firecrawl.getAgentTrace("JOB_ID", { liveView: true });
console.log(live.activeBrowserSessions);

curl "https://api.firecrawl.dev/v2/agent/JOB_ID/trace" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# Incluir las sesiones de browser activas mientras la ejecución está en curso
curl "https://api.firecrawl.dev/v2/agent/JOB_ID/trace?liveView=true" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

Los eventos de traza artifact.updated hacen referencia a la salida de trabajo del agente mediante snapshotId. Obtén el contenido completo de un snapshot mediante el endpoint de snapshots:

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# Los eventos de traza artifact.updated hacen referencia al contenido de la instantánea mediante snapshotId
snapshot = app.get_agent_snapshot("JOB_ID", "SNAPSHOT_ID")

print(snapshot.snapshot)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// Los eventos de traza artifact.updated hacen referencia al contenido del snapshot mediante snapshotId
const snapshot = await firecrawl.getAgentSnapshot("JOB_ID", "SNAPSHOT_ID");

console.log(snapshot.snapshot);

curl "https://api.firecrawl.dev/v2/agent/JOB_ID/snapshots/SNAPSHOT_ID" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

Las trazas y los snapshots se registran en las ejecuciones de Spark 2, es decir, en todas las ejecuciones nuevas; los trabajos iniciados en modelos Spark 1 antes de su retirada no los incluyen. Consulta las referencias de la API de traza y snapshot para ver el esquema completo de eventos, y el catálogo de errores de Agent para conocer los fallos que devuelven estos endpoints.

Obtención de los datos de origen del agente

Durante su ejecución, un agente va escribiendo su salida de trabajo en artefactos, que puedes recuperar cuando tengas la traza de la ejecución. Cada evento artifact.updated describe un cambio en un artefacto: artifact.kind puede ser json, markdown, html, screenshot o text; artifact.path indica dónde lo guardó la ejecución, y artifact.snapshotId es el identificador que debes usar para obtener su contenido mediante GET /agent/{jobId}/snapshots/{snapshotId}. El endpoint de snapshots devuelve ese contenido en un campo snapshot como una cadena: en los artefactos json, esa cadena está codificada en JSON y debe decodificarse; en los artefactos markdown, html y text, es el contenido directamente. Para obtener el contenido de página que produjo una ejecución, recupera la traza, conserva los eventos artifact.updated cuyo kind te interese y, después, obtén cada snapshot:

import json

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

trace = app.get_agent_trace("JOB_ID")

for event in trace.events or []:
    if event.type != "artifact.updated":
        continue

    kind = event.artifact.kind
    if kind not in ("markdown", "html", "json"):
        continue

    snapshot = app.get_agent_snapshot("JOB_ID", event.artifact.snapshot_id)

    # los snapshots de markdown, html y texto son el contenido en sí.
    # los snapshots de json vienen codificados en JSON, así que hay que decodificarlos.
    content = json.loads(snapshot.snapshot) if kind == "json" else snapshot.snapshot

    print(kind, event.artifact.path, content)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

const trace = await firecrawl.getAgentTrace("JOB_ID");

for (const event of trace.events ?? []) {
  if (event.type !== "artifact.updated") continue;

  const kind = event.artifact.kind;
  if (!["markdown", "html", "json"].includes(kind)) continue;

  const snapshot = await firecrawl.getAgentSnapshot("JOB_ID", event.artifact.snapshotId);

  // los snapshots de markdown, html y texto son el contenido en sí.
  // los snapshots de json vienen codificados en JSON, así que hay que decodificarlos.
  const content = kind === "json" ? JSON.parse(snapshot.snapshot) : snapshot.snapshot;

  console.log(kind, event.artifact.path, content);
}

# Obtén todos los artifacts markdown, html o json generados por la ejecución.
curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID/trace" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
| jq -r '.events[]
         | select(.type == "artifact.updated")
         | select(.artifact.kind == "markdown" or .artifact.kind == "html" or .artifact.kind == "json")
         | "\(.artifact.kind) \(.artifact.snapshotId)"' \
| while read -r kind snapshot_id; do
    body=$(curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID/snapshots/$snapshot_id" \
      -H "Authorization: Bearer $FIRECRAWL_API_KEY")

    # los snapshots markdown y html son el contenido en sí; json viene codificado en JSON.
    if [ "$kind" = "json" ]; then
      printf '%s' "$body" | jq -r '.snapshot | fromjson'
    else
      printf '%s' "$body" | jq -r '.snapshot'
    fi
  done

Conviene tener en cuenta dos aspectos antes de desarrollar sobre esta base:

Los artefactos son la salida de la ejecución, no un archivo de cada página. Lo que una ejecución escribe en un artefacto depende de cómo resuelva tu prompt, así que considera el conjunto de artefactos como lo que produjo esa ejecución concreta, no como un registro garantizado de todas las páginas que abrió.
Los resultados de las herramientas contienen el resto. Cada evento tool_call.finished incluye un campo result con lo que devolvió la herramienta, donde aparece el contenido que nunca llegó a convertirse en un artefacto.

Puedes compartir ejecuciones del agente directamente desde el Agent Playground. Los enlaces compartidos son públicos: cualquier persona que tenga el enlace puede ver la salida y la actividad de la ejecución, y puedes revocar el acceso en cualquier momento para desactivar el enlace. Los motores de búsqueda no indexan las páginas compartidas.

Selección de modelo

Firecrawl Agent se ejecuta con Spark 2 —más económico y rápido que los modelos anteriores de Spark 1, con una precisión comparable—. Es el modelo predeterminado: todas las ejecuciones usan spark-2, tanto si se establece el parámetro model como si no.

Los modelos Spark 1 están obsoletos. Los nombres de modelo de Spark 1 se siguen aceptando por compatibilidad con versiones anteriores, pero las solicitudes que los usan se redirigen a spark-2.

Spark 2

spark-2 gestiona toda la gama de tareas que antes requerían elegir entre Mini y Pro, por lo que no es necesario sacrificar precisión por costo. Aspectos destacados:

El menor costo por ejecución
El tiempo de ejecución más rápido
Precisión comparable a la del anterior modelo insignia Spark 1
El único modelo con un presupuesto de razonamiento: pasa effort (low, medium o high) para controlar cuánto razona

Especificar un modelo

El parámetro model es opcional; todas las solicitudes usan spark-2:

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# Spark 2 es el predeterminado — todas las ejecuciones se realizan con él
result = app.agent(
    prompt="Find the pricing of Firecrawl",
    model="spark-2"
)

# Obsoleto: los nombres de modelo de Spark 1 se siguen aceptando, pero se redirigen a "spark-2".

print(result.data)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// Spark 2 es el predeterminado — todas las ejecuciones se realizan con él
const result = await firecrawl.agent({
  prompt: "Find the pricing of Firecrawl",
  model: "spark-2"
});

// Obsoleto: los nombres de modelo de Spark 1 aún se aceptan, pero se redirigen a "spark-2".

console.log(result.data);

# Spark 2 es el modelo predeterminado: todas las ejecuciones lo usan
curl -X POST "https://api.firecrawl.dev/v2/agent" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find the pricing of Firecrawl",
    "model": "spark-2"
  }'

# Obsoleto: los nombres de modelo de Spark 1 se siguen aceptando, pero se redirigen a "spark-2".

Proveedores de datos que requieren aceptar términos

Agent puede llamar a proveedores de datos de Alexandria durante una ejecución, pero solo a aquellos cuyos términos de datos haya aceptado tu equipo. Nunca se llama a un provider cuyos términos no hayas aceptado, sea cual sea el valor de exchange.onTermsRequired. La ejecución continúa con los proveedores que puede usar, y la respuesta de estado indica cuáles omitió. No existe un modo de aceptación automática. Aceptar los términos de un provider siempre requiere que una persona dé su conformidad, ya sea en el Dashboard o mediante una llamada a terms/accept que realice tu aplicación después de que su usuario haya dado su consentimiento explícito. Si construyes un agente sobre Firecrawl, este debe consultar a su usuario antes de llamar a terms/accept. Solicitar datos no equivale a aceptar los términos de un provider.

`onTermsRequired`	Qué ocurre
`skip` (predeterminado)	La ejecución responde solo con proveedores aceptados y nunca se bloquea. `exchange.skippedProviders` enumera los proveedores restringidos que habrían resultado útiles.
`ask`	Igual que `skip`. Además, la ejecución termina con `exchange.requiresAction` y un `pendingApproval` de `kind: "terms"`, para que puedas consultar a tu usuario, aceptar los términos y continuar el hilo.

Si omites onTermsRequired en un turno posterior de un hilo, se usa el valor del turno anterior. Si un turno termina con una aprobación de llamada de pago (requireApproval), no incluye ninguna oferta de términos.

Campos de la respuesta

Estos campos se encuentran en el objeto exchange de GET /v2/agent/{id}:

skippedProviders (cualquier modo): una entrada por cada provider restringido que habría sido útil, con provider, name, capability, adds (lo que habría aportado), reason: "terms_required", version (la versión de los términos) y termsUrl (dónde aceptarlos en el Dashboard).
requiresAction (solo ask): type: "accept_terms", un approvalId y una lista providers. approvalId siempre está presente. Es el id de la aprobación pendiente de terms que respondes al continuar el hilo. Cada provider incluye las llamadas exactas de show (terms/show) y accept (terms/accept) que debes realizar. El digest de cada provider (y accept.options.digest) siempre está presente y puede ser null, lo que indica que el catálogo no publicó ninguno. En ese caso, ejecuta primero terms/show y envía el digest que devuelve.

{
  "status": "completed",
  "exchange": {
    "enabled": true,
    "onTermsRequired": "ask",
    "paidCalls": 0,
    "creditsUsed": null,
    "skippedProviders": [
      {
        "provider": "apollo",
        "name": "Apollo",
        "capability": "people/search",
        "adds": "verified work emails and direct phone numbers",
        "reason": "terms_required",
        "version": "F-1.0.0",
        "termsUrl": "https://www.firecrawl.dev/app/alexandria/apollo"
      }
    ],
    "requiresAction": {
      "type": "accept_terms",
      "approvalId": "0199aaaa-0000-7000-8000-000000000000",
      "providers": [
        {
          "provider": "apollo",
          "name": "Apollo",
          "capability": "people/search",
          "version": "F-1.0.0",
          "digest": "<sha256>",
          "url": "https://www.firecrawl.dev/app/alexandria/apollo",
          "show": { "provider": "firecrawl", "capability": "terms/show", "options": { "provider": "apollo" } },
          "accept": {
            "provider": "firecrawl",
            "capability": "terms/accept",
            "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "<sha256>", "confirmed": true }
          }
        }
      ]
    }
  },
  "pendingApproval": {
    "id": "0199aaaa-0000-7000-8000-000000000000",
    "kind": "terms",
    "reason": "Apollo could add verified work emails and direct phone numbers.",
    "calls": [],
    "terms": [{ "provider": "apollo", "name": "Apollo", "version": "F-1.0.0", "digest": "<sha256>", "url": "https://www.firecrawl.dev/app/alexandria/apollo" }],
    "resolution": null
  }
}

Acepta y luego continúa

En el modo ask:

Muestra los términos a tu usuario. Ejecuta la llamada show del provider a través de /v2/scrape con alexandria.
Solo si el usuario acepta explícitamente, ejecuta su llamada accept de la misma forma. Si accept.options.digest es null, usa el digest que devolvió terms/show:

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alexandria": {
      "provider": "firecrawl",
      "capability": "terms/accept",
      "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "<sha256>", "confirmed": true }
    }
  }'

Continúa el mismo hilo con exchange.approve. La oferta se acepta en su totalidad, por lo que callIds y always se ignoran. El siguiente turno usa esos providers para cubrir la carencia que señaló la respuesta anterior, en lugar de volver a ejecutarlo todo.

curl -X POST https://api.firecrawl.dev/v2/agent \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "<threadId from the previous run>",
    "prompt": "Continue with Apollo.",
    "exchange": {
      "approve": { "approvalId": "0199aaaa-0000-7000-8000-000000000000" }
    }
  }'

Para seguir sin el provider, continúa con exchange.decline: { "approvalId": "..." }. Esto rechaza la oferta completa, y sus providers no se vuelven a ofrecer durante el resto del hilo. En el modo skip no hay ninguna aprobación pendiente que responder. Una vez aceptados los términos, inicia una nueva ejecución (o un nuevo turno del hilo) y el provider estará disponible.

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`prompt`	string	Sí	Descripción en lenguaje natural de los datos que deseas extraer (máx. 10.000 caracteres)
`model`	string	No	De forma predeterminada usa `spark-2`, el modelo con el que se ejecutan todas las ejecuciones. Los modelos Spark 1 están obsoletos y se redirigen a `spark-2`
`effort`	string	No	Presupuesto de razonamiento: `low`, `medium` o `high`. Todas las ejecuciones se realizan con `spark-2`, por lo que `effort` puede enviarse con o sin `model`
`urls`	array	No	Lista opcional de URLs en las que centrar la extracción
`schema`	object	No	Esquema JSON opcional para una salida estructurada
`strictConstrainToURLs`	boolean	No	Si es `true`, el agente solo visita las URLs proporcionadas en el array `urls`
`webhook`	object	No	Webhook para recibir eventos del ciclo de vida del agente (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). Consulta las cargas útiles de webhook
`maxCredits`	number	No	Número máximo de créditos que se pueden usar en esta tarea del agente. De forma predeterminada es 2,500 si no se especifica. El Dashboard admite valores de hasta 2,500; para límites superiores, configura `maxCredits` mediante la API (los valores por encima de 2,500 siempre se tratan como solicitudes de pago). Si se alcanza el límite, el trabajo falla y no se devuelve ningún dato. Las ejecuciones fallidas no se facturan: los créditos usados para el razonamiento de IA nunca se cobran en caso de fallo, cualquier crédito usado para llamadas a herramientas durante la ejecución (`scraping`, `search`, `mapping`, etc.) se reembolsa, y la respuesta informa `creditsUsed: 0`.
`exchange.onTermsRequired`	string	No	Qué hacer cuando un provider de datos de Alexandria que el agente fuera a usar requiere términos que tu equipo no ha aceptado: `skip` (predeterminado) o `ask`. Consulta Proveedores de datos que requieren términos

Agent vs Extract: Qué ha mejorado

Característica	Agent (nuevo)	Extract
URLs necesarias	No	Sí
Velocidad	Más rápida	Estándar
Costo	Más bajo	Estándar
Fiabilidad	Más alta	Estándar
Flexibilidad de las consultas	Alta	Moderada

Ejemplos de casos de uso

Investigación: “Encuentra las 5 principales startups de IA y sus montos de financiación”
Análisis de la competencia: “Compara los planes de precios entre Slack y Microsoft Teams”
Recopilación de datos: “Extrae información de contacto de sitios web de empresas”
Resumen de contenido: “Resume las últimas entradas de blog sobre web scraping”

Carga de archivos CSV en Agent Playground

El Agent Playground admite la carga de archivos CSV para el procesamiento por lotes. Tu CSV puede contener una o más columnas de datos de entrada. Por ejemplo, una sola columna con nombres de empresas, o varias columnas como nombre de la empresa, producto y URL del sitio web. Cada fila representa un elemento que el agente debe procesar. Sube tu CSV y luego agrega columnas de salida con el botón ”+” en el encabezado de la cuadrícula. Cada columna tiene su propio prompt: haz clic en el encabezado de una columna para describir qué debe encontrar el agente para ese campo (p. ej., “Nombre del CEO o fundador”, “Financiación total obtenida”). Pulsa Run y el agente procesa cada fila en paralelo y completa los resultados.

Solución de problemas con Ask

Si los trabajos de tu agente fallan o devuelven resultados inesperados, usa la API de Ask para depuración agentic. Describe el problema y obtén una respuesta verificada con parámetros de solución que puedes aplicar directamente:

curl -X POST https://api.firecrawl.dev/v2/support/ask \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "my agent returned incomplete results"
  }'

Consulta la documentación de Ask para conocer todos los detalles y ejemplos de integración.

Referencia de la API

Consulta la Agent API Reference para más detalles. ¿Tienes comentarios o necesitas ayuda? Escríbenos a help@firecrawl.com.

Precios

Firecrawl Agent usa facturación dinámica que se ajusta a la complejidad de tu solicitud de extracción de datos. Pagas según el trabajo real que realiza Agent, lo que garantiza un precio justo tanto si estás extrayendo datos simples como información estructurada compleja de múltiples fuentes.

Cómo funcionan los precios de Agent

Los precios de Agent son dinámicos y basados en créditos durante la Research Preview:

Extracciones simples (como obtener información de contacto de una sola página) suelen usar menos créditos y cuestan menos
Tareas de investigación complejas (como análisis de la competencia en múltiples dominios) usan más créditos, pero reflejan el esfuerzo total involucrado
Uso transparente te muestra exactamente cuántos créditos consumió cada solicitud
Conversión de créditos convierte automáticamente el uso de créditos del agente en créditos para una facturación sencilla

El uso de créditos varía según la complejidad de tu prompt, la cantidad de datos procesados y la estructura de la salida solicitada. Como guía aproximada, la mayoría de las ejecuciones de agentes consumen unos pocos cientos de créditos, aunque las tareas simples de una sola página pueden usar menos y las investigaciones complejas en múltiples dominios pueden usar más.

Precios de agentes en paralelo

Si estás ejecutando varios agentes en paralelo con Spark-1 Fast, el precio es mucho más predecible: 10 créditos por celda.

Primeros pasos

Todos los usuarios reciben 5 ejecuciones gratuitas al día, que pueden utilizarse tanto desde el playground como desde la API, para explorar las capacidades de Agent sin costo. El uso adicional se cobra en función del consumo de créditos y se convierte en créditos.

Gestión de costos

Agent puede resultar costoso, pero hay algunas formas de reducir el costo:

Empieza con ejecuciones gratuitas: Usa tus 5 solicitudes gratuitas diarias para entender los precios
Configura el parámetro maxCredits: Limita tu gasto estableciendo un número máximo de créditos que estás dispuesto a usar. El panel de control limita esto a 2,500 créditos; para establecer un límite más alto, usa el parámetro maxCredits directamente a través de la API (nota: los valores por encima de 2,500 siempre se facturan como solicitudes pagadas)
Optimiza los prompts: Los prompts más específicos suelen consumir menos créditos
Divide las tareas grandes en ejecuciones más pequeñas: Una sola ejecución de Agent devuelve aproximadamente 150-200 filas de datos estructurados. Para trabajos de extracción grandes, divide por categoría, región o lote de URL (3-5 URL por ejecución) y combina los resultados. Esto también mantiene cada ejecución muy por debajo del límite de maxCredits.
Supervisa tu uso: Haz seguimiento de tu consumo desde el panel de control
Define expectativas: Las investigaciones complejas en múltiples dominios consumirán más créditos que las extracciones simples de una sola página

Prueba Agent ahora en firecrawl.dev/app/agent para ver cómo escala el consumo de créditos según tus casos de uso específicos.

Los precios están sujetos a cambios a medida que pasamos de la Research Preview a la disponibilidad general. Los usuarios actuales recibirán aviso previo de cualquier actualización de precios.

¿Eres un Agent de IA que necesita una API key de Firecrawl? Consulta firecrawl.dev/agent-onboarding/SKILL.md para obtener instrucciones de incorporación automatizada.

Primeros pasos

Endpoints principales

Más

Inicios rápidos

Guías para desarrolladores

Webhooks

Casos de uso

Otros

Contribuciones

Pruébalo en el Playground

Uso de `/agent`

Respuesta

Proporcionar URLs (opcional)

Estado y finalización de trabajos

Posibles estados

Ejemplo en estado pendiente

Ejemplo completado

Listado de ejecuciones de agentes

Seguimiento de una ejecución en curso

Trazas de ejecución y snapshots

Obtención de los datos de origen del agente

Selección de modelo

Spark 2

Especificar un modelo

Proveedores de datos que requieren aceptar términos

Campos de la respuesta

Acepta y luego continúa

Parámetros

Agent vs Extract: Qué ha mejorado

Ejemplos de casos de uso

Carga de archivos CSV en Agent Playground

Solución de problemas con Ask

Referencia de la API

Precios

Cómo funcionan los precios de Agent

Precios de agentes en paralelo

Primeros pasos

Gestión de costos

Pruébalo en el Playground

​Uso de /agent

​Respuesta

​Proporcionar URLs (opcional)

​Estado y finalización de trabajos

​Posibles estados

​Ejemplo en estado pendiente

​Ejemplo completado

​Listado de ejecuciones de agentes

​Seguimiento de una ejecución en curso

​Trazas de ejecución y snapshots

​Obtención de los datos de origen del agente

​Compartir ejecuciones del agente

​Selección de modelo

​Spark 2

​Especificar un modelo

​Proveedores de datos que requieren aceptar términos

​Campos de la respuesta

​Acepta y luego continúa

​Parámetros

​Agent vs Extract: Qué ha mejorado

​Ejemplos de casos de uso

​Carga de archivos CSV en Agent Playground

​Solución de problemas con Ask

​Referencia de la API

​Precios

​Cómo funcionan los precios de Agent

​Precios de agentes en paralelo

​Primeros pasos

​Gestión de costos

Uso de `/agent`

Respuesta

Proporcionar URLs (opcional)

Estado y finalización de trabajos

Posibles estados

Ejemplo en estado pendiente

Ejemplo completado

Listado de ejecuciones de agentes

Seguimiento de una ejecución en curso

Trazas de ejecución y snapshots

Obtención de los datos de origen del agente

Compartir ejecuciones del agente

Selección de modelo

Spark 2

Especificar un modelo

Proveedores de datos que requieren aceptar términos

Campos de la respuesta

Acepta y luego continúa

Parámetros

Agent vs Extract: Qué ha mejorado

Ejemplos de casos de uso

Carga de archivos CSV en Agent Playground

Solución de problemas con Ask

Referencia de la API

Precios

Cómo funcionan los precios de Agent

Precios de agentes en paralelo

Primeros pasos

Gestión de costos