Skip to content

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

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.md
index 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
### Added
diff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lock
index 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.toml
index 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.rs
index 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.rs
index 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")]