# Agente (/pt-BR/api-reference/endpoint/agent)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1738 · updated: 2026-07-30 -->

> Você é um agente de IA que precisa de uma chave de API da Firecrawl? Veja [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para instruções automatizadas de integração.

`POST /agent`

Iniciar uma tarefa de agente para extração de dados orientada a agentes

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "properties": {
            "auditMetadata": {
              "additionalProperties": false,
              "description": "Identificação do usuário incluída nos eventos de log do SIEM quando o SIEM Logging estiver habilitado para a organização.",
              "properties": {
                "username": {
                  "description": "O nome de usuário associado à requisição.",
                  "maxLength": 1024,
                  "type": "string"
                }
              },
              "required": [
                "username"
              ],
              "type": "object"
            },
            "maxCredits": {
              "description": "Máximo de créditos a serem gastos nesta tarefa do agente. O padrão é 2500 se não for definido. Valores acima de 2.500 são sempre cobrados como requisições pagas.",
              "type": "number"
            },
            "model": {
              "default": "spark-1-mini",
              "description": "Modelo a ser usado na tarefa do agente. spark-1-mini (padrão) é 60% mais barato; spark-1-pro oferece maior precisão em tarefas complexas.",
              "enum": [
                "spark-1-mini",
                "spark-1-pro"
              ],
              "type": "string"
            },
            "prompt": {
              "description": "O prompt que descreve quais dados devem ser extraídos",
              "maxLength": 10000,
              "type": "string"
            },
            "schema": {
              "description": "Esquema JSON opcional para estruturar os dados extraídos",
              "type": "object"
            },
            "strictConstrainToURLs": {
              "description": "Se verdadeiro, o agente visitará somente as URLs fornecidas no array urls",
              "type": "boolean"
            },
            "threatProtection": {
              "description": "Substituição por solicitação da [Proteção contra ameaças](https://docs.firecrawl.dev/features/threat-protection). Os campos fornecidos substituem os campos correspondentes da política da sua organização apenas nesta solicitação; os campos omitidos mantêm os valores definidos no nível da organização. Exige que a Proteção contra ameaças esteja habilitada para sua equipe (recurso enterprise) — caso contrário, a solicitação será rejeitada com 403. Se sua organização tiver desativado substituições por solicitação, qualquer solicitação que inclua este objeto será rejeitada com 403. Se a Proteção contra ameaças for imposta à sua equipe, `mode` não poderá ser definido como `off`.",
              "properties": {
                "blacklist": {
                  "description": "Domínios a serem sempre bloqueados, como domínios simples (`example.com`) ou padrões curinga (`*.example.com`). Sem protocolo, caminho ou porta.",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                },
                "blockedTlds": {
                  "description": "Domínios de nível superior a serem bloqueados diretamente, em minúsculas e sem o ponto inicial (ex.: `zip`).",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                },
                "failurePolicy": {
                  "description": "O que fazer quando o classificador não puder ser acessado: `closed` bloqueia a solicitação, `open` a permite.",
                  "enum": [
                    "open",
                    "closed"
                  ],
                  "type": "string"
                },
                "mode": {
                  "description": "Modo de verificação de URL para esta solicitação. `normal` verifica as URLs no Google Web Risk (+2 créditos por URL verificada).",
                  "enum": [
                    "off",
                    "normal"
                  ],
                  "type": "string"
                },
                "riskScoreThreshold": {
                  "description": "Pontuação de risco normalizada (0–100) a partir da qual um veredito do classificador bloqueia a URL. Quanto menor, mais rigoroso.",
                  "example": 75,
                  "maximum": 100,
                  "minimum": 0,
                  "type": "integer"
                },
                "whitelist": {
                  "description": "Domínios a serem sempre permitidos, como domínios simples ou padrões curinga. Tem prioridade sobre todas as outras regras.",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                }
              },
              "title": "Threat Protection Override",
              "type": "object"
            },
            "urls": {
              "description": "Lista opcional de URLs às quais o agente ficará restrito",
              "items": {
                "format": "uri",
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "prompt"
          ],
          "type": "object"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "id": {
                "format": "uuid",
                "type": "string"
              },
              "success": {
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "Tarefa do agente iniciada com sucesso"
    },
    "402": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Payment required to access this resource.",
                "type": "string"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "Pagamento obrigatório"
    },
    "429": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Rate limit exceeded.",
                "type": "string"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "Muitas solicitações"
    }
  }
}
```