Skip to content

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

fix(sdks): add spark-2 to agent model types

Rakshith Ramprakash26e555e0aa6d
diff --git a/apps/elixir-sdk/lib/firecrawl.ex b/apps/elixir-sdk/lib/firecrawl.ex
index 07c944793..a1ff52f9a 100644
--- a/apps/elixir-sdk/lib/firecrawl.ex
+++ b/apps/elixir-sdk/lib/firecrawl.ex
@@ -1348,7 +1348,7 @@ defmodule Firecrawl do
@start_agent_schema NimbleOptions.new!([
audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution to include with SIEM logging events."],
max_credits: [type: {:or, [:integer, :float]}, doc: "Maximum credits to spend on this agent task. Defaults to 2500 if not set. Values above 2,500 are always billed as paid requests."],
- model: [type: {:or, [{:in, [:"spark-1-mini", :"spark-1-pro"]}, :string]}, doc: "The model to use for the agent task. spark-1-mini (default) is 60% cheaper, spark-1-pro offers higher accuracy for complex tasks"],
+ model: [type: {:or, [{:in, [:"spark-1-mini", :"spark-1-pro", :"spark-2"]}, :string]}, doc: "The model to use for the agent task. spark-2 (default) handles most tasks, spark-1-mini is 60% cheaper than spark-1-pro, spark-1-pro offers higher accuracy for complex tasks"],
prompt: [type: :string, required: true, doc: "The prompt describing what data to extract"],
schema: [type: :any, doc: "Optional JSON schema to structure the extracted data"],
strict_constrain_to_urls: [type: :boolean, doc: "If true, agent will only visit URLs provided in the urls array"],
diff --git a/apps/elixir-sdk/mix.exs b/apps/elixir-sdk/mix.exs
index a9fe4235a..6f95af7f0 100644
--- a/apps/elixir-sdk/mix.exs
+++ b/apps/elixir-sdk/mix.exs
@@ -1,7 +1,7 @@
defmodule Firecrawl.MixProject do
use Mix.Project
- @version "1.9.1"
+ @version "1.9.2"
@source_url "https://github.com/firecrawl/firecrawl/tree/main/apps/elixir-sdk"
def project do
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentOptions.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentOptions.java
index 36c9b1ba4..2b1a16ce8 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentOptions.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentOptions.java
@@ -61,7 +61,7 @@ public class AgentOptions {
public Builder maxCredits(Integer maxCredits) { this.maxCredits = maxCredits; return this; }
/** Don't navigate outside provided URLs. */
public Builder strictConstrainToURLs(Boolean strictConstrainToURLs) { this.strictConstrainToURLs = strictConstrainToURLs; return this; }
- /** Agent model: "spark-1-pro" or "spark-1-mini". */
+ /** Agent model: "spark-2" (default), "spark-1-pro", or "spark-1-mini". */
public Builder model(String model) { this.model = model; return this; }
/** Webhook configuration. */
public Builder webhook(WebhookConfig webhook) { this.webhook = webhook; return this; }
diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.json
index 1c98a72be..f6df5416b 100644
--- a/apps/js-sdk/firecrawl/package.json
+++ b/apps/js-sdk/firecrawl/package.json
@@ -1,6 +1,6 @@
{
"name": "@mendable/firecrawl-js",
- "version": "4.34.0",
+ "version": "4.34.1",
"description": "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
"main": "dist/index.js",
"types": "dist/index.d.ts",
diff --git a/apps/js-sdk/firecrawl/src/v2/methods/agent.ts b/apps/js-sdk/firecrawl/src/v2/methods/agent.ts
index d87113542..aed8bcc22 100644
--- a/apps/js-sdk/firecrawl/src/v2/methods/agent.ts
+++ b/apps/js-sdk/firecrawl/src/v2/methods/agent.ts
@@ -12,7 +12,7 @@ function prepareAgentPayload(args: {
origin?: string;
maxCredits?: number;
strictConstrainToURLs?: boolean;
- model?: "spark-1-pro" | "spark-1-mini";
+ model?: "spark-1-pro" | "spark-1-mini" | "spark-2";
webhook?: string | AgentWebhookConfig;
threatProtection?: ThreatProtectionOptions;
auditMetadata?: AuditMetadata;
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index 120f41049..bf364606e 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -1244,7 +1244,12 @@ export interface AgentStatusResponse {
status: "processing" | "completed" | "failed";
error?: string;
data?: unknown;
- model?: "spark-1-pro" | "spark-1-mini";
+ /**
+ * Server-provided model name. Widened past the request-side union on
+ * purpose: new models ship without an SDK release, so pinning this to known
+ * names makes every future model a type error at the call site.
+ */
+ model?: "spark-1-pro" | "spark-1-mini" | "spark-2" | (string & {});
expiresAt: string;
creditsUsed?: number;
}
diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.py
index 0174e915f..c4babac4c 100644
--- a/apps/python-sdk/firecrawl/__init__.py
+++ b/apps/python-sdk/firecrawl/__init__.py
@@ -18,7 +18,7 @@ from .v1 import (
V1ChangeTrackingOptions,
)
-__version__ = "4.37.0"
+__version__ = "4.37.1"
# Define the logger for the Firecrawl project
logger: logging.Logger = logging.getLogger("firecrawl")
diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_request_preparation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_request_preparation.py
index 6ccc7225d..32478a547 100644
--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_request_preparation.py
+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_request_preparation.py
@@ -7,7 +7,7 @@ from pydantic import BaseModel, Field
from typing import List, Optional
from firecrawl.v2.methods.agent import _prepare_agent_request
-from firecrawl.v2.types import AgentWebhookConfig
+from firecrawl.v2.types import AgentResponse, AgentWebhookConfig
class TestAgentRequestPreparation:
@@ -337,3 +337,34 @@ class TestAgentRequestPreparation:
assert data["model"] == "spark-1-pro"
assert data["webhook"]["url"] == "https://example.com/webhook"
+ @pytest.mark.parametrize("model", ["spark-2", "spark-1-pro", "spark-1-mini"])
+ def test_model_forwarded_verbatim(self, model):
+ """Every documented model, including spark-2, reaches the request body."""
+ data = _prepare_agent_request(None, prompt="Model test", model=model)
+
+ assert data["model"] == model
+
+
+class TestAgentResponseParsing:
+ """Unit tests for parsing agent status payloads."""
+
+ @pytest.mark.parametrize("model", ["spark-2", "spark-1-pro", "spark-1-mini"])
+ def test_status_payload_parses_known_models(self, model):
+ """A status payload naming any current model parses.
+
+ /v2/agent/:id always returns `model`, and it defaults to spark-2, so a
+ narrow type here breaks every poll of a default-model job.
+ """
+ response = AgentResponse(
+ **{"success": True, "id": "job-1", "status": "completed", "model": model}
+ )
+
+ assert response.model == model
+
+ def test_status_payload_parses_unreleased_model(self):
+ """An unknown model name must not raise; the server ships models first."""
+ response = AgentResponse(
+ **{"success": True, "id": "job-1", "status": "completed", "model": "spark-3"}
+ )
+
+ assert response.model == "spark-3"
diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.py
index e2cbf8094..6655520a7 100644
--- a/apps/python-sdk/firecrawl/v2/client.py
+++ b/apps/python-sdk/firecrawl/v2/client.py
@@ -1357,7 +1357,7 @@ class FirecrawlClient:
integration: Optional[str] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
@@ -1370,7 +1370,7 @@ class FirecrawlClient:
schema: Target JSON schema for the output (dict or Pydantic BaseModel)
integration: Integration tag/name
max_credits: Maximum credits to use (optional)
- model: Model to use for the agent ("spark-1-pro" or "spark-1-mini")
+ model: Model to use for the agent ("spark-2" (default), "spark-1-pro", or "spark-1-mini")
webhook: Webhook URL or configuration for notifications
threat_protection: Enterprise per-request override of the team's
threat protection policy
@@ -1403,7 +1403,7 @@ class FirecrawlClient:
timeout: Optional[int] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
@@ -1418,7 +1418,7 @@ class FirecrawlClient:
poll_interval: Seconds between status checks
timeout: Maximum seconds to wait (None for no timeout)
max_credits: Maximum credits to use (optional)
- model: Model to use for the agent ("spark-1-pro" or "spark-1-mini")
+ model: Model to use for the agent ("spark-2" (default), "spark-1-pro", or "spark-1-mini")
webhook: Webhook URL or configuration for notifications
threat_protection: Enterprise per-request override of the team's
threat protection policy
diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.py
index a9db3e2c8..587c823fc 100644
--- a/apps/python-sdk/firecrawl/v2/client_async.py
+++ b/apps/python-sdk/firecrawl/v2/client_async.py
@@ -694,7 +694,7 @@ class AsyncFirecrawlClient:
timeout: Optional[int] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
@@ -727,7 +727,7 @@ class AsyncFirecrawlClient:
integration: Optional[str] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
diff --git a/apps/python-sdk/firecrawl/v2/methods/agent.py b/apps/python-sdk/firecrawl/v2/methods/agent.py
index 64a22dc98..7d6e63e63 100644
--- a/apps/python-sdk/firecrawl/v2/methods/agent.py
+++ b/apps/python-sdk/firecrawl/v2/methods/agent.py
@@ -15,7 +15,7 @@ def _prepare_agent_request(
integration: Optional[str] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
@@ -73,7 +73,7 @@ def start_agent(
integration: Optional[str] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
@@ -133,7 +133,7 @@ def agent(
timeout: Optional[int] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/agent.py b/apps/python-sdk/firecrawl/v2/methods/aio/agent.py
index 0b7fb67b1..8ddab3409 100644
--- a/apps/python-sdk/firecrawl/v2/methods/aio/agent.py
+++ b/apps/python-sdk/firecrawl/v2/methods/aio/agent.py
@@ -15,7 +15,7 @@ def _prepare_agent_request(
integration: Optional[str] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
@@ -73,7 +73,7 @@ async def start_agent(
integration: Optional[str] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
@@ -133,7 +133,7 @@ async def agent(
timeout: Optional[int] = None,
max_credits: Optional[int] = None,
strict_constrain_to_urls: Optional[bool] = None,
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None,
+ model: Optional[Literal["spark-1-pro", "spark-1-mini", "spark-2"]] = None,
webhook: Optional[Union[str, AgentWebhookConfig]] = None,
threat_protection: Optional[ThreatProtectionOptions] = None,
audit_metadata: Optional[AuditMetadata] = None,
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index d97dc9391..fc5199e95 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -1447,7 +1447,10 @@ class AgentResponse(BaseModel):
status: Optional[Literal["processing", "completed", "failed"]] = None
data: Optional[Any] = None
error: Optional[str] = None
- model: Optional[Literal["spark-1-pro", "spark-1-mini"]] = None
+ # Deliberately a plain str, not a Literal: this is server-provided and new
+ # models ship without an SDK release, so a narrow type turns an unknown
+ # model name into a ValidationError on every status poll.
+ model: Optional[str] = None
expires_at: Optional[datetime] = None
credits_used: Optional[int] = None
diff --git a/apps/rust-sdk/CHANGELOG.md b/apps/rust-sdk/CHANGELOG.md
index 2f1996072..dbb541844 100644
--- a/apps/rust-sdk/CHANGELOG.md
+++ b/apps/rust-sdk/CHANGELOG.md
@@ -1,5 +1,13 @@
## CHANGELOG
+## [2.15.0] - 2026-08-21
+
+### Added
+
+- Added `AgentModel::Spark2` for the `spark-2` agent model, now the server-side
+ default. Agent status responses for jobs running it previously failed to
+ deserialize.
+
## [2.14.0] - 2026-08-19
### Added
diff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lock
index c00d6c2f9..35d3e537c 100644
--- a/apps/rust-sdk/Cargo.lock
+++ b/apps/rust-sdk/Cargo.lock
@@ -250,7 +250,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
[[package]]
name = "firecrawl"
-version = "2.14.0"
+version = "2.15.0"
dependencies = [
"mockito",
"reqwest",
diff --git a/apps/rust-sdk/Cargo.toml b/apps/rust-sdk/Cargo.toml
index 81db3eb7c..a86a81885 100644
--- a/apps/rust-sdk/Cargo.toml
+++ b/apps/rust-sdk/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "firecrawl"
-version = "2.14.0"
+version = "2.15.0"
edition = "2021"
license = "MIT"
homepage = "https://www.firecrawl.dev/"
diff --git a/apps/rust-sdk/src/agent.rs b/apps/rust-sdk/src/agent.rs
index ae6cb077a..9292a7f1b 100644
--- a/apps/rust-sdk/src/agent.rs
+++ b/apps/rust-sdk/src/agent.rs
@@ -32,7 +32,7 @@ pub struct AgentOptions {
/// Strictly constrain the agent to the provided URLs.
pub strict_constrain_to_urls: Option<bool>,
- /// Agent model to use.
+ /// Agent model to use. Defaults to `spark-2` server-side when unset.
pub model: Option<AgentModel>,
/// Webhook configuration for agent notifications.
diff --git a/apps/rust-sdk/src/types.rs b/apps/rust-sdk/src/types.rs
index b05c911b1..e98a38985 100644
--- a/apps/rust-sdk/src/types.rs
+++ b/apps/rust-sdk/src/types.rs
@@ -991,6 +991,8 @@ pub enum AgentModel {
Spark1Pro,
#[serde(rename = "spark-1-mini")]
Spark1Mini,
+ #[serde(rename = "spark-2")]
+ Spark2,
}
/// Search source types.