Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

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.md
index 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 & Metrics
diff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rb
index 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.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_exchange_summary.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_exchange_summary.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_options.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_options.rb
index 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 AgentOptions
FIELDS = %i[
urls prompt schema integration max_credits
strict_constrain_to_urls model effort webhook audit_metadata
+ thread_id mode exchange
].freeze
attr_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,
}.compact
end
end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_pending_approval.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_pending_approval.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_response.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_response.rb
index 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 Firecrawl
module Models
# Response from starting an agent task.
class AgentResponse
- attr_reader :success, :id, :error
+ attr_reader :success, :id, :error, :thread_id, :thread_turn
def 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"]
end
def to_s
diff --git a/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rb b/apps/ruby-sdk/lib/firecrawl/models/agent_status_response.rb
index 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 Firecrawl
module 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,
+ :exchange
def 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"])
end
def done?
diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rb
index 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: true
module Firecrawl
- VERSION = "1.17.1"
+ VERSION = "1.17.3"
end
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index 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::Test
assert_equal "https://api.firecrawl.dev/v2/agent?before=1756600000000", response.next
end
+ 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
# ================================================================