Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(ruby-sdk): add agent exchange options, threadId and mode (#4985)
Gergő Móricz9da7ff609c79
diff --git a/apps/ruby-sdk/README.md b/apps/ruby-sdk/README.mdindex 79398a653..7435e445d 100644--- a/apps/ruby-sdk/README.md+++ b/apps/ruby-sdk/README.md@@ -203,6 +203,17 @@ status = client.agent(urls: ["https://example.com"]))puts status.data++# Use Alexandria data providers connected in the dashboard+status = client.agent(+ Firecrawl::Models::AgentOptions.new(+ prompt: "Find the work email of the CEO of example.com",+ exchange: Firecrawl::Models::AgentExchangeOptions.new(+ enabled: true,+ toolkits: ["apollo"]+ )+ ))+puts status.exchange&.paid_calls```### Usage & Metricsdiff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rbindex ceda485a1..d1ddee372 100644--- a/apps/ruby-sdk/lib/firecrawl.rb+++ b/apps/ruby-sdk/lib/firecrawl.rb@@ -23,9 +23,12 @@ require_relative "firecrawl/models/search_data"require_relative "firecrawl/models/parse_file"require_relative "firecrawl/models/parse_options"require_relative "firecrawl/models/parse_format"+require_relative "firecrawl/models/agent_exchange_options"require_relative "firecrawl/models/agent_options"require_relative "firecrawl/models/agent_response"require_relative "firecrawl/models/agent_list_response"+require_relative "firecrawl/models/agent_exchange_summary"+require_relative "firecrawl/models/agent_pending_approval"require_relative "firecrawl/models/agent_status_response"require_relative "firecrawl/models/agent_trace_response"require_relative "firecrawl/models/agent_snapshot_response"diff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_exchange_options.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_exchange_options.rbnew file mode 100644index 000000000..9538470e5--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/agent_exchange_options.rb@@ -0,0 +1,68 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Alexandria (Exchange) options for an agent run, forwarded verbatim; the+ # server owns every default and limit. On a follow-up turn, omitting the+ # exchange options inherits the previous turn's settings.+ #+ # on_terms_required: "skip" or "ask".+ class AgentExchangeOptions+ # Answers the previous turn's pending approval. A "terms" approval is+ # accepted as a whole, so call_ids and always are ignored on it.+ class Approve+ attr_reader :approval_id, :call_ids, :always++ def initialize(approval_id:, call_ids: nil, always: nil)+ @approval_id = approval_id+ @call_ids = call_ids+ @always = always+ end++ def to_h+ {+ "approvalId" => approval_id,+ "callIds" => call_ids,+ "always" => always,+ }.compact+ end+ end++ # Refuses the previous turn's pending approval.+ class Decline+ attr_reader :approval_id++ def initialize(approval_id:)+ @approval_id = approval_id+ end++ def to_h+ { "approvalId" => approval_id }+ end+ end++ FIELDS = %i[+ enabled toolkits max_calls require_approval approve decline+ on_terms_required+ ].freeze++ attr_reader(*FIELDS)++ def initialize(**kwargs)+ FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }+ end++ def to_h+ {+ "enabled" => enabled,+ "toolkits" => toolkits,+ "maxCalls" => max_calls,+ "requireApproval" => require_approval,+ "approve" => approve&.to_h,+ "decline" => decline&.to_h,+ "onTermsRequired" => on_terms_required,+ }.compact+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_exchange_summary.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_exchange_summary.rbnew file mode 100644index 000000000..95ffd3bb9--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/agent_exchange_summary.rb@@ -0,0 +1,72 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # What an agent run did with Alexandria (Exchange). toolkits and+ # require_approval are what the run resolved to after thread inheritance.+ class AgentExchangeSummary+ # A provider that needs data terms the team has not accepted, so the run+ # did not use it.+ class SkippedProvider+ attr_reader :provider, :name, :capability, :adds, :reason, :version,+ :terms_url++ def initialize(data)+ @provider = data["provider"]+ @name = data["name"]+ @capability = data["capability"]+ @adds = data["adds"]+ @reason = data["reason"]+ @version = data["version"]+ @terms_url = data["termsUrl"]+ end+ end++ # The Exchange calls to view and accept providers' terms ("ask" mode).+ # Nothing here runs for you; only call accept after your user agrees.+ class TermsRequiredAction+ # show and accept are the raw Exchange calls ("provider",+ # "capability", "options").+ class Provider+ attr_reader :provider, :name, :capability, :adds, :version, :digest,+ :url, :show, :accept++ def initialize(data)+ @provider = data["provider"]+ @name = data["name"]+ @capability = data["capability"]+ @adds = data["adds"]+ @version = data["version"]+ @digest = data["digest"]+ @url = data["url"]+ @show = data["show"]+ @accept = data["accept"]+ end+ end++ attr_reader :type, :approval_id, :providers++ def initialize(data)+ @type = data["type"]+ @approval_id = data["approvalId"]+ @providers = data["providers"]&.map { |p| Provider.new(p) }+ end+ end++ attr_reader :enabled, :toolkits, :require_approval, :on_terms_required,+ :paid_calls, :credits_used, :skipped_providers,+ :requires_action++ def initialize(data)+ @enabled = data["enabled"]+ @toolkits = data["toolkits"]+ @require_approval = data["requireApproval"]+ @on_terms_required = data["onTermsRequired"]+ @paid_calls = data["paidCalls"]+ @credits_used = data["creditsUsed"]+ @skipped_providers = data["skippedProviders"]&.map { |p| SkippedProvider.new(p) }+ @requires_action = data["requiresAction"] && TermsRequiredAction.new(data["requiresAction"])+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_options.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_options.rbindex 65473bd5c..8600fb27f 100644--- a/apps/ruby-sdk/lib/firecrawl/models/agent_options.rb+++ b/apps/ruby-sdk/lib/firecrawl/models/agent_options.rb@@ -6,10 +6,14 @@ module Firecrawl## effort: valid values are "low", "medium", and "high"; sets the reasoning# budget for the run (every level runs spark-2).+ #+ # thread_id continues an existing thread as its next turn; omitted starts a+ # new thread. mode: "extract" or "chat".class AgentOptionsFIELDS = %i[urls prompt schema integration max_creditsstrict_constrain_to_urls model effort webhook audit_metadata+ thread_id mode exchange].freezeattr_reader(*FIELDS)@@ -34,6 +38,9 @@ module Firecrawl"effort" => effort,"webhook" => webhook.is_a?(Hash) ? webhook : webhook&.to_h,"auditMetadata" => audit_metadata&.to_h,+ "threadId" => thread_id,+ "mode" => mode,+ "exchange" => exchange&.to_h,}.compactendenddiff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_pending_approval.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_pending_approval.rbnew file mode 100644index 000000000..9f5832226--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/agent_pending_approval.rb@@ -0,0 +1,64 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # A turn that ended waiting for the caller. kind "calls" (or nil on older+ # runs) holds paid calls to allow or refuse; kind "terms" lists providers+ # whose data terms need accepting, with calls empty. Answer it on the next+ # turn of the thread with AgentExchangeOptions approve or decline.+ class AgentPendingApproval+ # input and more are the raw call arguments.+ class Call+ attr_reader :id, :provider, :capability, :input, :more,+ :credits_estimate++ def initialize(data)+ @id = data["id"]+ @provider = data["provider"]+ @capability = data["capability"]+ @input = data["input"]+ @more = data["more"]+ @credits_estimate = data["creditsEstimate"]+ end+ end++ class TermsGate+ attr_reader :provider, :name, :logo, :capability, :adds, :version,+ :digest, :url++ def initialize(data)+ @provider = data["provider"]+ @name = data["name"]+ @logo = data["logo"]+ @capability = data["capability"]+ @adds = data["adds"]+ @version = data["version"]+ @digest = data["digest"]+ @url = data["url"]+ end+ end++ class Resolution+ attr_reader :approved, :call_ids, :always, :by_run_id++ def initialize(data)+ @approved = data["approved"]+ @call_ids = data["callIds"]+ @always = data["always"]+ @by_run_id = data["byRunId"]+ end+ end++ attr_reader :id, :kind, :reason, :calls, :terms, :resolution++ def initialize(data)+ @id = data["id"]+ @kind = data["kind"]+ @reason = data["reason"]+ @calls = data["calls"]&.map { |c| Call.new(c) }+ @terms = data["terms"]&.map { |t| TermsGate.new(t) }+ @resolution = data["resolution"] && Resolution.new(data["resolution"])+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_response.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_response.rbindex a65d09b96..be1671de9 100644--- a/apps/ruby-sdk/lib/firecrawl/models/agent_response.rb+++ b/apps/ruby-sdk/lib/firecrawl/models/agent_response.rb@@ -4,12 +4,15 @@ module Firecrawlmodule Models# Response from starting an agent task.class AgentResponse- attr_reader :success, :id, :error+ attr_reader :success, :id, :error, :thread_id, :thread_turndef initialize(data)@success = data["success"]@id = data["id"]@error = data["error"]+ # Pass thread_id back in AgentOptions to continue the conversation.+ @thread_id = data["threadId"]+ @thread_turn = data["threadTurn"]enddef to_sdiff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rbindex b2eb09671..3ff0f8ab3 100644--- a/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rb+++ b/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rb@@ -4,7 +4,9 @@ module Firecrawlmodule Models# Status response for monitoring agent tasks.class AgentStatusResponse- attr_reader :status, :data, :credits_used, :expires_at, :effort+ attr_reader :status, :data, :credits_used, :expires_at, :effort,+ :thread_id, :thread_turn, :mode, :message, :pending_approval,+ :exchangedef initialize(raw)@status = raw["status"]@@ -13,6 +15,13 @@ module Firecrawl@expires_at = raw["expiresAt"]# The effort the job ran with; only present for runs that specified it.@effort = raw["effort"]+ @thread_id = raw["threadId"]+ @thread_turn = raw["threadTurn"]+ @mode = raw["mode"]+ # Chat-mode runs answer here instead of in data.+ @message = raw["message"]+ @pending_approval = raw["pendingApproval"] && AgentPendingApproval.new(raw["pendingApproval"])+ @exchange = raw["exchange"] && AgentExchangeSummary.new(raw["exchange"])enddef done?diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rbindex b24f94d6a..9e8041c26 100644--- a/apps/ruby-sdk/lib/firecrawl/version.rb+++ b/apps/ruby-sdk/lib/firecrawl/version.rb@@ -1,5 +1,5 @@# frozen_string_literal: truemodule Firecrawl- VERSION = "1.17.1"+ VERSION = "1.17.3"enddiff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rbindex d75929894..c7b1f7754 100644--- a/apps/ruby-sdk/test/firecrawl/client_test.rb+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb@@ -802,6 +802,297 @@ class ClientTest < Minitest::Testassert_equal "https://api.firecrawl.dev/v2/agent?before=1756600000000", response.nextend+ def test_start_agent_with_exchange_thread_and_mode+ thread_id = "0199bbbb-0000-7000-8000-000000000000"+ approval_id = "0199aaaa-0000-7000-8000-000000000000"+ body = nil+ stub_request(:post, "#{BASE_URL}/v2/agent")+ .with { |req| body = JSON.parse(req.body) }+ .to_return(+ status: 200,+ body: JSON.generate(success: true, id: "agent-turn-2", threadId: thread_id, threadTurn: 2),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::AgentOptions.new(+ prompt: "Go ahead",+ thread_id: thread_id,+ mode: "chat",+ exchange: Firecrawl::Models::AgentExchangeOptions.new(+ enabled: true,+ toolkits: ["apollo", "clearbit"],+ max_calls: 4,+ require_approval: true,+ approve: Firecrawl::Models::AgentExchangeOptions::Approve.new(+ approval_id: approval_id,+ call_ids: ["call-1"],+ always: false+ ),+ on_terms_required: "ask"+ )+ )+ response = @client.start_agent(options)++ assert_equal(+ {+ "prompt" => "Go ahead",+ "threadId" => thread_id,+ "mode" => "chat",+ "exchange" => {+ "enabled" => true,+ "toolkits" => ["apollo", "clearbit"],+ "maxCalls" => 4,+ "requireApproval" => true,+ "approve" => { "approvalId" => approval_id, "callIds" => ["call-1"], "always" => false },+ "onTermsRequired" => "ask",+ },+ },+ body+ )+ assert_equal "agent-turn-2", response.id+ assert_equal thread_id, response.thread_id+ assert_equal 2, response.thread_turn+ end++ def test_agent_with_exchange_decline+ approval_id = "0199aaaa-0000-7000-8000-000000000000"+ body = nil+ stub_request(:post, "#{BASE_URL}/v2/agent")+ .with { |req| body = JSON.parse(req.body) }+ .to_return(+ status: 200,+ body: JSON.generate(success: true, id: "agent-decline"),+ headers: { "Content-Type" => "application/json" }+ )+ stub_request(:get, "#{BASE_URL}/v2/agent/agent-decline")+ .to_return(+ status: 200,+ body: JSON.generate(status: "completed", mode: "chat", message: "Skipped the paid lookup."),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::AgentOptions.new(+ prompt: "No thanks",+ thread_id: "0199bbbb-0000-7000-8000-000000000000",+ mode: "chat",+ exchange: Firecrawl::Models::AgentExchangeOptions.new(+ decline: Firecrawl::Models::AgentExchangeOptions::Decline.new(approval_id: approval_id)+ )+ )+ status = @client.agent(options, poll_interval: 0, timeout: 10)++ assert_equal({ "decline" => { "approvalId" => approval_id } }, body["exchange"])+ assert_equal "chat", status.mode+ assert_equal "Skipped the paid lookup.", status.message+ end++ def test_start_agent_omits_unset_thread_and_exchange_fields+ body = nil+ stub_request(:post, "#{BASE_URL}/v2/agent")+ .with { |req| body = JSON.parse(req.body) }+ .to_return(+ status: 200,+ body: JSON.generate(success: true, id: "agent-plain"),+ headers: { "Content-Type" => "application/json" }+ )++ response = @client.start_agent(Firecrawl::Models::AgentOptions.new(prompt: "Find pricing info"))++ assert_equal({ "prompt" => "Find pricing info" }, body)+ assert_nil response.thread_id+ assert_nil response.thread_turn+ assert_equal({ "enabled" => true }, Firecrawl::Models::AgentExchangeOptions.new(enabled: true).to_h)+ assert_equal(+ { "approvalId" => "a-1" },+ Firecrawl::Models::AgentExchangeOptions::Approve.new(approval_id: "a-1").to_h+ )+ end++ def test_get_agent_status_with_exchange_and_pending_calls_approval+ approval_id = "0199aaaa-0000-7000-8000-000000000000"+ stub_request(:get, "#{BASE_URL}/v2/agent/agent-calls")+ .to_return(+ status: 200,+ body: JSON.generate(+ success: true,+ status: "completed",+ expiresAt: "2026-09-02T00:00:00.000Z",+ threadId: "0199bbbb-0000-7000-8000-000000000000",+ threadTurn: 1,+ mode: "chat",+ message: "Apollo can verify these emails for about 3 credits.",+ suggestions: [{ label: "Approve", prompt: "Go ahead" }],+ unknownField: "ignored",+ exchange: {+ enabled: true,+ toolkits: ["apollo"],+ requireApproval: true,+ onTermsRequired: "skip",+ paidCalls: 0,+ creditsUsed: nil,+ skippedProviders: [+ {+ provider: "clearbit",+ name: "Clearbit",+ capability: "company/enrich",+ adds: "company size",+ reason: "terms_required",+ version: "F-1.0.0",+ termsUrl: "https://www.firecrawl.dev/app/alexandria/clearbit",+ },+ ],+ },+ pendingApproval: {+ id: approval_id,+ kind: "calls",+ reason: "Apollo charges per lookup.",+ calls: [+ {+ id: "call-1",+ provider: "apollo",+ capability: "people/match",+ input: { domain: "example.com" },+ more: [{ domain: "example.org" }],+ creditsEstimate: 3,+ },+ ],+ resolution: {+ approved: true,+ callIds: ["call-1"],+ always: false,+ byRunId: "agent-turn-2",+ },+ }+ ),+ headers: { "Content-Type" => "application/json" }+ )++ status = @client.get_agent_status("agent-calls")++ assert_equal "0199bbbb-0000-7000-8000-000000000000", status.thread_id+ assert_equal 1, status.thread_turn+ assert_equal "chat", status.mode+ assert_equal "Apollo can verify these emails for about 3 credits.", status.message++ exchange = status.exchange+ assert_instance_of Firecrawl::Models::AgentExchangeSummary, exchange+ assert_equal true, exchange.enabled+ assert_equal ["apollo"], exchange.toolkits+ assert_equal true, exchange.require_approval+ assert_equal "skip", exchange.on_terms_required+ assert_equal 0, exchange.paid_calls+ assert_nil exchange.credits_used+ assert_nil exchange.requires_action+ skipped = exchange.skipped_providers.first+ assert_equal "clearbit", skipped.provider+ assert_equal "terms_required", skipped.reason+ assert_equal "F-1.0.0", skipped.version+ assert_equal "https://www.firecrawl.dev/app/alexandria/clearbit", skipped.terms_url++ pending = status.pending_approval+ assert_instance_of Firecrawl::Models::AgentPendingApproval, pending+ assert_equal approval_id, pending.id+ assert_equal "calls", pending.kind+ assert_equal "Apollo charges per lookup.", pending.reason+ assert_nil pending.terms+ assert_equal true, pending.resolution.approved+ assert_equal ["call-1"], pending.resolution.call_ids+ assert_equal false, pending.resolution.always+ assert_equal "agent-turn-2", pending.resolution.by_run_id+ call = pending.calls.first+ assert_equal "call-1", call.id+ assert_equal "apollo", call.provider+ assert_equal "people/match", call.capability+ assert_equal({ "domain" => "example.com" }, call.input)+ assert_equal [{ "domain" => "example.org" }], call.more+ assert_equal 3, call.credits_estimate+ end++ def test_get_agent_status_with_terms_required_action+ approval_id = "0199aaaa-0000-7000-8000-000000000000"+ stub_request(:get, "#{BASE_URL}/v2/agent/agent-terms")+ .to_return(+ status: 200,+ body: JSON.generate(+ success: true,+ status: "completed",+ expiresAt: "2026-09-02T00:00:00.000Z",+ exchange: {+ enabled: true,+ onTermsRequired: "ask",+ paidCalls: 0,+ creditsUsed: nil,+ skippedProviders: [+ {+ provider: "clearbit",+ name: "Clearbit",+ reason: "terms_required",+ version: "F-1.0.0",+ termsUrl: "https://www.firecrawl.dev/app/alexandria/clearbit",+ },+ ],+ requiresAction: {+ type: "accept_terms",+ approvalId: approval_id,+ providers: [+ {+ provider: "clearbit",+ name: "Clearbit",+ version: "F-1.0.0",+ digest: nil,+ url: "https://www.firecrawl.dev/app/alexandria/clearbit",+ show: { provider: "firecrawl", capability: "terms/show", options: { provider: "clearbit" } },+ accept: {+ provider: "firecrawl",+ capability: "terms/accept",+ options: { provider: "clearbit", version: "F-1.0.0", digest: nil, confirmed: true },+ },+ },+ ],+ },+ },+ pendingApproval: {+ id: approval_id,+ kind: "terms",+ reason: "Clearbit could add company size.",+ calls: [],+ terms: [+ {+ provider: "clearbit",+ name: "Clearbit",+ version: "F-1.0.0",+ digest: nil,+ url: "https://www.firecrawl.dev/app/alexandria/clearbit",+ },+ ],+ resolution: nil,+ }+ ),+ headers: { "Content-Type" => "application/json" }+ )++ status = @client.get_agent_status("agent-terms")++ action = status.exchange.requires_action+ assert_equal "accept_terms", action.type+ assert_equal approval_id, action.approval_id+ provider = action.providers.first+ assert_equal "clearbit", provider.provider+ assert_equal "F-1.0.0", provider.version+ assert_nil provider.digest+ assert_equal "https://www.firecrawl.dev/app/alexandria/clearbit", provider.url+ assert_equal "terms/show", provider.show["capability"]+ assert_equal "terms/accept", provider.accept["capability"]+ assert_equal true, provider.accept["options"]["confirmed"]++ pending = status.pending_approval+ assert_equal "terms", pending.kind+ assert_equal [], pending.calls+ assert_equal "clearbit", pending.terms.first.provider+ assert_nil pending.terms.first.digest+ assert_nil pending.resolution+ end+# ================================================================# USAGE & METRICS# ================================================================