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!

agente 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

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:

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

Opcionalmente, você pode fornecer URLs para que o agente se concentre em páginas específicas:

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

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

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

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.

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.

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.

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:

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:

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:

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.

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.

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

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

• 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"

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.

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.

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.

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.

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

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.

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.

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.

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.