agente

Escolhendo a ferramenta certa. agente é a escolha certa quando você não sabe quais são as URLs ou precisa de navegação autônoma pela web.

Para uma única URL conhecida, o modo JSON no /scrape é mais barato e síncrono.
Comparação completa: Escolhendo o Extrator de Dados.

Firecrawl /agent é uma API mágica que pesquisa, navega e coleta dados da mais ampla variedade de sites, encontrando dados em locais de difícil acesso e descobrindo dados de maneiras que nenhuma outra API consegue. Ele realiza em poucos minutos o que levaria muitas horas para um humano — coleta de dados de ponta a ponta, sem scripts ou trabalho manual. Seja para obter um único dado ou conjuntos de dados completos em escala, o Firecrawl /agent trabalha para obter seus dados. Pense no /agent como uma pesquisa profunda por dados, onde quer que eles estejam!

Research Preview: agente está em acesso antecipado. Espere algumas imperfeições. Ele ficará significativamente melhor com o tempo.

agente aproveita tudo o que há de melhor no /extract e leva isso além:

Não requer URLs: basta descrever o que você precisa pelo parâmetro prompt. As URLs são opcionais
Busca profunda na web: pesquisa e navega de forma autônoma pelas camadas mais profundas dos sites para encontrar seus dados
Confiável e preciso: funciona com uma ampla variedade de queries e casos de uso
Mais rápido: processa múltiplas fontes em paralelo para resultados mais ágeis

Experimente no Playground

Experimente o agente no playground interativo — sem precisar de código.

Usando `/agent`

O único parâmetro obrigatório é prompt. Basta descrever quais dados deseja extrair. Para obter uma saída estruturada, forneça um schema JSON. Os SDKs oferecem suporte a Pydantic (Python) e Zod (Node) para definições de schema com segurança de tipos:

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="Nome completo do fundador")
    role: Optional[str] = Field(None, description="Cargo ou posição")
    background: Optional[str] = Field(None, description="Formação profissional")

class FoundersSchema(BaseModel):
    founders: List[Founder] = Field(description="List of founders")

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": "Histórico profissional" }
            },
            "required": ["name"]
          }
        }
      },
      "required": ["founders"]
    }
  }'

Resposta

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
}

Fornecendo URLs (Opcional)

Opcionalmente, você pode fornecer URLs para que o agente se concentre em 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="Compare os recursos e informações de preços dessas 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"
  }'

Status e conclusão de jobs

Jobs de agente são executados de forma assíncrona. Ao enviar um job, você recebe um Job ID que pode usar para verificar o status:

Método padrão: agent() aguarda e retorna os resultados finais
Iniciar e depois consultar: use start_agent (Python) ou startAgent (Node) para obter um Job ID imediatamente e depois verificar o status com get_agent_status / getAgentStatus
Notificação em vez de consulta: passe um webhook ao iniciar o job para receber eventos do agente conforme a execução avança e é concluída

Os resultados do job ficam disponíveis via API por 24 horas após a conclusão. Após esse período, você ainda pode ver o histórico do seu agente e os resultados nos logs de atividade.

from firecrawl import Firecrawl

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

# Iniciar uma tarefa de 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" });

// Iniciar uma tarefa do agente
const started = await firecrawl.startAgent({
  prompt: "Find the founders of Firecrawl"
});

// Verificar o status
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"

Estados possíveis

Status	Descrição
`processing`	O agente ainda está trabalhando na sua requisição
`completed`	Extração concluída com sucesso
`failed`	Ocorreu um erro durante a extração ou o job foi cancelado (jobs cancelados informam `failed` com uma mensagem de erro de cancelamento)

O cancelamento é cooperativo. Quando você chama o endpoint de cancelamento, a solicitação é registrada imediatamente, mas qualquer etapa já em andamento (uma etapa de raciocínio do LLM, uma chamada de ferramenta ou uma ação no navegador) continua até um ponto de interrupção seguro antes de o job parar. Os créditos podem continuar sendo consumidos durante esse breve intervalo, então o creditsUsed final pode ser maior do que o valor informado no momento em que você clicou em cancelar. Um job cancelado informa o status failed quando consultado e emite um evento de webhook agent.cancelled.

Exemplo pendente

JSON

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

Exemplo concluído

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
}

Listando execuções de agentes

