# Agente (/es/api-reference/endpoint/agent)

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

> ¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver instrucciones de incorporación automatizada.

`POST /agent`

Inicia una tarea de agente para la extracción de datos mediante agentes

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "properties": {
            "auditMetadata": {
              "additionalProperties": false,
              "description": "Atribución de usuario incluida en los eventos de registro SIEM cuando SIEM Logging está habilitado para la organización.",
              "properties": {
                "username": {
                  "description": "El nombre de usuario asociado a la solicitud.",
                  "maxLength": 1024,
                  "type": "string"
                }
              },
              "required": [
                "username"
              ],
              "type": "object"
            },
            "maxCredits": {
              "description": "Créditos máximos que se pueden gastar en esta tarea del agente. El valor predeterminado es 2500 si no se especifica. Los valores superiores a 2.500 siempre se facturan como solicitudes de pago.",
              "type": "number"
            },
            "model": {
              "default": "spark-1-mini",
              "description": "El modelo que utilizará el agente para la tarea. spark-1-mini (predeterminado) es un 60 % más barato; spark-1-pro ofrece mayor precisión para tareas complejas.",
              "enum": [
                "spark-1-mini",
                "spark-1-pro"
              ],
              "type": "string"
            },
            "prompt": {
              "description": "El prompt que describe los datos que se van a extraer",
              "maxLength": 10000,
              "type": "string"
            },
            "schema": {
              "description": "Esquema JSON opcional para estructurar los datos extraídos",
              "type": "object"
            },
            "strictConstrainToURLs": {
              "description": "Si es true, el agente solo visitará las URL proporcionadas en el array urls",
              "type": "boolean"
            },
            "threatProtection": {
              "description": "Anulación por solicitud de [Protección contra amenazas](https://docs.firecrawl.dev/features/threat-protection). Los campos que proporciones reemplazan los campos correspondientes de la política de tu organización solo para esta solicitud; los campos omitidos conservan sus valores a nivel de organización. Requiere que Protección contra amenazas esté habilitada para tu equipo (función enterprise); de lo contrario, la solicitud se rechaza con un 403. Si tu organización ha deshabilitado las anulaciones por solicitud, cualquier solicitud que incluya este objeto se rechaza con un 403. Si Protección contra amenazas se aplica de forma obligatoria a tu equipo, `mode` no puede establecerse en `off`.",
              "properties": {
                "blacklist": {
                  "description": "Dominios que siempre se deben bloquear, como dominios simples (`example.com`) o patrones con comodines (`*.example.com`). Sin protocolo, ruta ni puerto.",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                },
                "blockedTlds": {
                  "description": "Dominios de nivel superior que se bloquean directamente, en minúsculas y sin el punto inicial (p. ej., `zip`).",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                },
                "failurePolicy": {
                  "description": "Qué hacer cuando no se puede acceder al clasificador: `closed` bloquea la solicitud; `open` la permite.",
                  "enum": [
                    "open",
                    "closed"
                  ],
                  "type": "string"
                },
                "mode": {
                  "description": "Modo de análisis de URL para esta solicitud. `normal` verifica las URL con Google Web Risk (+2 créditos por URL analizada).",
                  "enum": [
                    "off",
                    "normal"
                  ],
                  "type": "string"
                },
                "riskScoreThreshold": {
                  "description": "Puntuación de riesgo normalizada (0–100) a partir de la cual el veredicto de un clasificador bloquea la URL. Cuanto más bajo, más estricto.",
                  "example": 75,
                  "maximum": 100,
                  "minimum": 0,
                  "type": "integer"
                },
                "whitelist": {
                  "description": "Dominios que siempre se deben permitir, como dominios simples o patrones con comodines. Tiene prioridad sobre cualquier otra regla.",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                }
              },
              "title": "Threat Protection Override",
              "type": "object"
            },
            "urls": {
              "description": "Lista opcional de URLs a las que se limitará el agente",
              "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": "La tarea del agente se inició correctamente"
    },
    "402": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Payment required to access this resource.",
                "type": "string"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "Se requiere pago"
    },
    "429": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Rate limit exceeded.",
                "type": "string"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "Demasiadas solicitudes"
    }
  }
}
```