Agente

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!

Prévia de pesquisa: Agent está em acesso antecipado. Espere algumas imperfeições. Ele ficará significativamente melhor com o tempo. Compartilhe feedback →

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

Nenhuma URL necessária: Basta descrever o que você precisa via parâmetro prompt. URLs são opcionais
Pesquisa aprofundada na web: Pesquisa e navega autonomamente em profundidade em sites para encontrar seus dados
Confiável e preciso: Funciona com uma grande variedade de consultas e casos de uso
Mais rápido: Processa múltiplas fontes em paralelo para resultados mais rápidos

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-1-mini",
    maxCredits=100
)

print(result.data)

import Firecrawl from '@mendable/firecrawl-js';
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-1-mini",
  maxCredits: 100,
  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-1-mini",
    "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 '@mendable/firecrawl-js';

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

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 '@mendable/firecrawl-js';

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 solicitação
`completed`	Extração concluída com sucesso
`failed`	Ocorreu um erro durante a extração

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
}

Seleção de modelos

O Firecrawl Agent oferece dois modelos. O Spark 1 Mini é 60% mais barato e é o padrão — perfeito para a maioria dos casos de uso. Atualize para o Spark 1 Pro quando precisar de máxima precisão em tarefas complexas.

Model	Cost	Accuracy	Best For
`spark-1-mini`	60% mais barato	Padrão	A maioria das tarefas (padrão)
`spark-1-pro`	Padrão	Mais alta	Pesquisa complexa, extrações críticas

Comece com o Spark 1 Mini (padrão) — ele lida bem com a maioria das tarefas de extração com um custo 60% menor. Altere para o Pro apenas para pesquisas complexas em múltiplos domínios ou quando a precisão for crítica.

Spark 1 Mini (Padrão)

spark-1-mini é nosso modelo eficiente, ideal para tarefas simples de extração de dados. Use o Mini quando:

Extraindo dados simples (informações de contato, preços, etc.)
Trabalhando com sites bem estruturados
Custo-benefício é uma prioridade
Executando trabalhos de extração em grande escala

Spark 1 Pro

spark-1-pro é o nosso principal modelo, projetado para máxima precisão em tarefas complexas de extração. Use o Pro quando:

Realizar análises competitivas complexas
Extrair dados que exigem raciocínio profundo
A precisão for crítica para o seu caso de uso
Lidar com dados ambíguos ou difíceis de encontrar

Especificando um modelo

Informe o parâmetro model para selecionar qual modelo usar:

from firecrawl import Firecrawl

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

# Usando Spark 1 Mini (padrão - pode ser omitido)
result = app.agent(
    prompt="Find the pricing of Firecrawl",
    model="spark-1-mini"
)

# Using Spark 1 Pro for complex tasks
result = app.agent(
    prompt="Compare all enterprise features and pricing across Firecrawl, Apify, and ScrapingBee",
    model="spark-1-pro"
)

print(result.data)

import Firecrawl from '@mendable/firecrawl-js';

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

// Usando Spark 1 Mini (padrão - pode ser omitido)
const result = await firecrawl.agent({
  prompt: "Find the pricing of Firecrawl",
  model: "spark-1-mini"
});

// Usando Spark 1 Pro para tarefas complexas
const resultPro = await firecrawl.agent({
  prompt: "Compare all enterprise features and pricing across Firecrawl, Apify, and ScrapingBee",
  model: "spark-1-pro"
});

console.log(result.data);

# Using Spark 1 Mini (default)
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-1-mini"
  }'

# Usando Spark 1 Pro para tarefas complexas
curl -X POST "https://api.firecrawl.dev/v2/agent" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Compare all enterprise features and pricing across Firecrawl, Apify, and ScrapingBee",
    "model": "spark-1-pro"
  }'

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	Modelo a ser utilizado: `spark-1-mini` (padrão) ou `spark-1-pro`
`urls`	array	Não	Lista opcional de URLs para direcionar a extração
`schema`	object	Não	Esquema JSON opcional para saída estruturada
`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. Se o limite for atingido, a tarefa falha e nenhum dado é retornado, mas os créditos consumidos pelo trabalho já realizado ainda serão cobrados.

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. Envie um arquivo CSV contendo seus dados de entrada (por exemplo, nomes de empresas, URLs ou quaisquer entidades), escreva um prompt descrevendo quais dados deseja que o agente encontre para cada linha, defina seus campos de saída e execute — o agente processa cada linha em paralelo e preenche os resultados.

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

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

Comece com execuções gratuitas: Use suas 5 solicitaçõ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
Otimize os prompts: Prompts mais específicos geralmente usam menos créditos
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 Agent 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.

Primeiros passos

Novos recursos

Recursos principais

Guias para desenvolvedores

Webhooks

Casos de uso

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

Seleção de modelos

Spark 1 Mini (Padrão)

Spark 1 Pro

Especificando um modelo

Parâmetros

Agent vs Extract: O que melhorou

Exemplos de Casos de Uso

Upload de CSV no Agent Playground

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

​Seleção de modelos

​Spark 1 Mini (Padrão)

​Spark 1 Pro

​Especificando um modelo

​Parâmetros

​Agent vs Extract: O que melhorou

​Exemplos de Casos de Uso

​Upload de CSV no Agent Playground

​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

Seleção de modelos

Spark 1 Mini (Padrão)

Spark 1 Pro

Especificando um modelo

Parâmetros

Agent vs Extract: O que melhorou

Exemplos de Casos de Uso

Upload de CSV no Agent Playground

Referência da API

Preços

Como funciona o preço do Agent

Preços para Agentes em Paralelo

Começando

Gerenciando custos