GET /agent lista todas as execuções de agentes da sua equipe, das mais recentes às mais antigas — incluindo as iniciadas no playground ou pela API. Cada entrada inclui o ID da execução, a hora de criação, o status, uma breve indicação do destino e as opções com que ela foi iniciada. Os resultados são paginados em páginas fixas de 20 execuções. Quando houver mais páginas, a resposta incluirá uma URL next; use o timestamp before dela para buscar a próxima página. Os métodos do SDK não paginam automaticamente, para que você mantenha o controle de até onde voltar.

from firecrawl import Firecrawl

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

# Liste suas execuções de agente mais recentes
page = app.list_agents()

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

# Busque a próxima página usando o 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 suas execuções de agente mais recentes
const page = await firecrawl.listAgents();

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

// Busca a próxima página usando o 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"

# Busca a próxima página (timestamp unix em ms obtido da URL `next` da página anterior)
curl -X GET "https://api.firecrawl.dev/v2/agent?before=1756600000000" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

Acompanhando uma execução em andamento

O agente não mantém uma conexão de streaming aberta. Não há stream de eventos enviados pelo servidor nem websocket, então acompanhe uma execução consultando seu rastro ou recebendo webhooks.

Superfície	O que você recebe	Ideal para
Consulta do rastro	Detalhes completos: todos os eventos emitidos pela execução até o momento, incluindo chamadas de ferramenta, resumos de raciocínio, fases de progresso e mudanças nos artefatos	Criar sua própria UI de progresso ou depurar o que uma execução realmente fez
Webhooks	Entrega por push, em nível mais amplo: os cinco eventos do ciclo de vida do agente (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). Consulte eventos de webhook	Reagir ao término de uma execução sem manter um loop de consulta aberto
Visualização em tempo real	Uma visualização do navegador do agente que pode ser acompanhada por humanos. Solicite o rastro com `?liveView=true`, e cada entrada em `activeBrowserSessions` inclui uma `liveViewUrl`	Acompanhar uma execução navegando em tempo real

Ao ordenar eventos de rastro manualmente, primeiro agrupe-os por agent.id: producerSequence é monotônica para cada agente emissor, portanto uma única ordenação global intercala incorretamente os eventos de um orquestrador com os de seus subagentes. Os eventos também podem chegar por um breve período após o evento terminal run.finished; portanto, continue consultando durante uma curta janela adicional antes de renderizar o 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 é monotônico por agente emissor, portanto agrupe antes.
    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:
        # Janela final: eventos ainda podem chegar por um instante após o término da execução.
        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 é monotônico por agente emissor, por isso agrupe primeiro.
  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 {
    // Janela final: eventos ainda podem chegar por um instante depois que a execução termina.
    if (++quietPolls === 3) break;
  }

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

# Exibe apenas os eventos que você ainda não viu e continua consultando por uma
# breve janela final após o término da execução.
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

Rastros de execução e snapshots

Cada execução registra um rastro de execução canônico — uma sequência ordenada de eventos que abrange chamadas de ferramenta, resumos de raciocínio, atualizações de progresso, sessões de navegador e alterações nos artefatos de resultado. Use-o para depurar uma execução ou criar uma UI de progresso em tempo real:

from firecrawl import Firecrawl

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

# Trace de execução de uma execução: eventos ordenados (chamadas de ferramenta, raciocínio, artefatos)
trace = app.get_agent_trace("JOB_ID")

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

# Inclui as sessões de navegador ativas no momento, enquanto a execução está em andamento
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" });

// Trace de execução de uma run: eventos ordenados (chamadas de ferramenta, raciocínio, artefatos)
const trace = await firecrawl.getAgentTrace("JOB_ID");

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

// Inclui as sessões de navegador ativas no momento, enquanto a run está em execução
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"

# Inclui as sessões de navegador ativas enquanto a execução está em andamento
curl "https://api.firecrawl.dev/v2/agent/JOB_ID/trace?liveView=true" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

Os eventos de rastro artifact.updated fazem referência ao resultado de trabalho do agente por meio de snapshotId. Obtenha o conteúdo completo de um snapshot usando o endpoint de snapshots:

from firecrawl import Firecrawl

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

# Eventos de trace artifact.updated referenciam o conteúdo do snapshot pelo 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" });

// os eventos de trace artifact.updated referenciam o conteúdo do snapshot pelo 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"

