Ruby

El SDK de Ruby de Firecrawl es un wrapper de la API de Firecrawl que te permite convertir sitios web en Markdown fácilmente.

Instalación

El SDK oficial de Ruby se mantiene en el monorepo de Firecrawl, en apps/ruby-sdk.

Para instalar el SDK de Ruby de Firecrawl, añádelo a tu proyecto:

Añádelo a tu Gemfile:

gem "firecrawl-sdk", "~> 1.0"

Luego, ejecuta:

bundle install

Requiere Ruby 3.0 o una versión posterior.

Uso

Obtén una clave de API de firecrawl.dev
Configura la clave de API como una variable de entorno llamada FIRECRAWL_API_KEY, o pásala directamente con Firecrawl::Client.new(api_key: ...)

Aquí tienes un ejemplo rápido con la API actual del SDK:

require "firecrawl"

client = Firecrawl::Client.from_env

doc = client.scrape(
  "https://firecrawl.dev",
  Firecrawl::Models::ScrapeOptions.new(formats: ["markdown"])
)

job = client.crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(limit: 5)
)

puts doc.markdown
puts "Crawled pages: #{job.data&.size || 0}"

Hacer scraping de una URL

Para hacer scraping de una sola URL, usa el método scrape.

doc = client.scrape(
  "https://firecrawl.dev",
  Firecrawl::Models::ScrapeOptions.new(
    formats: ["markdown", "html"],
    only_main_content: true,
    wait_for: 5000
  )
)

puts doc.markdown
puts doc.metadata["title"]

Extracción JSON

Extrae JSON estructurado a través del endpoint scrape incluyendo el formato json junto con un prompt y un schema:

doc = client.scrape(
  "https://example.com/product",
  Firecrawl::Models::ScrapeOptions.new(
    formats: [
      {
        "type" => "json",
        "prompt" => "Extract the product name and price",
        "schema" => {
          "type" => "object",
          "properties" => {
            "name" => { "type" => "string" },
            "price" => { "type" => "number" }
          }
        }
      }
    ]
  )
)

puts doc.json

Rastreo de un sitio web

Para rastrear un sitio web y esperar a que finalice, usa crawl. Realiza sondeos automáticamente hasta que el trabajo termine.

job = client.crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(
    limit: 50,
    max_discovery_depth: 3,
    scrape_options: Firecrawl::Models::ScrapeOptions.new(
      formats: ["markdown"]
    )
  )
)

puts "Status: #{job.status}"
puts "Progress: #{job.completed}/#{job.total}"

job.data&.each do |page|
  puts page.metadata["sourceURL"]
end

Iniciar un rastreo

Inicia un trabajo sin esperar con start_crawl.

response = client.start_crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(limit: 100)
)

puts "Job ID: #{response.id}"

Consultar el estado del rastreo

Consulta el progreso del rastreo con get_crawl_status.

status = client.get_crawl_status(response.id)
puts "Status: #{status.status}"
puts "Progress: #{status.completed}/#{status.total}"

Cancelar un rastreo

Cancela un rastreo en curso con cancel_crawl.

result = client.cancel_crawl(response.id)
puts result

Mapeo de un sitio web

Descubre enlaces en un sitio web utilizando map.

data = client.map(
  "https://firecrawl.dev",
  Firecrawl::Models::MapOptions.new(
    limit: 100,
    search: "blog"
  )
)

data.links&.each do |link|
  puts "#{link["url"]} - #{link["title"]}"
end

Buscar en la Web

Busca con opciones de configuración opcionales utilizando search.

results = client.search(
  "firecrawl web scraping",
  Firecrawl::Models::SearchOptions.new(limit: 10)
)

results.web&.each do |result|
  puts "#{result["title"]} - #{result["url"]}"
end

Scraping por lotes

Realiza scraping de varias URL en paralelo con batch_scrape.

job = client.batch_scrape(
  ["https://firecrawl.dev", "https://firecrawl.dev/blog"],
  Firecrawl::Models::BatchScrapeOptions.new(
    options: Firecrawl::Models::ScrapeOptions.new(
      formats: ["markdown"]
    )
  )
)

job.data&.each do |doc|
  puts doc.markdown
end

Agente

Ejecuta un agente con IA mediante agent.

result = client.agent(
  Firecrawl::Models::AgentOptions.new(
    prompt: "Find the pricing plans for Firecrawl and compare them"
  )
)

puts result.data

Con un esquema JSON para salida estructurada:

result = client.agent(
  Firecrawl::Models::AgentOptions.new(
    prompt: "Extract pricing plan details",
    urls: ["https://firecrawl.dev"],
    schema: {
      "type" => "object",
      "properties" => {
        "plans" => {
          "type" => "array",
          "items" => {
            "type" => "object",
            "properties" => {
              "name" => { "type" => "string" },
              "price" => { "type" => "string" }
            }
          }
        }
      }
    }
  )
)

puts result.data

Uso & métricas

Consulta la concurrencia y los créditos restantes:

concurrency = client.get_concurrency
puts "Concurrency: #{concurrency.concurrency}/#{concurrency.max_concurrency}"

credits = client.get_credit_usage
puts "Remaining credits: #{credits.remaining_credits}"

Browser

El SDK de Ruby incluye utilidades para el sandbox del navegador.

Sesión interactiva vinculada al scraping

Usa un ID de trabajo de scraping para ejecutar código adicional de browser en el mismo contexto reproducido:

interact(...) ejecuta código en la sesión de browser vinculada al scraping (y la inicializa la primera vez que se usa).
stop_interactive_browser(...) detiene explícitamente la sesión interactiva cuando terminas.

scrape_job_id = "550e8400-e29b-41d4-a716-446655440000"

run = client.interact(
  scrape_job_id,
  "console.log(page.url());",
  language: "node",
  timeout: 60
)

puts run["stdout"]

deleted = client.stop_interactive_browser(scrape_job_id)
puts "Deleted: #{deleted["success"]}"

Configuración

Firecrawl::Client.new admite las siguientes opciones:

Opción	Tipo	Predeterminado	Descripción
`api_key`	`String`	variable de entorno `FIRECRAWL_API_KEY`	Tu clave de la API de Firecrawl
`api_url`	`String`	`https://api.firecrawl.dev` (o `FIRECRAWL_API_URL`)	URL base de la API
`timeout`	`Integer`	`300`	Tiempo de espera de la solicitud HTTP en segundos
`max_retries`	`Integer`	`3`	Reintentos automáticos ante fallos transitorios
`backoff_factor`	`Float`	`0.5`	Factor de backoff exponencial en segundos

client = Firecrawl::Client.new(
  api_key: "fc-your-api-key",
  api_url: "https://api.firecrawl.dev",
  timeout: 300,
  max_retries: 3,
  backoff_factor: 0.5
)

Manejo de errores

El SDK lanza excepciones dentro del módulo Firecrawl.

begin
  doc = client.scrape("https://example.com")
rescue Firecrawl::AuthenticationError => e
  puts "Auth failed: #{e.message}"
rescue Firecrawl::RateLimitError => e
  puts "Rate limited: #{e.message}"
rescue Firecrawl::JobTimeoutError => e
  puts "Job #{e.job_id} timed out after #{e.timeout_seconds}s"
rescue Firecrawl::FirecrawlError => e
  puts "Error (#{e.status_code}): #{e.message}"
end

¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta firecrawl.dev/agent-onboarding/SKILL.md para ver las instrucciones de incorporación automática.

On this page