> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-docs-agent-transparency-gaps.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# agente
> Reúna dados em qualquer lugar da web.
**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`](/pt-BR/features/llm-extract) é mais barato e síncrono.
* Comparação completa: [Escolhendo o Extrator de Dados](/pt-BR/developer-guides/usage-guides/choosing-the-data-extractor).
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.
Recompensa: 5.000 créditos
por feedback de qualidade sobre /agent
Para se qualificar, faça uma entrevista detalhada (com casos de uso concretos e bem pensados etc.) com nosso Assistente de Feedback do Firecrawl. Leva apenas alguns minutos, pode ser interrompida a qualquer momento e é adequada tanto para humanos quanto para agentes (basta colar o link no seu harness de agentes!). Nunca usou /agent? Sua opinião também conta.
Iniciar a entrevista
Informe seu email para se qualificar. As entrevistas são avaliadas quanto à qualidade ao fim de cada semana.
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
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:
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
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 JSON theme={null}
{
"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:
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
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](https://www.firecrawl.dev/app/logs).
```python Python theme={null}
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
```
```js Node theme={null}
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);
}
```
```bash cURL theme={null}
curl -X GET "https://api.firecrawl.dev/v2/agent/" \
-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 JSON theme={null}
{
"success": true,
"status": "processing",
"expiresAt": "2024-12-15T00:00:00.000Z"
}
```
#### Exemplo concluído
```json JSON theme={null}
{
"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
}
```
## 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:
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
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:
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
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](/pt-BR/api-reference/endpoint/agent-trace) e [snapshot](/pt-BR/api-reference/endpoint/agent-snapshot) para conferir o esquema completo de eventos.
## Compartilhar execuções de agentes
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`:
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
# 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".
```
## 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](/pt-BR/api-reference/endpoint/webhook-agent-started) |
| `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`. |
| 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](https://www.firecrawl.dev/app/agent) 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](/pt-BR/features/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:
```bash theme={null}
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](/pt-BR/features/ask) para mais detalhes e exemplos de integração.
## Referência da API
Confira a [referência da Agent API](/pt-BR/api-reference/endpoint/agent) para mais detalhes.
Tem alguma sugestão ou precisa de ajuda? Envie um e-mail para [help@firecrawl.com](mailto: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 tem um limite de resultado com base na capacidade de geração do modelo subjacente (\~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](https://www.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](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para instruções de onboarding automatizado.