Rastros e snapshots são registrados em execuções do Spark 2, ou seja, em todas as novas execuções; jobs iniciados em modelos Spark 1 antes de serem descontinuados não os incluem. Consulte as referências da API de rastro e snapshot para conferir o esquema completo de eventos e o catálogo de erros do agente para as falhas retornadas por esses endpoints.

Obtendo os dados de origem do agente

Uma execução grava seus resultados parciais em artefatos à medida que avança, e você pode recuperá-los depois de obter o rastro da execução. Cada evento artifact.updated descreve uma alteração em um artefato: artifact.kind pode ser json, markdown, html, screenshot ou text; artifact.path indica onde a execução o salvou; e artifact.snapshotId é o identificador que você usa para obter seu conteúdo em GET /agent/{jobId}/snapshots/{snapshotId}. O endpoint de snapshots retorna esse conteúdo em um campo snapshot como uma string: para artefatos json, essa string é codificada em JSON e precisa ser decodificada, enquanto, para artefatos markdown, html e text, ela é o próprio conteúdo. Para obter o conteúdo de página produzido por uma execução, busque o rastro, filtre os eventos artifact.updated pelo kind desejado e, em seguida, busque 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)

    # snapshots de markdown, html e text são o próprio conteúdo.
    # snapshots de json vêm codificados em JSON, portanto precisam ser decodificados.
    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);

  // snapshots de markdown, html e texto já são o próprio conteúdo.
  // snapshots json vêm codificados em JSON, então precisam ser decodificados.
  const content = kind === "json" ? JSON.parse(snapshot.snapshot) : snapshot.snapshot;

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

# Busca todos os artifacts markdown, html ou json gerados pela execução.
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")

    # snapshots markdown e html são o próprio conteúdo; json vem codificado em JSON.
    if [ "$kind" = "json" ]; then
      printf '%s' "$body" | jq -r '.snapshot | fromjson'
    else
      printf '%s' "$body" | jq -r '.snapshot'
    fi
  done

Duas coisas importantes antes de usar isso como base:

Os artefatos são o resultado da execução, não um arquivo de cada página. O que uma execução grava em um artefato depende de como ela processa seu prompt. Portanto, trate o conjunto de artefatos como o que aquela execução específica produziu, e não como um registro garantido de todas as páginas que ela abriu.
Os resultados das ferramentas contêm o restante. Cada evento tool_call.finished inclui um campo result com o que a ferramenta retornou. É nele que aparece o conteúdo que nunca se tornou um artefato.

Você pode compartilhar execuções de agentes diretamente no Agent Playground. Os links compartilhados são públicos — qualquer pessoa com o link pode ver a saída e a atividade da execução — e você pode revogar o acesso a qualquer momento para desativar o link. As páginas compartilhadas não são indexadas por mecanismos de busca.

Seleção de modelo

O Firecrawl Agent é executado no Spark 2 — mais barato e mais rápido que os modelos Spark 1 anteriores, com precisão comparável. Ele é o modelo padrão: todas as execuções usam spark-2, independentemente de você definir o parâmetro model.

Os modelos Spark 1 estão descontinuados. Os nomes dos modelos Spark 1 continuam aceitos por compatibilidade retroativa, mas as solicitações que os utilizam são direcionadas para spark-2.

Spark 2

spark-2 abrange toda a gama de tarefas que antes exigiam escolher entre Mini e Pro, eliminando a necessidade de abrir mão da precisão para reduzir custos. Destaques:

Menor custo por execução
Tempo de execução mais rápido
Precisão comparável ao antigo carro-chefe Spark 1
O único modelo com um orçamento de raciocínio: passe effort (low, medium ou high) para controlar o quanto ele raciocina

Especificando um modelo

O parâmetro model é opcional — todas as solicitações usam spark-2:

from firecrawl import Firecrawl

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

# O Spark 2 é o padrão — toda execução roda nele
result = app.agent(
    prompt="Find the pricing of Firecrawl",
    model="spark-2"
)

# Descontinuado: os nomes de modelo do Spark 1 ainda são aceitos, mas são redirecionados para "spark-2".

print(result.data)

import { Firecrawl } from 'firecrawl';

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

// Spark 2 é o padrão — toda execução usa esse modelo
const result = await firecrawl.agent({
  prompt: "Find the pricing of Firecrawl",
  model: "spark-2"
});

