# Agent > Recopila datos dondequiera que se encuentren en la web. import AgentPython from "/snippets/es/v2/agent/base/python.mdx"; import AgentJS from "/snippets/es/v2/agent/base/js.mdx"; import AgentCURL from "/snippets/es/v2/agent/base/curl.mdx"; import AgentOutput from "/snippets/es/v2/agent/base/output.mdx"; import AgentWithSchemaPython from "/snippets/es/v2/agent/with-schema/python.mdx"; import AgentWithSchemaJS from "/snippets/es/v2/agent/with-schema/js.mdx"; import AgentWithSchemaCURL from "/snippets/es/v2/agent/with-schema/curl.mdx"; import AgentWithSchemaOutput from "/snippets/es/v2/agent/with-schema/output.mdx"; import AgentWithURLsPython from "/snippets/es/v2/agent/with-urls/python.mdx"; import AgentWithURLsJS from "/snippets/es/v2/agent/with-urls/js.mdx"; import AgentWithURLsCURL from "/snippets/es/v2/agent/with-urls/curl.mdx"; import AgentStatusPython from "/snippets/es/v2/agent/status/python.mdx"; import AgentStatusJS from "/snippets/es/v2/agent/status/js.mdx"; import AgentStatusCURL from "/snippets/es/v2/agent/status/curl.mdx"; import AgentListPython from "/snippets/es/v2/agent/list/python.mdx"; import AgentListJS from "/snippets/es/v2/agent/list/js.mdx"; import AgentListCURL from "/snippets/es/v2/agent/list/curl.mdx"; import AgentStatusPending from "/snippets/es/v2/agent/status/pending.mdx"; import AgentStatusCompleted from "/snippets/es/v2/agent/status/completed.mdx"; import AgentWithModelPython from "/snippets/es/v2/agent/with-model/python.mdx"; import AgentWithModelJS from "/snippets/es/v2/agent/with-model/js.mdx"; import AgentWithModelCURL from "/snippets/es/v2/agent/with-model/curl.mdx"; import AgentTracePython from "/snippets/es/v2/agent/trace/python.mdx"; import AgentTraceJS from "/snippets/es/v2/agent/trace/js.mdx"; import AgentTraceCURL from "/snippets/es/v2/agent/trace/curl.mdx"; import AgentSnapshotPython from "/snippets/es/v2/agent/snapshot/python.mdx"; import AgentSnapshotJS from "/snippets/es/v2/agent/snapshot/js.mdx"; import AgentSnapshotCURL from "/snippets/es/v2/agent/snapshot/curl.mdx"; import AgentTracePollPython from "/snippets/es/v2/agent/trace/poll/python.mdx"; import AgentTracePollJS from "/snippets/es/v2/agent/trace/poll/js.mdx"; import AgentTracePollCURL from "/snippets/es/v2/agent/trace/poll/curl.mdx"; import AgentArtifactsPython from "/snippets/es/v2/agent/artifacts/python.mdx"; import AgentArtifactsJS from "/snippets/es/v2/agent/artifacts/js.mdx"; import AgentArtifactsCURL from "/snippets/es/v2/agent/artifacts/curl.mdx"; import PlaygroundCTA from "/snippets/es/shared/playground-cta-agent.mdx"; import ChooseDataExtractor from "/snippets/es/shared/choose-data-extractor/from-agent.mdx"; import AgentFeedbackCTA from "/snippets/es/agent-feedback-cta.mdx"; **Elegir la herramienta adecuada.** Agent es la opción correcta cuando **no conoces las URL** o necesitas navegación autónoma por la web. Firecrawl `/agent` es una API mágica que busca, navega y recopila datos desde la gama más amplia de sitios web, encontrando datos en lugares de difícil acceso y descubriéndolos de formas que ninguna otra API puede. Consigue en pocos minutos lo que a una persona le llevaría muchas horas: recopilación de datos de extremo a extremo, sin necesidad de scripts ni trabajo manual. Tanto si necesitas un solo dato como conjuntos de datos completos a escala, Firecrawl `/agent` trabaja para obtener tus datos. **Piensa en `/agent` como una investigación profunda de datos, ¡estén donde estén!** **Research Preview**: Agent está en acceso anticipado. Es de esperar que tenga algunos detalles por pulir. Mejorará significativamente con el tiempo. Agent se basa en todo lo bueno de `/extract` y lo lleva más allá: * **No se requieren URL**: Describe lo que necesitas mediante el parámetro `prompt`. Las URL son opcionales * **Búsqueda profunda en la web**: Busca y navega de forma autónoma, explorando en profundidad los sitios para encontrar tus datos * **Fiable y preciso**: Funciona con una amplia variedad de consultas y casos de uso * **Más rápido**: Procesa múltiples fuentes en paralelo para obtener resultados más rápidos
## Uso de `/agent`
El único parámetro obligatorio es `prompt`. Describe simplemente qué datos quieres extraer. Para obtener salida estructurada, proporciona un esquema JSON. Los SDK son compatibles con Pydantic (Python) y Zod (Node) para definiciones de esquemas con tipado seguro:
### Respuesta
## Proporcionar URLs (opcional)
Puedes proporcionar URLs opcionalmente para centrar al agente en páginas específicas:
## Estado y finalización de trabajos
Los trabajos de agente se ejecutan de forma asíncrona. Cuando envíes un trabajo, recibirás un ID de trabajo que podrás usar para comprobar su estado: * **Método predeterminado**: `agent()` espera y devuelve los resultados finales * **Iniciar y luego consultar**: Usa `start_agent` (Python) o `startAgent` (Node) para obtener un ID de trabajo de inmediato y luego consulta su estado con `get_agent_status` / `getAgentStatus` * **Push en lugar de consultar**: Pasa un `webhook` al iniciar el trabajo para recibir [eventos de agente](/es/webhooks/events#agent-events) a medida que la ejecución avanza y finaliza Los resultados de los trabajos estarán disponibles a través de la API durante 24 horas después de su finalización. Pasado este período, aún puedes ver el historial y los resultados de tu agente en los [registros de actividad](https://www.firecrawl.dev/app/logs).
### Posibles estados
| Estado | Descripción | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `processing` | El agente todavía está trabajando en tu solicitud | | `completed` | La extracción finalizó correctamente | | `failed` | Se produjo un error durante la extracción, o el trabajo fue cancelado (los trabajos cancelados informan `failed` con un mensaje de error de cancelación) | **La cancelación es cooperativa.** Cuando llamas al endpoint de cancelación, la solicitud se registra de inmediato, pero cualquier paso que ya esté en curso (un paso de razonamiento del LLM, una llamada a una herramienta o una acción del navegador) se ejecuta hasta completarse correctamente antes de que el trabajo se detenga. Los créditos pueden seguir acumulándose durante ese breve intervalo, por lo que el valor final de `creditsUsed` puede ser mayor que el valor informado en el momento en que hiciste clic en cancelar. Un trabajo cancelado informa el estado `failed` al consultarse y emite un evento de webhook `agent.cancelled`.
#### Ejemplo en estado pendiente
#### Ejemplo completado
## Listado de ejecuciones de agentes
`GET /agent` lista todas las ejecuciones de agentes de tu equipo, empezando por las más recientes, incluidas las iniciadas desde el playground o la API. Cada entrada incluye el ID de la ejecución, la hora de creación, el estado, una breve referencia al objetivo y las opciones con las que se inició. Los resultados se dividen en páginas fijas de 20 ejecuciones. Cuando hay más páginas, la respuesta incluye una URL `next`; pasa su marca de tiempo `before` para obtener la página siguiente. Los métodos del SDK no paginan automáticamente, por lo que tú decides hasta dónde retroceder.
## Seguimiento de una ejecución en curso
Agent no mantiene abierta una conexión de streaming. No hay flujo de eventos enviados por el servidor ni websocket, por lo que puedes seguir una ejecución sondeando su traza o recibiendo webhooks. | Superficie | Lo que obtienes | Ideal para | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | Sondeo de trazas | Todos los detalles: cada evento que la ejecución ha emitido hasta el momento, incluidas las llamadas a herramientas, los resúmenes de razonamiento, las fases de progreso y los cambios en los artefactos | Crear tu propia interfaz de usuario de progreso o depurar lo que realmente hizo una ejecución | | Webhooks | Entrega mediante push, de granularidad amplia: los cinco eventos del ciclo de vida del agente (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). Consulta [eventos de webhook](/es/webhooks/events) | Reaccionar cuando finalice una ejecución sin mantener abierto un bucle de sondeo | | Vista en vivo | Una vista del navegador del agente que una persona puede observar. Solicita la traza con `?liveView=true` y cada entrada de `activeBrowserSessions` incluye una `liveViewUrl` | Observar cómo navega una ejecución en tiempo real | Si ordenas los eventos de traza por tu cuenta, agrúpalos primero por `agent.id`: `producerSequence` es monótona para cada agente emisor, por lo que una única ordenación global intercala incorrectamente los eventos de un orquestador con los de sus subagentes. Los eventos también pueden llegar brevemente después del evento terminal `run.finished`, así que continúa sondeando durante un breve periodo adicional antes de mostrar el estado final.
## Trazas de ejecución y snapshots
Cada ejecución registra una traza de ejecución canónica: una secuencia ordenada de eventos que incluye llamadas a herramientas, resúmenes de razonamiento, actualizaciones de progreso, sesiones de navegador y cambios en los artefactos de salida. Consúltala para depurar una ejecución o crear una interfaz de usuario de progreso en tiempo real: Los eventos de traza `artifact.updated` hacen referencia a la salida de trabajo del agente mediante `snapshotId`. Obtén el contenido completo de un snapshot mediante el endpoint de snapshots: Las trazas y los snapshots se registran en las ejecuciones de Spark 2, es decir, en todas las ejecuciones nuevas; los trabajos iniciados en modelos Spark 1 antes de su retirada no los incluyen. Consulta las referencias de la API de [traza](/es/api-reference/endpoint/agent-trace) y [snapshot](/es/api-reference/endpoint/agent-snapshot) para ver el esquema completo de eventos, y el catálogo de [errores de Agent](/es/api-reference/errors#agent) para conocer los fallos que devuelven estos endpoints.
## Obtención de los datos de origen del agente
Durante su ejecución, un agente va escribiendo su salida de trabajo en artefactos, que puedes recuperar cuando tengas la traza de la ejecución. Cada evento `artifact.updated` describe un cambio en un artefacto: `artifact.kind` puede ser `json`, `markdown`, `html`, `screenshot` o `text`; `artifact.path` indica dónde lo guardó la ejecución, y `artifact.snapshotId` es el identificador que debes usar para obtener su contenido mediante `GET /agent/{jobId}/snapshots/{snapshotId}`. El endpoint de snapshots devuelve ese contenido en un campo `snapshot` como una cadena: en los artefactos `json`, esa cadena está codificada en JSON y debe decodificarse; en los artefactos `markdown`, `html` y `text`, es el contenido directamente. Para obtener el contenido de página que produjo una ejecución, recupera la traza, conserva los eventos `artifact.updated` cuyo `kind` te interese y, después, obtén cada snapshot: Conviene tener en cuenta dos aspectos antes de desarrollar sobre esta base: * **Los artefactos son la salida de la ejecución, no un archivo de cada página.** Lo que una ejecución escribe en un artefacto depende de cómo resuelva tu prompt, así que considera el conjunto de artefactos como lo que produjo esa ejecución concreta, no como un registro garantizado de todas las páginas que abrió. * **Los resultados de las herramientas contienen el resto.** Cada evento `tool_call.finished` incluye un campo `result` con lo que devolvió la herramienta, donde aparece el contenido que nunca llegó a convertirse en un artefacto.
## Compartir ejecuciones del agente
Puedes compartir ejecuciones del agente directamente desde el Agent Playground. Los enlaces compartidos son públicos: cualquier persona que tenga el enlace puede ver la salida y la actividad de la ejecución, y puedes revocar el acceso en cualquier momento para desactivar el enlace. Los motores de búsqueda no indexan las páginas compartidas.
## Selección de modelo
Firecrawl Agent se ejecuta con **Spark 2** —más económico y rápido que los modelos anteriores de Spark 1, con una precisión comparable—. Es el modelo predeterminado: todas las ejecuciones usan `spark-2`, tanto si se establece el parámetro `model` como si no. **Los modelos Spark 1 están obsoletos.** Los nombres de modelo de Spark 1 se siguen aceptando por compatibilidad con versiones anteriores, pero las solicitudes que los usan se redirigen a `spark-2`.
### Spark 2
`spark-2` gestiona toda la gama de tareas que antes requerían elegir entre Mini y Pro, por lo que no es necesario sacrificar precisión por costo. **Aspectos destacados:** * El menor costo por ejecución * El tiempo de ejecución más rápido * Precisión comparable a la del anterior modelo insignia Spark 1 * El único modelo con un presupuesto de razonamiento: pasa `effort` (`low`, `medium` o `high`) para controlar cuánto razona
### Especificar un modelo
El parámetro `model` es opcional; todas las solicitudes usan `spark-2`:
## Parámetros
| Parámetro | Tipo | Obligatorio | Descripción | | ----------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt` | string | **Sí** | Descripción en lenguaje natural de los datos que deseas extraer (máx. 10.000 caracteres) | | `model` | string | No | De forma predeterminada usa `spark-2`, el modelo con el que se ejecutan todas las ejecuciones. Los modelos Spark 1 están obsoletos y se redirigen a `spark-2` | | `effort` | string | No | Presupuesto de razonamiento: `low`, `medium` o `high`. Todas las ejecuciones se realizan con `spark-2`, por lo que `effort` puede enviarse con o sin `model` | | `urls` | array | No | Lista opcional de URLs en las que centrar la extracción | | `schema` | object | No | Esquema JSON opcional para una salida estructurada | | `strictConstrainToURLs` | boolean | No | Si es `true`, el agente solo visita las URLs proporcionadas en el array `urls` | | `webhook` | object | No | Webhook para recibir eventos del ciclo de vida del agente (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). Consulta las [cargas útiles de webhook](/es/api-reference/endpoint/webhook-agent-started) | | `maxCredits` | number | No | Número máximo de créditos que se pueden usar en esta tarea del agente. De forma predeterminada es **2,500** si no se especifica. El panel de control admite valores de hasta **2,500**; para límites superiores, configura `maxCredits` mediante la API (los valores por encima de 2,500 siempre se tratan como solicitudes de pago). Si se alcanza el límite, el trabajo falla y **no se devuelve ningún dato**. Las ejecuciones fallidas no se facturan: los créditos usados para el razonamiento de IA nunca se cobran en caso de fallo, cualquier crédito usado para llamadas a herramientas durante la ejecución (`scraping`, `search`, `mapping`, etc.) se reembolsa, y la respuesta informa `creditsUsed: 0`. |
## Agent vs Extract: Qué ha mejorado
| Característica | Agent (nuevo) | Extract | |---------|-------------|---------| | URLs necesarias | No | Sí | | Velocidad | Más rápida | Estándar | | Costo | Más bajo | Estándar | | Fiabilidad | Más alta | Estándar | | Flexibilidad de las consultas | Alta | Moderada |
## Ejemplos de casos de uso
* **Investigación**: "Encuentra las 5 principales startups de IA y sus montos de financiación" * **Análisis de la competencia**: "Compara los planes de precios entre Slack y Microsoft Teams" * **Recopilación de datos**: "Extrae información de contacto de sitios web de empresas" * **Resumen de contenido**: "Resume las últimas entradas de blog sobre web scraping"
## Carga de archivos CSV en Agent Playground
El [Agent Playground](https://www.firecrawl.dev/app/agent) admite la carga de archivos CSV para el procesamiento por lotes. Tu CSV puede contener una o más columnas de datos de entrada. Por ejemplo, una sola columna con nombres de empresas, o varias columnas como nombre de la empresa, producto y URL del sitio web. Cada fila representa un elemento que el agente debe procesar. Sube tu CSV y luego agrega columnas de salida con el botón "+" en el encabezado de la cuadrícula. Cada columna tiene su propio prompt: haz clic en el encabezado de una columna para describir qué debe encontrar el agente para ese campo (p. ej., "Nombre del CEO o fundador", "Financiación total obtenida"). Pulsa Run y el agente procesa cada fila en paralelo y completa los resultados.
## Solución de problemas con Ask
Si los trabajos de tu agente fallan o devuelven resultados inesperados, usa la [API de Ask](/es/features/ask) para depuración agentic. Describe el problema y obtén una respuesta verificada con parámetros de solución que puedes aplicar directamente: ```bash 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" }' ``` Consulta la [documentación de Ask](/es/features/ask) para conocer todos los detalles y ejemplos de integración.
## Referencia de la API
Consulta la [Agent API Reference](/es/api-reference/endpoint/agent) para más detalles. ¿Tienes comentarios o necesitas ayuda? Escríbenos a [help@firecrawl.com](mailto:help@firecrawl.com).
## Precios
Firecrawl Agent usa **facturación dinámica** que se ajusta a la complejidad de tu solicitud de extracción de datos. Pagas según el trabajo real que realiza Agent, lo que garantiza un precio justo tanto si estás extrayendo datos simples como información estructurada compleja de múltiples fuentes.
### Cómo funcionan los precios de Agent
Los precios de Agent son **dinámicos y basados en créditos** durante la Research Preview: * **Extracciones simples** (como obtener información de contacto de una sola página) suelen usar menos créditos y cuestan menos * **Tareas de investigación complejas** (como análisis de la competencia en múltiples dominios) usan más créditos, pero reflejan el esfuerzo total involucrado * **Uso transparente** te muestra exactamente cuántos créditos consumió cada solicitud * **Conversión de créditos** convierte automáticamente el uso de créditos del agente en créditos para una facturación sencilla El uso de créditos varía según la complejidad de tu prompt, la cantidad de datos procesados y la estructura de la salida solicitada. Como guía aproximada, la mayoría de las ejecuciones de agentes consumen **unos pocos cientos de créditos**, aunque las tareas simples de una sola página pueden usar menos y las investigaciones complejas en múltiples dominios pueden usar más.
### Precios de agentes en paralelo
Si estás ejecutando varios agentes en paralelo con Spark-1 Fast, el precio es mucho más predecible: 10 créditos por celda.
### Primeros pasos
**Todos los usuarios** reciben **5 ejecuciones gratuitas al día**, que pueden utilizarse tanto desde el playground como desde la API, para explorar las capacidades de Agent sin costo. El uso adicional se cobra en función del consumo de créditos y se convierte en créditos.
### Gestión de costos
Agent puede resultar costoso, pero hay algunas formas de reducir el costo: * **Empieza con ejecuciones gratuitas**: Usa tus 5 solicitudes gratuitas diarias para entender los precios * **Configura el parámetro `maxCredits`**: Limita tu gasto estableciendo un número máximo de créditos que estás dispuesto a usar. El panel de control limita esto a 2,500 créditos; para establecer un límite más alto, usa el parámetro `maxCredits` directamente a través de la API (nota: los valores por encima de 2,500 siempre se facturan como solicitudes pagadas) * **Optimiza los prompts**: Los prompts más específicos suelen consumir menos créditos * **Divide las tareas grandes en ejecuciones más pequeñas**: Una sola ejecución de Agent devuelve aproximadamente 150-200 filas de datos estructurados. Para trabajos de extracción grandes, divide por categoría, región o lote de URL (3-5 URL por ejecución) y combina los resultados. Esto también mantiene cada ejecución muy por debajo del límite de `maxCredits`. * **Supervisa tu uso**: Haz seguimiento de tu consumo desde el panel de control * **Define expectativas**: Las investigaciones complejas en múltiples dominios consumirán más créditos que las extracciones simples de una sola página Prueba Agent ahora en [firecrawl.dev/app/agent](https://www.firecrawl.dev/app/agent) para ver cómo escala el consumo de créditos según tus casos de uso específicos. Los precios están sujetos a cambios a medida que pasamos de la Research Preview a la disponibilidad general. Los usuarios actuales recibirán aviso previo de cualquier actualización de precios. > ¿Eres un Agent de IA que necesita una API key de Firecrawl? Consulta [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para obtener instrucciones de incorporación automatizada.