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"
gem install firecrawl-sdk
Requiere Ruby 3.0 o una versión posterior.
- 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
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"]
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
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
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
get_crawl_status.
status = client.get_crawl_status(response.id)
puts "Status: #{status.status}"
puts "Progress: #{status.completed}/#{status.total}"
cancel_crawl.
result = client.cancel_crawl(response.id)
puts result
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
search.
results = client.search(
"firecrawl web scraping",
Firecrawl::Models::SearchOptions.new(limit: 10)
)
results.web&.each do |result|
puts "#{result["title"]} - #{result["url"]}"
end
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
agent.
result = client.agent(
Firecrawl::Models::AgentOptions.new(
prompt: "Find the pricing plans for Firecrawl and compare them"
)
)
puts result.data
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
concurrency = client.get_concurrency
puts "Concurrency: #{concurrency.concurrency}/#{concurrency.max_concurrency}"
credits = client.get_credit_usage
puts "Remaining credits: #{credits.remaining_credits}"
Sesión interactiva vinculada al scraping
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"]}"
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
)
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.