// Descontinuado: os nomes de modelo do Spark 1 ainda são aceitos, mas são redirecionados para "spark-2".

console.log(result.data);

# O Spark 2 é o padrão — toda execução roda nele
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"
  }'

# Descontinuado: os nomes de modelo do Spark 1 ainda são aceitos, mas são direcionados para "spark-2".

Providers de dados que exigem aceite de termos

O Agent pode chamar providers de dados do Alexandria durante uma execução, mas apenas aqueles cujos termos de dados sua equipe já aceitou. Um provider cujos termos você não aceitou nunca é chamado, independentemente do valor de exchange.onTermsRequired. A execução continua com os providers que pode usar, e a resposta de status informa o que foi ignorado. Não existe modo de aceite automático. Aceitar os termos de um provider sempre exige que uma pessoa concorde com eles, seja no painel ou por meio de uma chamada terms/accept feita pela sua aplicação depois que o usuário tiver concordado explicitamente. Se você criar um agente com base no Firecrawl, ele deve pedir a confirmação do usuário antes de chamar terms/accept. Uma solicitação de dados não equivale a consentimento com os termos de um provider.

`onTermsRequired`	O que acontece
`skip` (padrão)	A execução responde apenas com providers aceitos e nunca fica bloqueada. `exchange.skippedProviders` lista os providers restritos que teriam ajudado.
`ask`	Igual a `skip`. Além disso, a execução termina com `exchange.requiresAction` e um `pendingApproval` com `kind: "terms"`, para que você possa consultar o usuário, aceitar os termos e continuar a thread.

Se você omitir onTermsRequired em um turno seguinte de uma thread, o turno usará o valor do turno anterior. Se um turno terminar em uma aprovação de chamada paga (requireApproval), ele não inclui oferta de termos.

Campos da resposta

Estes campos ficam no objeto exchange de GET /v2/agent/{id}:

skippedProviders (qualquer modo): uma entrada para cada provider restrito que teria ajudado, com provider, name, capability, adds (o que ele teria acrescentado), reason: "terms_required", version (a versão dos termos) e termsUrl (onde aceitar os termos no painel).
requiresAction (somente ask): type: "accept_terms", um approvalId e uma lista providers. O approvalId está sempre presente. Ele é o id da aprovação pendente de terms que você responde ao dar continuidade à thread. Cada provider traz as chamadas exatas de show (terms/show) e accept (terms/accept) que devem ser feitas. O digest de cada provider (e accept.options.digest) está sempre presente e pode ser null, o que indica que o catálogo não publicou nenhum. Nesse caso, execute terms/show primeiro e envie o digest retornado.

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

Aceite e continue

No modo ask:

Mostre os termos ao usuário. Execute a chamada show do provider via /v2/scrape com alexandria.
Somente se o usuário concordar explicitamente, execute a chamada accept do provider da mesma forma. Se accept.options.digest for null, use o digest retornado por 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 }
    }
  }'

Continue a mesma thread com exchange.approve. A oferta é aceita por completo, e callIds e always são ignorados nela. O próximo turno usa esses providers para preencher a lacuna indicada na resposta anterior, sem precisar executar tudo de novo.

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 prosseguir sem o provider, continue com exchange.decline: { "approvalId": "..." }. Isso recusa a oferta inteira, e os providers incluídos nela não serão oferecidos novamente no restante da thread. No modo skip, não há aprovação pendente a ser respondida. Depois que os termos forem aceitos, inicie uma nova execução (ou um novo turno da thread) e o provider ficará disponível.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`prompt`	string	Sim	Descrição em linguagem natural dos dados que você quer extrair (máx. 10.000 caracteres)
`model`	string	Não	O padrão é `spark-2`, modelo usado em todas as execuções. Os modelos Spark 1 estão descontinuados e são direcionados para `spark-2`
`effort`	string	Não	Orçamento de raciocínio: `low`, `medium` ou `high`. Todas as execuções usam `spark-2`, portanto `effort` pode ser enviado com ou sem `model`
`urls`	array	Não	Lista opcional de URLs para direcionar a extração
`schema`	object	Não	schema JSON opcional para resultado estruturado
`strictConstrainToURLs`	boolean	Não	Se `true`, o agente visita apenas as URLs fornecidas no array `urls`
`webhook`	object	Não	Webhook para receber eventos do ciclo de vida do agente (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). Consulte os payloads de webhook
`maxCredits`	number	Não	Número máximo de créditos a serem usados nesta tarefa de agente. O padrão é 2.500 se não for definido. O painel suporta valores de até 2.500; para limites mais altos, defina `maxCredits` via API (valores acima de 2.500 são sempre tratados como requisições pagas). Se o limite for atingido, o job falha e nenhum dado é retornado. Execuções com falha não são cobradas: créditos usados para raciocínio de IA nunca são cobrados em caso de falha, quaisquer créditos usados para chamadas de ferramentas durante a execução (scraping, busca, mapeamento etc.) são reembolsados, e a resposta informa `creditsUsed: 0`.
`exchange.onTermsRequired`	string	Não	O que fazer quando um provider de dados da Alexandria que o agente usaria exige termos que sua equipe ainda não aceitou: `skip` (padrão) ou `ask`. Consulte Providers de dados que exigem termos

