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(rust-sdk): add agent exchange, threadId and mode options (#4988)
Gergő Móricz776a87f060d6
diff --git a/apps/rust-sdk/CHANGELOG.md b/apps/rust-sdk/CHANGELOG.mdindex f5363bb32..9d1d84931 100644--- a/apps/rust-sdk/CHANGELOG.md+++ b/apps/rust-sdk/CHANGELOG.md@@ -1,5 +1,18 @@## CHANGELOG+## [2.21.3] - 2026-10-06++### Added++- Added `AgentOptions::exchange` (`AgentExchangeOptions`) so agent runs can use+ the team's Exchange (Alexandria) data providers, including `approve` and+ `decline` answers to a pending approval. Added `AgentOptions::thread_id` and+ `AgentOptions::mode` (`AgentMode`) to continue a thread and run in chat mode.+- `AgentResponse` now carries `thread_id` and `thread_turn`.+ `AgentStatusResponse` now carries `thread_id`, `thread_turn`, `mode`,+ `message`, `pending_approval` (`AgentPendingApproval`), and `exchange`+ (`AgentExchangeSummary`).+## [2.21.2] - 2026-10-02### Addeddiff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lockindex 717cf4418..06631529b 100644--- a/apps/rust-sdk/Cargo.lock+++ b/apps/rust-sdk/Cargo.lock@@ -250,7 +250,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"[[package]]name = "firecrawl"-version = "2.21.2"+version = "2.21.3"dependencies = ["mockito","reqwest",diff --git a/apps/rust-sdk/Cargo.toml b/apps/rust-sdk/Cargo.tomlindex c9120059e..abb196d44 100644--- a/apps/rust-sdk/Cargo.toml+++ b/apps/rust-sdk/Cargo.toml@@ -1,6 +1,6 @@[package]name = "firecrawl"-version = "2.21.2"+version = "2.21.3"edition = "2021"license = "MIT"homepage = "https://www.firecrawl.dev/"diff --git a/apps/rust-sdk/src/agent.rs b/apps/rust-sdk/src/agent.rsindex 3d1013e0b..f3b9086c9 100644--- a/apps/rust-sdk/src/agent.rs+++ b/apps/rust-sdk/src/agent.rs@@ -4,7 +4,10 @@//! to accomplish complex tasks that may require multiple page interactions.use crate::client::Client;-use crate::types::{AgentEffort, AgentModel, AgentWebhookConfig};+use crate::types::{+ AgentEffort, AgentExchangeOptions, AgentMode, AgentModel, AgentOnTermsRequired,+ AgentWebhookConfig,+};use crate::{AuditMetadata, FirecrawlError};use serde::{Deserialize, Serialize};use serde_json::Value;@@ -48,6 +51,15 @@ pub struct AgentOptions {/// User attribution to include with SIEM logging events.pub audit_metadata: Option<AuditMetadata>,+ /// Continue this thread as its next turn. Omitted starts a new thread.+ pub thread_id: Option<String>,++ /// Conversation mode. The server defaults to `AgentMode::Extract`.+ pub mode: Option<AgentMode>,++ /// Let the agent use the team's Exchange (Alexandria) data providers.+ pub exchange: Option<AgentExchangeOptions>,+/// Poll interval for synchronous agent execution (milliseconds).#[serde(skip)]pub poll_interval: Option<u64>,@@ -67,6 +79,10 @@ pub struct AgentResponse {pub id: String,/// Error message if the request failed.pub error: Option<String>,+ /// Thread this run belongs to; pass it back to continue the conversation.+ pub thread_id: Option<String>,+ /// 1-based position of this run in its thread.+ pub thread_turn: Option<u32>,}/// Agent task status.@@ -104,6 +120,156 @@ pub struct AgentStatusResponse {pub expires_at: Option<String>,/// Credits used by the agent task.pub credits_used: Option<u32>,+ /// Thread this run belongs to; pass it back to continue the conversation.+ pub thread_id: Option<String>,+ /// 1-based position of this run in its thread.+ pub thread_turn: Option<u32>,+ pub mode: Option<AgentMode>,+ /// Text reply. Chat-mode runs answer here instead of in `data`.+ pub message: Option<String>,+ /// Set when the turn ended waiting for the caller to answer it.+ pub pending_approval: Option<AgentPendingApproval>,+ /// What the run did with Exchange, when it was enabled.+ pub exchange: Option<AgentExchangeSummary>,+}++/// A turn that ended waiting for the caller. Answer it on the next turn of+/// the thread with `AgentExchangeOptions::approve` or `decline`.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentPendingApproval {+ pub id: String,+ /// `None` on approvals written before terms offers existed; those are+ /// call approvals.+ pub kind: Option<AgentPendingApprovalKind>,+ pub reason: String,+ /// Paid calls waiting for approval. Always empty on a terms approval.+ pub calls: Vec<AgentPendingApprovalCall>,+ /// Providers whose data terms need accepting, on a terms approval.+ pub terms: Option<Vec<AgentTermsGate>>,+ /// How a later turn answered it, once answered.+ pub resolution: Option<AgentPendingApprovalResolution>,+}++/// What a pending approval is waiting for.+#[derive(Deserialize, Serialize, Clone, Copy, Debug, PartialEq, Eq)]+#[serde(rename_all = "lowercase")]+pub enum AgentPendingApprovalKind {+ Calls,+ Terms,+ /// A kind this SDK release does not know about.+ #[serde(other)]+ Unknown,+}++/// A paid provider call held back by a pending approval.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentPendingApprovalCall {+ pub id: String,+ pub provider: String,+ pub capability: String,+ pub input: Value,+ pub more: Option<Vec<Value>>,+ pub credits_estimate: Option<u32>,+}++/// How a pending approval was answered.+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentPendingApprovalResolution {+ pub approved: bool,+ /// Calls approved. Empty on terms approvals.+ pub call_ids: Vec<String>,+ pub always: bool,+ pub by_run_id: String,+}++/// A provider whose data terms the team has not accepted.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentTermsGate {+ pub provider: String,+ pub name: String,+ pub logo: Option<String>,+ pub capability: Option<String>,+ /// What it would have added, in the agent's words.+ pub adds: Option<String>,+ pub version: String,+ /// `None` when the catalog published no digest.+ pub digest: Option<String>,+ /// Where a person accepts the terms in the dashboard.+ pub url: String,+}++/// What a run did with Exchange. `toolkits` and `require_approval` are what+/// the run resolved to after thread inheritance, not what it requested.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentExchangeSummary {+ pub enabled: bool,+ pub toolkits: Option<Vec<String>>,+ pub require_approval: Option<bool>,+ pub on_terms_required: Option<AgentOnTermsRequired>,+ pub paid_calls: u32,+ pub credits_used: Option<u32>,+ /// Gated providers that would have helped and were not used.+ pub skipped_providers: Option<Vec<AgentSkippedProvider>>,+ /// Set in `AgentOnTermsRequired::Ask` mode when a terms offer ended the+ /// turn.+ pub requires_action: Option<AgentTermsRequiredAction>,+}++/// A gated provider the run would have used but did not.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentSkippedProvider {+ pub provider: String,+ pub name: String,+ pub capability: Option<String>,+ pub adds: Option<String>,+ /// Why it was skipped, such as `terms_required`.+ pub reason: String,+ pub version: String,+ /// Where a person accepts the terms in the dashboard.+ pub terms_url: String,+}++/// The Exchange calls that view and accept gated providers' terms. Nothing+/// runs them for you; only call `accept` after the user has agreed.+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentTermsRequiredAction {+ /// Identifies the step, such as `accept_terms`.+ #[serde(rename = "type")]+ pub kind: String,+ /// The terms pending approval to approve once the terms are accepted.+ pub approval_id: String,+ pub providers: Vec<AgentTermsActionProvider>,+}++/// A provider in an `AgentTermsRequiredAction`.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentTermsActionProvider {+ pub provider: String,+ pub name: String,+ pub capability: Option<String>,+ pub adds: Option<String>,+ pub version: String,+ /// `None` when the catalog published no digest.+ pub digest: Option<String>,+ pub url: String,+ /// The terms/show call, as `{provider, capability, options}`.+ pub show: Value,+ /// The terms/accept call, as `{provider, capability, options}`.+ pub accept: Value,}/// Per-session settings attached to an agent run.@@ -920,6 +1086,7 @@ impl Client {#[cfg(test)]mod tests {use super::*;+ use crate::types::{AgentExchangeApprove, AgentExchangeDecline};use mockito::Matcher;use serde_json::json;@@ -1515,4 +1682,254 @@ mod tests {assert!(response.success);mock.assert();}++ #[tokio::test]+ async fn test_start_agent_sends_thread_mode_and_exchange() -> Result<(), FirecrawlError> {+ let mut server = mockito::Server::new_async().await;++ let mock = server+ .mock("POST", "/v2/agent")+ .match_body(Matcher::Json(json!({+ "prompt": "Find the CTO's work email",+ "origin": format!("rust-sdk@{}", env!("CARGO_PKG_VERSION")),+ "threadId": "0199aaaa-0000-7000-8000-000000000001",+ "mode": "chat",+ "exchange": {+ "enabled": true,+ "toolkits": ["acme"],+ "maxCalls": 4,+ "requireApproval": true,+ "approve": {+ "approvalId": "0199aaaa-0000-7000-8000-000000000002",+ "callIds": ["call-1"],+ "always": true+ },+ "decline": {"approvalId": "0199aaaa-0000-7000-8000-000000000003"},+ "onTermsRequired": "ask"+ }+ })))+ .with_status(200)+ .with_header("content-type", "application/json")+ .with_body(+ json!({+ "success": true,+ "id": "agent-123",+ "threadId": "0199aaaa-0000-7000-8000-000000000001",+ "threadTurn": 2+ })+ .to_string(),+ )+ .create();++ let client = Client::new_selfhosted(server.url(), Some("test_key"))?;+ let options = AgentOptions {+ prompt: "Find the CTO's work email".to_string(),+ thread_id: Some("0199aaaa-0000-7000-8000-000000000001".to_string()),+ mode: Some(AgentMode::Chat),+ exchange: Some(AgentExchangeOptions {+ enabled: Some(true),+ toolkits: Some(vec!["acme".to_string()]),+ max_calls: Some(4),+ require_approval: Some(true),+ approve: Some(AgentExchangeApprove {+ approval_id: "0199aaaa-0000-7000-8000-000000000002".to_string(),+ call_ids: Some(vec!["call-1".to_string()]),+ always: Some(true),+ }),+ decline: Some(AgentExchangeDecline {+ approval_id: "0199aaaa-0000-7000-8000-000000000003".to_string(),+ }),+ on_terms_required: Some(AgentOnTermsRequired::Ask),+ }),+ ..Default::default()+ };++ let response = client.start_agent(options).await?;++ assert_eq!(+ response.thread_id.as_deref(),+ Some("0199aaaa-0000-7000-8000-000000000001")+ );+ assert_eq!(response.thread_turn, Some(2));+ mock.assert();+ Ok(())+ }++ #[tokio::test]+ async fn test_start_agent_omits_unset_exchange_fields() -> Result<(), FirecrawlError> {+ let mut server = mockito::Server::new_async().await;++ let mock = server+ .mock("POST", "/v2/agent")+ .match_body(Matcher::Json(json!({+ "prompt": "Find the CTO's work email",+ "origin": format!("rust-sdk@{}", env!("CARGO_PKG_VERSION")),+ "exchange": {+ "approve": {"approvalId": "0199aaaa-0000-7000-8000-000000000002"}+ }+ })))+ .with_status(200)+ .with_header("content-type", "application/json")+ .with_body(json!({"success": true, "id": "agent-123"}).to_string())+ .create();++ let client = Client::new_selfhosted(server.url(), Some("test_key"))?;+ let options = AgentOptions {+ prompt: "Find the CTO's work email".to_string(),+ exchange: Some(AgentExchangeOptions {+ approve: Some(AgentExchangeApprove {+ approval_id: "0199aaaa-0000-7000-8000-000000000002".to_string(),+ ..Default::default()+ }),+ ..Default::default()+ }),+ ..Default::default()+ };++ let response = client.start_agent(options).await?;++ assert!(response.thread_id.is_none());+ assert!(response.thread_turn.is_none());+ mock.assert();+ Ok(())+ }++ #[tokio::test]+ async fn test_get_agent_status_with_exchange_and_pending_approval() -> Result<(), FirecrawlError>+ {+ let mut server = mockito::Server::new_async().await;++ let mock = server+ .mock("GET", "/v2/agent/agent-123")+ .with_status(200)+ .with_header("content-type", "application/json")+ .with_body(+ json!({+ "success": true,+ "status": "completed",+ "model": "spark-2",+ "expiresAt": "2026-10-07T12:00:00.000Z",+ "creditsUsed": 12,+ "threadId": "0199aaaa-0000-7000-8000-000000000001",+ "threadTurn": 1,+ "mode": "chat",+ "message": "Two calls need your approval.",+ "suggestions": [{"label": "Approve", "prompt": "Go ahead"}],+ "futureField": {"ignored": true},+ "pendingApproval": {+ "id": "0199aaaa-0000-7000-8000-000000000002",+ "kind": "calls",+ "reason": "These calls cost credits.",+ "calls": [{+ "id": "call-1",+ "provider": "acme",+ "capability": "people/search",+ "input": {"company": "example.com", "title": "CTO"},+ "more": [{"company": "example.org"}],+ "creditsEstimate": 50+ }],+ "resolution": null+ },+ "exchange": {+ "enabled": true,+ "toolkits": ["acme"],+ "requireApproval": true,+ "onTermsRequired": "ask",+ "paidCalls": 0,+ "creditsUsed": null,+ "skippedProviders": [{+ "provider": "globex",+ "name": "Globex",+ "capability": "company/lookup",+ "adds": "verified company records",+ "reason": "terms_required",+ "version": "F-1.0.0",+ "termsUrl": "https://www.firecrawl.dev/app/alexandria/globex"+ }],+ "requiresAction": {+ "type": "accept_terms",+ "approvalId": "0199aaaa-0000-7000-8000-000000000003",+ "providers": [{+ "provider": "globex",+ "name": "Globex",+ "version": "F-1.0.0",+ "digest": null,+ "url": "https://www.firecrawl.dev/app/alexandria/globex",+ "show": {+ "provider": "firecrawl",+ "capability": "terms/show",+ "options": {"provider": "globex"}+ },+ "accept": {+ "provider": "firecrawl",+ "capability": "terms/accept",+ "options": {+ "provider": "globex",+ "version": "F-1.0.0",+ "digest": null,+ "confirmed": true+ }+ }+ }]+ }+ }+ })+ .to_string(),+ )+ .create();++ let client = Client::new_selfhosted(server.url(), Some("test_key"))?;+ let status = client.get_agent_status("agent-123").await?;++ assert_eq!(status.status, AgentStatus::Completed);+ assert_eq!(+ status.thread_id.as_deref(),+ Some("0199aaaa-0000-7000-8000-000000000001")+ );+ assert_eq!(status.thread_turn, Some(1));+ assert_eq!(status.mode, Some(AgentMode::Chat));+ assert_eq!(+ status.message.as_deref(),+ Some("Two calls need your approval.")+ );++ let approval = status.pending_approval.ok_or_else(|| {+ FirecrawlError::Misuse("pendingApproval did not deserialize".to_string())+ })?;+ assert_eq!(approval.id, "0199aaaa-0000-7000-8000-000000000002");+ assert_eq!(approval.kind, Some(AgentPendingApprovalKind::Calls));+ assert!(approval.terms.is_none());+ assert!(approval.resolution.is_none());+ assert_eq!(approval.calls.len(), 1);+ assert_eq!(approval.calls[0].id, "call-1");+ assert_eq!(approval.calls[0].provider, "acme");+ assert_eq!(approval.calls[0].input["title"], "CTO");+ assert_eq!(approval.calls[0].more.as_ref().map(Vec::len), Some(1));+ assert_eq!(approval.calls[0].credits_estimate, Some(50));++ let exchange = status+ .exchange+ .ok_or_else(|| FirecrawlError::Misuse("exchange did not deserialize".to_string()))?;+ assert!(exchange.enabled);+ assert_eq!(exchange.on_terms_required, Some(AgentOnTermsRequired::Ask));+ assert_eq!(exchange.paid_calls, 0);+ assert!(exchange.credits_used.is_none());+ let skipped = exchange.skipped_providers.unwrap_or_default();+ assert_eq!(skipped.len(), 1);+ assert_eq!(skipped[0].reason, "terms_required");+ assert_eq!(+ skipped[0].terms_url,+ "https://www.firecrawl.dev/app/alexandria/globex"+ );+ let action = exchange.requires_action.ok_or_else(|| {+ FirecrawlError::Misuse("requiresAction did not deserialize".to_string())+ })?;+ assert_eq!(action.kind, "accept_terms");+ assert_eq!(action.approval_id, "0199aaaa-0000-7000-8000-000000000003");+ assert_eq!(action.providers.len(), 1);+ assert!(action.providers[0].digest.is_none());+ assert_eq!(action.providers[0].accept["capability"], "terms/accept");+ mock.assert();+ Ok(())+ }}diff --git a/apps/rust-sdk/src/types.rs b/apps/rust-sdk/src/types.rsindex abd73cc92..93ade4cf7 100644--- a/apps/rust-sdk/src/types.rs+++ b/apps/rust-sdk/src/types.rs@@ -1030,6 +1030,79 @@ pub enum AgentEffort {Unknown,}+/// Agent conversation mode. The server defaults to `Extract`.+#[derive(Deserialize, Serialize, Clone, Copy, Debug, PartialEq, Eq)]+#[serde(rename_all = "lowercase")]+pub enum AgentMode {+ Extract,+ /// Answers in `AgentStatusResponse::message` instead of `data`.+ Chat,+ /// Read-only catch-all, same rationale as `AgentModel::Unknown`. Do not+ /// send it in a request.+ #[serde(other)]+ Unknown,+}++/// What the agent does when a provider needs data terms the team has not+/// accepted. Gated providers are never called in either mode.+#[derive(Deserialize, Serialize, Clone, Copy, Debug, PartialEq, Eq)]+#[serde(rename_all = "lowercase")]+pub enum AgentOnTermsRequired {+ /// Answer without the gated providers and list them in+ /// `AgentExchangeSummary::skipped_providers`. The server default.+ Skip,+ /// Also end the turn with a `terms` pending approval.+ Ask,+ /// Read-only catch-all, same rationale as `AgentModel::Unknown`. Do not+ /// send it in a request.+ #[serde(other)]+ Unknown,+}++/// Exchange (Alexandria data provider) settings for an agent run, forwarded+/// as-is: the server owns every default and limit. On a follow-up turn,+/// omitting it inherits the previous turn's settings.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Default, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentExchangeOptions {+ /// Defaults to true server-side once exchange options are sent.+ pub enabled: Option<bool>,+ /// Provider slugs to pin, at most 5. Omitted or empty allows every+ /// provider the team can use.+ pub toolkits: Option<Vec<String>>,+ /// Maximum provider calls per turn, 1 to 30.+ pub max_calls: Option<u32>,+ /// End the turn with a pending approval before any paid provider call.+ /// Requires `AgentMode::Chat` on every turn of the thread.+ pub require_approval: Option<bool>,+ /// Answers the previous turn's pending approval. Requires a thread id.+ pub approve: Option<AgentExchangeApprove>,+ /// Refuses the previous turn's pending approval. Requires a thread id.+ pub decline: Option<AgentExchangeDecline>,+ pub on_terms_required: Option<AgentOnTermsRequired>,+}++/// Approves a pending approval. A `terms` approval is accepted as a whole, so+/// `call_ids` and `always` are ignored on it.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Default, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentExchangeApprove {+ pub approval_id: String,+ /// Calls to allow. Omitted allows every pending call.+ pub call_ids: Option<Vec<String>>,+ /// Also stop requiring approval for the rest of the thread.+ pub always: Option<bool>,+}++/// Declines a pending approval.+#[derive(Deserialize, Serialize, Debug, Default, Clone)]+#[serde(rename_all = "camelCase")]+pub struct AgentExchangeDecline {+ pub approval_id: String,+}+/// Search source types.#[derive(Deserialize, Serialize, Clone, Copy, Debug, PartialEq, Eq)]#[serde(rename_all = "lowercase")]