Agent vs Extract: O que melhorou

Recurso	Agent (Novo)	Extract
URLs obrigatórias	Não	Sim
Velocidade	Mais rápida	Padrão
Custo	Mais baixo	Padrão
Confiabilidade	Maior	Padrão
Flexibilidade das consultas	Alta	Moderada

Exemplos de Casos de Uso

Pesquisa: “Encontre as 5 principais startups de IA e seus valores de financiamento”
Análise de concorrência: “Compare os planos de preços do Slack e do Microsoft Teams”
Coleta de dados: “Extraia informações de contato de sites de empresas”
Resumo de conteúdo: “Resuma as postagens de blog mais recentes sobre web scraping”

Upload de CSV no Agent Playground

O Agent Playground oferece suporte a upload de CSV para processamento em lote. Seu CSV pode conter uma ou mais colunas de dados de entrada. Por exemplo, uma única coluna com nomes de empresas, ou múltiplas colunas como nome da empresa, produto e URL do site. Cada linha representa um item para o agente processar. Envie seu arquivo CSV e, em seguida, adicione colunas de saída usando o botão ”+” no cabeçalho da grade. Cada coluna tem seu próprio prompt — clique no cabeçalho de uma coluna para descrever o que o agente deve encontrar para esse campo (por exemplo, “Nome do CEO ou fundador”, “Total captado em investimentos”). Clique em Run, e o agente processa cada linha em paralelo, preenchendo os resultados.

Solução de problemas com Ask

Se os jobs do seu agente falharem ou retornarem resultados inesperados, use a API Ask para depuração de agentes. Descreva o problema e obtenha uma resposta verificada com parâmetros de correção que você pode aplicar diretamente:

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

Consulte a documentação do Ask para mais detalhes e exemplos de integração.

Referência da API

Confira a referência da Agent API para mais detalhes. Tem alguma sugestão ou precisa de ajuda? Envie um e-mail para help@firecrawl.com.

Preços

O Firecrawl Agent usa cobrança dinâmica, que acompanha a complexidade da sua solicitação de extração de dados. Você paga com base no trabalho efetivamente realizado pelo Agent, garantindo preços justos tanto ao extrair dados simples quanto informações estruturadas complexas de múltiplas fontes.

Como funciona o preço do Agent

Os preços do Agent são dinâmicos e baseados em créditos durante o Research Preview:

Extrações simples (como informações de contato de uma única página) normalmente consomem menos créditos e custam menos
Tarefas de pesquisa complexas (como análise de concorrência em vários domínios) consomem mais créditos, mas refletem o esforço total envolvido
Uso transparente mostra exatamente quantos créditos cada requisição consumiu
Conversão de créditos converte automaticamente o uso de créditos do Agent em créditos para facilitar a cobrança

O uso de créditos varia de acordo com a complexidade do seu prompt, a quantidade de dados processados e a estrutura do resultado solicitado. Como orientação geral, a maioria das execuções do Agent consome algumas centenas de créditos, embora tarefas simples em uma única página possam usar menos e pesquisas complexas em vários domínios possam usar mais.

Preços para Agentes em Paralelo

Se você estiver executando vários agentes em paralelo com o Spark-1 Fast, o custo se torna muito mais previsível: 10 créditos por célula.

Começando

Todos os usuários recebem 5 execuções gratuitas por dia, que podem ser usadas tanto no playground quanto na API, para explorar os recursos do Agent sem nenhum custo. O uso adicional é cobrado com base no consumo de créditos e convertido em créditos.

Gerenciando custos

agente pode ser caro, mas há algumas maneiras de reduzir o custo:

Comece com execuções gratuitas: Use suas 5 requisições gratuitas diárias para entender os preços
Defina o parâmetro maxCredits: Limite seus gastos definindo um número máximo de créditos que você está disposto a usar. O painel limita isso a 2.500 créditos; para definir um limite maior, use o parâmetro maxCredits diretamente via API (observação: valores acima de 2.500 são sempre cobrados como requisições pagas)
Otimize os prompts: Prompts mais específicos geralmente usam menos créditos
Divida tarefas grandes em execuções menores: Uma única execução do agente retorna aproximadamente 150-200 linhas de dados estruturados. Para jobs grandes de extração, divida por categoria, região ou lote de URLs (3-5 URLs por execução) e mescle os resultados. Isso também mantém cada execução bem abaixo do limite de maxCredits.
Monitore o uso: Acompanhe seu consumo pelo painel
Ajuste expectativas: Pesquisas complexas em múltiplos domínios vão consumir mais créditos do que extrações simples de uma única página

Teste o agente agora em firecrawl.dev/app/agent para ver como o uso de créditos escala com seus casos de uso específicos.

Os preços estão sujeitos a alteração à medida que avançamos de Research Preview para disponibilidade geral. Usuários atuais receberão aviso antecipado sobre quaisquer atualizações de preços.

Você é um agente de IA que precisa de uma API key da Firecrawl? Veja firecrawl.dev/agent-onboarding/SKILL.md para instruções de onboarding automatizado.

Primeiros passos

Endpoints principais

Mais

Guias de início rápido

Guias para desenvolvedores

Webhooks

Casos de uso

Outros

Como contribuir

Experimente no Playground

Usando `/agent`

Resposta

Fornecendo URLs (Opcional)

Status e conclusão de jobs

Estados possíveis

Exemplo pendente

Exemplo concluído

Listando execuções de agentes

Acompanhando uma execução em andamento

Rastros de execução e snapshots

Obtendo os dados de origem do agente

Seleção de modelo

Spark 2

Especificando um modelo

Providers de dados que exigem aceite de termos

Campos da resposta

Aceite e continue

Parâmetros

Agent vs Extract: O que melhorou

Exemplos de Casos de Uso

Upload de CSV no Agent Playground

Solução de problemas com Ask

Referência da API

Preços

Como funciona o preço do Agent

Preços para Agentes em Paralelo

Começando

Gerenciando custos

Experimente no Playground

​Usando /agent

​Resposta

​Fornecendo URLs (Opcional)

​Status e conclusão de jobs

​Estados possíveis

​Exemplo pendente

​Exemplo concluído

​Listando execuções de agentes

​Acompanhando uma execução em andamento

​Rastros de execução e snapshots

​Obtendo os dados de origem do agente

​Compartilhar execuções de agentes

​Seleção de modelo

​Spark 2

​Especificando um modelo

​Providers de dados que exigem aceite de termos

​Campos da resposta

​Aceite e continue

​Parâmetros

​Agent vs Extract: O que melhorou

​Exemplos de Casos de Uso

​Upload de CSV no Agent Playground

​Solução de problemas com Ask

​Referência da API

​Preços

​Como funciona o preço do Agent

​Preços para Agentes em Paralelo

​Começando

​Gerenciando custos

Usando `/agent`

Resposta

Fornecendo URLs (Opcional)

Status e conclusão de jobs

Estados possíveis

Exemplo pendente

Exemplo concluído

Listando execuções de agentes

Acompanhando uma execução em andamento

Rastros de execução e snapshots

Obtendo os dados de origem do agente

Compartilhar execuções de agentes

Seleção de modelo

Spark 2

Especificando um modelo

Providers de dados que exigem aceite de termos

Campos da resposta

Aceite e continue

Parâmetros

Agent vs Extract: O que melhorou

Exemplos de Casos de Uso

Upload de CSV no Agent Playground

Solução de problemas com Ask

Referência da API

Preços

Como funciona o preço do Agent

Preços para Agentes em Paralelo

Começando

Gerenciando custos