Skip to content

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

feat(java): agent exchange, threadId and mode (#4984)

Gergő Móricz3a5f89c5d25f
diff --git a/apps/java-sdk/README.md b/apps/java-sdk/README.md
index cc37aa8af..e5a24874e 100644
--- a/apps/java-sdk/README.md
+++ b/apps/java-sdk/README.md
@@ -363,6 +363,23 @@ AgentStatusResponse result = client.agent(
System.out.println(result.getData());
```
+To let the agent use the Exchange (Alexandria) data providers connected to your team, pass `exchange`. `toolkits` pins up to 5 providers by slug; omit it to allow all of them.
+
+```java
+AgentStatusResponse result = client.agent(
+ AgentOptions.builder()
+ .prompt("Find the head of engineering at example.com")
+ .exchange(AgentExchangeOptions.builder()
+ .enabled(true)
+ .toolkits(List.of("provider-slug"))
+ .build())
+ .build());
+
+if (result.getExchange() != null) {
+ System.out.println("Paid provider calls: " + result.getExchange().getPaidCalls());
+}
+```
+
### Usage & Metrics
```java
diff --git a/apps/java-sdk/build.gradle.kts b/apps/java-sdk/build.gradle.kts
index 36ed0dc14..f67fb6ce1 100644
--- a/apps/java-sdk/build.gradle.kts
+++ b/apps/java-sdk/build.gradle.kts
@@ -4,7 +4,7 @@ plugins {
}
group = "com.firecrawl"
-version = "1.18.2"
+version = "1.18.3"
java {
sourceCompatibility = JavaVersion.VERSION_11
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java
index eeb552b1c..e4ad4fea7 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java
@@ -37,7 +37,7 @@ import java.util.concurrent.ForkJoinPool;
public class FirecrawlClient {
private static final String DEFAULT_API_URL = "https://api.firecrawl.dev";
- private static final String SDK_ORIGIN = "[email protected]";
+ private static final String SDK_ORIGIN = "[email protected]";
private static final long DEFAULT_TIMEOUT_MS = 300_000; // 5 minutes
private static final int DEFAULT_MAX_RETRIES = 3;
private static final double DEFAULT_BACKOFF_FACTOR = 0.5;
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentExchangeOptions.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentExchangeOptions.java
new file mode 100644
index 000000000..9ba7d5859
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentExchangeOptions.java
@@ -0,0 +1,114 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Exchange (Alexandria data provider) settings for an agent run. Every field is
+ * optional and forwarded as-is; the server owns the defaults and limits.
+ *
+ * <p>Usage:
+ * <pre>{@code
+ * AgentExchangeOptions exchange = AgentExchangeOptions.builder()
+ * .enabled(true)
+ * .toolkits(List.of("provider-slug"))
+ * .build();
+ * }</pre>
+ */
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class AgentExchangeOptions {
+
+ private Boolean enabled;
+ private List<String> toolkits;
+ private Integer maxCalls;
+ private Boolean requireApproval;
+ private Approve approve;
+ private Decline decline;
+ private String onTermsRequired;
+
+ private AgentExchangeOptions() {}
+
+ public Boolean getEnabled() { return enabled; }
+ public List<String> getToolkits() { return toolkits; }
+ public Integer getMaxCalls() { return maxCalls; }
+ public Boolean getRequireApproval() { return requireApproval; }
+ public Approve getApprove() { return approve; }
+ public Decline getDecline() { return decline; }
+ public String getOnTermsRequired() { return onTermsRequired; }
+
+ public static Builder builder() { return new Builder(); }
+
+ /** Accepts the previous turn's pending approval. */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class Approve {
+ private final String approvalId;
+ private final List<String> callIds;
+ private final Boolean always;
+
+ public Approve(String approvalId) { this(approvalId, null, null); }
+
+ /**
+ * @param callIds the calls to run; null runs all of them. Ignored on a terms approval.
+ * @param always stop asking for approval for the rest of the thread. Ignored on a terms approval.
+ */
+ public Approve(String approvalId, List<String> callIds, Boolean always) {
+ this.approvalId = Objects.requireNonNull(approvalId, "approvalId");
+ this.callIds = callIds;
+ this.always = always;
+ }
+
+ public String getApprovalId() { return approvalId; }
+ public List<String> getCallIds() { return callIds; }
+ public Boolean getAlways() { return always; }
+ }
+
+ /** Refuses the previous turn's pending approval. */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class Decline {
+ private final String approvalId;
+
+ public Decline(String approvalId) { this.approvalId = Objects.requireNonNull(approvalId, "approvalId"); }
+
+ public String getApprovalId() { return approvalId; }
+ }
+
+ public static final class Builder {
+ private Boolean enabled;
+ private List<String> toolkits;
+ private Integer maxCalls;
+ private Boolean requireApproval;
+ private Approve approve;
+ private Decline decline;
+ private String onTermsRequired;
+
+ private Builder() {}
+
+ /** Use Exchange providers on this run. The server defaults it to true once exchange is set. */
+ public Builder enabled(Boolean enabled) { this.enabled = enabled; return this; }
+ /** Provider slugs to use, at most 5. Empty or omitted allows every provider the team can use. */
+ public Builder toolkits(List<String> toolkits) { this.toolkits = toolkits; return this; }
+ /** Maximum provider calls per turn. */
+ public Builder maxCalls(Integer maxCalls) { this.maxCalls = maxCalls; return this; }
+ /** End the turn with a pending approval before a paid provider call. Needs mode "chat". */
+ public Builder requireApproval(Boolean requireApproval) { this.requireApproval = requireApproval; return this; }
+ /** Accept the previous turn's pending approval. Needs threadId. */
+ public Builder approve(Approve approve) { this.approve = approve; return this; }
+ /** Refuse the previous turn's pending approval. Needs threadId. */
+ public Builder decline(Decline decline) { this.decline = decline; return this; }
+ /** When a provider needs terms the team has not accepted: "skip" (server default) or "ask". */
+ public Builder onTermsRequired(String onTermsRequired) { this.onTermsRequired = onTermsRequired; return this; }
+
+ public AgentExchangeOptions build() {
+ AgentExchangeOptions o = new AgentExchangeOptions();
+ o.enabled = this.enabled;
+ o.toolkits = this.toolkits;
+ o.maxCalls = this.maxCalls;
+ o.requireApproval = this.requireApproval;
+ o.approve = this.approve;
+ o.decline = this.decline;
+ o.onTermsRequired = this.onTermsRequired;
+ return o;
+ }
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentExchangeSummary.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentExchangeSummary.java
new file mode 100644
index 000000000..adb0be27f
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentExchangeSummary.java
@@ -0,0 +1,37 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * What an agent run did with Exchange (Alexandria data providers).
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AgentExchangeSummary {
+
+ private boolean enabled;
+ private List<String> toolkits;
+ private Boolean requireApproval;
+ private String onTermsRequired;
+ private int paidCalls;
+ private Integer creditsUsed;
+ private List<AgentSkippedProvider> skippedProviders;
+ private AgentTermsRequiredAction requiresAction;
+
+ public boolean isEnabled() { return enabled; }
+ /** What the run resolved to after thread inheritance, not what it requested. */
+ public List<String> getToolkits() { return toolkits; }
+ public Boolean getRequireApproval() { return requireApproval; }
+ public String getOnTermsRequired() { return onTermsRequired; }
+ public int getPaidCalls() { return paidCalls; }
+ public Integer getCreditsUsed() { return creditsUsed; }
+ /** Providers that need terms the team has not accepted, so the run did not use them. */
+ public List<AgentSkippedProvider> getSkippedProviders() { return skippedProviders; }
+ /** Set in "ask" mode when a terms offer ended the turn. */
+ public AgentTermsRequiredAction getRequiresAction() { return requiresAction; }
+
+ @Override
+ public String toString() {
+ return "AgentExchangeSummary{enabled=" + enabled + ", paidCalls=" + paidCalls + ", creditsUsed=" + creditsUsed + "}";
+ }
+}
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 cf5cea2d3..de66e1a98 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
@@ -21,6 +21,9 @@ public class AgentOptions {
private String effort;
private WebhookConfig webhook;
private AuditMetadata auditMetadata;
+ private String threadId;
+ private String mode;
+ private AgentExchangeOptions exchange;
private AgentOptions() {}
@@ -35,6 +38,9 @@ public class AgentOptions {
public WebhookConfig getWebhook() { return webhook; }
@JsonProperty("auditMetadata")
public AuditMetadata getAuditMetadata() { return auditMetadata; }
+ public String getThreadId() { return threadId; }
+ public String getMode() { return mode; }
+ public AgentExchangeOptions getExchange() { return exchange; }
public static Builder builder() { return new Builder(); }
@@ -49,6 +55,9 @@ public class AgentOptions {
private String effort;
private WebhookConfig webhook;
private AuditMetadata auditMetadata;
+ private String threadId;
+ private String mode;
+ private AgentExchangeOptions exchange;
private Builder() {}
@@ -72,6 +81,12 @@ public class AgentOptions {
public Builder webhook(WebhookConfig webhook) { this.webhook = webhook; return this; }
/** User attribution to include with SIEM logging events. */
public Builder auditMetadata(AuditMetadata auditMetadata) { this.auditMetadata = auditMetadata; return this; }
+ /** Run as the next turn of this thread. Omitted starts a new thread. */
+ public Builder threadId(String threadId) { this.threadId = threadId; return this; }
+ /** Run mode: "extract" (server default) or "chat". */
+ public Builder mode(String mode) { this.mode = mode; return this; }
+ /** Exchange (Alexandria data provider) settings. Omitted on a follow-up turn inherits the previous turn's. */
+ public Builder exchange(AgentExchangeOptions exchange) { this.exchange = exchange; return this; }
public AgentOptions build() {
if (prompt == null || prompt.isEmpty()) {
@@ -88,6 +103,9 @@ public class AgentOptions {
o.effort = this.effort;
o.webhook = this.webhook;
o.auditMetadata = this.auditMetadata;
+ o.threadId = this.threadId;
+ o.mode = this.mode;
+ o.exchange = this.exchange;
return o;
}
}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentPendingApproval.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentPendingApproval.java
new file mode 100644
index 000000000..e37ea49db
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentPendingApproval.java
@@ -0,0 +1,34 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * A turn that ended waiting for the caller. Kind "calls" (or null on older runs)
+ * holds paid {@code calls}; kind "terms" lists providers' {@code terms} and has no calls.
+ * Answer it on the next turn of the thread with {@code AgentExchangeOptions.Approve} or
+ * {@code AgentExchangeOptions.Decline}.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AgentPendingApproval {
+
+ private String id;
+ private String kind;
+ private String reason;
+ private List<AgentPendingApprovalCall> calls;
+ private List<AgentTermsGate> terms;
+ private AgentPendingApprovalResolution resolution;
+
+ public String getId() { return id; }
+ public String getKind() { return kind; }
+ public String getReason() { return reason; }
+ public List<AgentPendingApprovalCall> getCalls() { return calls; }
+ public List<AgentTermsGate> getTerms() { return terms; }
+ /** Null until a later turn answers the approval. */
+ public AgentPendingApprovalResolution getResolution() { return resolution; }
+
+ @Override
+ public String toString() {
+ return "AgentPendingApproval{id=" + id + ", kind=" + kind + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentPendingApprovalCall.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentPendingApprovalCall.java
new file mode 100644
index 000000000..b831a39a0
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentPendingApprovalCall.java
@@ -0,0 +1,32 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A paid provider call held back by a pending approval.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AgentPendingApprovalCall {
+
+ private String id;
+ private String provider;
+ private String capability;
+ private Map<String, Object> input;
+ private List<Map<String, Object>> more;
+ private Integer creditsEstimate;
+
+ public String getId() { return id; }
+ public String getProvider() { return provider; }
+ public String getCapability() { return capability; }
+ public Map<String, Object> getInput() { return input; }
+ public List<Map<String, Object>> getMore() { return more; }
+ /** Null when the provider lists no per-call price. */
+ public Integer getCreditsEstimate() { return creditsEstimate; }
+
+ @Override
+ public String toString() {
+ return "AgentPendingApprovalCall{id=" + id + ", provider=" + provider + ", capability=" + capability + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentPendingApprovalResolution.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentPendingApprovalResolution.java
new file mode 100644
index 000000000..eb9f2cf51
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentPendingApprovalResolution.java
@@ -0,0 +1,27 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * How a later turn answered a pending approval.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AgentPendingApprovalResolution {
+
+ private boolean approved;
+ private List<String> callIds;
+ private boolean always;
+ private String byRunId;
+
+ public boolean isApproved() { return approved; }
+ /** Calls approved. Empty on a terms approval. */
+ public List<String> getCallIds() { return callIds; }
+ public boolean isAlways() { return always; }
+ public String getByRunId() { return byRunId; }
+
+ @Override
+ public String toString() {
+ return "AgentPendingApprovalResolution{approved=" + approved + ", byRunId=" + byRunId + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentResponse.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentResponse.java
index 5f5581204..49fb5edbf 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentResponse.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentResponse.java
@@ -11,10 +11,16 @@ public class AgentResponse {
private boolean success;
private String id;
private String error;
+ private String threadId;
+ private Integer threadTurn;
public boolean isSuccess() { return success; }
public String getId() { return id; }
public String getError() { return error; }
+ /** Thread this run belongs to; pass it to {@code AgentOptions.Builder.threadId} to continue it. */
+ public String getThreadId() { return threadId; }
+ /** 1-based position of this run in its thread. */
+ public Integer getThreadTurn() { return threadTurn; }
@Override
public String toString() {
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentSkippedProvider.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentSkippedProvider.java
new file mode 100644
index 000000000..80625e656
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentSkippedProvider.java
@@ -0,0 +1,34 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/**
+ * A provider the run would have used but skipped because its terms are not accepted.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AgentSkippedProvider {
+
+ private String provider;
+ private String name;
+ private String capability;
+ private String adds;
+ private String reason;
+ private String version;
+ private String termsUrl;
+
+ public String getProvider() { return provider; }
+ public String getName() { return name; }
+ public String getCapability() { return capability; }
+ /** What it would have added, in the agent's words. */
+ public String getAdds() { return adds; }
+ /** "terms_required". */
+ public String getReason() { return reason; }
+ public String getVersion() { return version; }
+ /** Where a person accepts the terms in the dashboard. */
+ public String getTermsUrl() { return termsUrl; }
+
+ @Override
+ public String toString() {
+ return "AgentSkippedProvider{provider=" + provider + ", reason=" + reason + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentStatusResponse.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentStatusResponse.java
index f1a28ccbf..f4852dcdc 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentStatusResponse.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentStatusResponse.java
@@ -16,6 +16,12 @@ public class AgentStatusResponse {
private String effort;
private String expiresAt;
private Integer creditsUsed;
+ private String threadId;
+ private Integer threadTurn;
+ private String mode;
+ private String message;
+ private AgentPendingApproval pendingApproval;
+ private AgentExchangeSummary exchange;
public boolean isSuccess() { return success; }
public String getStatus() { return status; }
@@ -26,6 +32,14 @@ public class AgentStatusResponse {
public String getEffort() { return effort; }
public String getExpiresAt() { return expiresAt; }
public Integer getCreditsUsed() { return creditsUsed; }
+ public String getThreadId() { return threadId; }
+ public Integer getThreadTurn() { return threadTurn; }
+ public String getMode() { return mode; }
+ /** Text reply. Chat-mode runs answer here instead of in {@code data}. */
+ public String getMessage() { return message; }
+ /** Set when the turn ended waiting for the caller to approve or decline. */
+ public AgentPendingApproval getPendingApproval() { return pendingApproval; }
+ public AgentExchangeSummary getExchange() { return exchange; }
public boolean isDone() {
return "completed".equals(status) || "failed".equals(status) || "cancelled".equals(status);
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentTermsActionProvider.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentTermsActionProvider.java
new file mode 100644
index 000000000..96943cbf1
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentTermsActionProvider.java
@@ -0,0 +1,39 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.Map;
+
+/**
+ * A provider whose terms the caller can view and accept.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AgentTermsActionProvider {
+
+ private String provider;
+ private String name;
+ private String capability;
+ private String adds;
+ private String version;
+ private String digest;
+ private String url;
+ private Map<String, Object> show;
+ private Map<String, Object> accept;
+
+ public String getProvider() { return provider; }
+ public String getName() { return name; }
+ public String getCapability() { return capability; }
+ public String getAdds() { return adds; }
+ public String getVersion() { return version; }
+ /** Null when the catalog published no digest; terms/show returns it. */
+ public String getDigest() { return digest; }
+ public String getUrl() { return url; }
+ /** The Exchange call that shows the terms: provider, capability, options. */
+ public Map<String, Object> getShow() { return show; }
+ /** The Exchange call that accepts the terms: provider, capability, options. */
+ public Map<String, Object> getAccept() { return accept; }
+
+ @Override
+ public String toString() {
+ return "AgentTermsActionProvider{provider=" + provider + ", version=" + version + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentTermsGate.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentTermsGate.java
new file mode 100644
index 000000000..c5a4aec2f
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentTermsGate.java
@@ -0,0 +1,35 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/**
+ * A provider in a "terms" pending approval.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AgentTermsGate {
+
+ private String provider;
+ private String name;
+ private String logo;
+ private String capability;
+ private String adds;
+ private String version;
+ private String digest;
+ private String url;
+
+ public String getProvider() { return provider; }
+ public String getName() { return name; }
+ public String getLogo() { return logo; }
+ public String getCapability() { return capability; }
+ public String getAdds() { return adds; }
+ public String getVersion() { return version; }
+ /** Null when the catalog published no digest; terms/show returns it. */
+ public String getDigest() { return digest; }
+ /** Where a person accepts the terms in the dashboard. */
+ public String getUrl() { return url; }
+
+ @Override
+ public String toString() {
+ return "AgentTermsGate{provider=" + provider + ", version=" + version + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/AgentTermsRequiredAction.java b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentTermsRequiredAction.java
new file mode 100644
index 000000000..c528a792a
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/AgentTermsRequiredAction.java
@@ -0,0 +1,27 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * The Exchange calls to view and accept providers' terms. Nothing here runs for
+ * you; only call terms/accept after the user has explicitly agreed.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AgentTermsRequiredAction {
+
+ private String type;
+ private String approvalId;
+ private List<AgentTermsActionProvider> providers;
+
+ /** "accept_terms". */
+ public String getType() { return type; }
+ /** The terms pending approval to answer with {@code AgentExchangeOptions.Approve} once the terms are accepted. */
+ public String getApprovalId() { return approvalId; }
+ public List<AgentTermsActionProvider> getProviders() { return providers; }
+
+ @Override
+ public String toString() {
+ return "AgentTermsRequiredAction{type=" + type + ", approvalId=" + approvalId + "}";
+ }
+}
diff --git a/apps/java-sdk/src/test/java/com/firecrawl/AgentMockTest.java b/apps/java-sdk/src/test/java/com/firecrawl/AgentMockTest.java
index 8dca838b1..1db20f7f9 100644
--- a/apps/java-sdk/src/test/java/com/firecrawl/AgentMockTest.java
+++ b/apps/java-sdk/src/test/java/com/firecrawl/AgentMockTest.java
@@ -1,11 +1,19 @@
package com.firecrawl;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
import com.firecrawl.client.FirecrawlClient;
+import com.firecrawl.models.AgentExchangeOptions;
+import com.firecrawl.models.AgentExchangeSummary;
import com.firecrawl.models.AgentListItem;
import com.firecrawl.models.AgentListResponse;
import com.firecrawl.models.AgentOptions;
+import com.firecrawl.models.AgentPendingApproval;
+import com.firecrawl.models.AgentPendingApprovalCall;
import com.firecrawl.models.AgentResponse;
import com.firecrawl.models.AgentSnapshotResponse;
+import com.firecrawl.models.AgentStatusResponse;
+import com.firecrawl.models.AgentTermsActionProvider;
import com.firecrawl.models.AgentTraceEvent;
import com.firecrawl.models.AgentTraceResponse;
import com.sun.net.httpserver.HttpServer;
@@ -17,6 +25,8 @@ import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Map;
import java.util.concurrent.atomic.AtomicReference;
import static org.junit.jupiter.api.Assertions.*;
@@ -24,12 +34,16 @@ import static org.junit.jupiter.api.Assertions.*;
/**
* Agent endpoint tests against a local mock HTTP server.
*
- * Verifies request serialization (effort parameter, query params) and
- * response parsing for the agent trace and snapshot endpoints without
- * requiring a live API key.
+ * Verifies request serialization (effort, thread and exchange options, query
+ * params) and response parsing for the agent status, trace and snapshot
+ * endpoints without requiring a live API key.
*/
class AgentMockTest {
+ private static final ObjectMapper MAPPER = new ObjectMapper();
+ private static final String THREAD_ID = "0199bbbb-0000-7000-8000-000000000000";
+ private static final String APPROVAL_ID = "0199aaaa-0000-7000-8000-000000000000";
+
private HttpServer server;
private FirecrawlClient client;
private final AtomicReference<String> lastRequestBody = new AtomicReference<>();
@@ -56,10 +70,54 @@ class AgentMockTest {
+ "}]"
+ "}");
} else {
- respond(exchange, 200, "{\"success\":true,\"id\":\"job-123\"}");
+ respond(exchange, 200, "{\"success\":true,\"id\":\"job-123\","
+ + "\"threadId\":\"" + THREAD_ID + "\",\"threadTurn\":2}");
}
});
+ server.createContext("/v2/agent/job-123", exchange -> {
+ lastRequestPath.set(exchange.getRequestURI().toString());
+ respond(exchange, 200, "{"
+ + "\"success\":true,\"status\":\"completed\",\"model\":\"spark-2\","
+ + "\"expiresAt\":\"2026-10-07T00:00:00.000Z\",\"creditsUsed\":12,"
+ + "\"threadId\":\"" + THREAD_ID + "\",\"threadTurn\":2,\"mode\":\"chat\","
+ + "\"message\":\"One paid call needs your approval.\","
+ + "\"suggestions\":[{\"label\":\"Approve\",\"prompt\":\"Go ahead\"}],"
+ + "\"someFutureField\":{\"nested\":true},"
+ + "\"pendingApproval\":{\"id\":\"" + APPROVAL_ID + "\",\"kind\":\"calls\","
+ + " \"reason\":\"Provider A charges per lookup.\","
+ + " \"calls\":[{\"id\":\"call-1\",\"provider\":\"provider-a\",\"capability\":\"people/search\","
+ + " \"input\":{\"query\":\"example\",\"limit\":5},\"more\":[{\"query\":\"example 2\"}],"
+ + " \"creditsEstimate\":4,\"futureCallField\":1}],"
+ + " \"resolution\":null},"
+ + "\"exchange\":{\"enabled\":true,\"toolkits\":[\"provider-a\"],\"requireApproval\":true,"
+ + " \"onTermsRequired\":\"ask\",\"paidCalls\":1,\"creditsUsed\":null,"
+ + " \"skippedProviders\":[{\"provider\":\"provider-b\",\"name\":\"Provider B\","
+ + " \"capability\":\"company/enrich\",\"adds\":\"verified work emails\","
+ + " \"reason\":\"terms_required\",\"version\":\"F-1.0.0\","
+ + " \"termsUrl\":\"https://www.firecrawl.dev/app/alexandria/provider-b\"}],"
+ + " \"requiresAction\":{\"type\":\"accept_terms\",\"approvalId\":\"" + APPROVAL_ID + "\","
+ + " \"providers\":[{\"provider\":\"provider-b\",\"name\":\"Provider B\",\"version\":\"F-1.0.0\","
+ + " \"digest\":null,\"url\":\"https://www.firecrawl.dev/app/alexandria/provider-b\","
+ + " \"show\":{\"provider\":\"firecrawl\",\"capability\":\"terms/show\","
+ + " \"options\":{\"provider\":\"provider-b\"}},"
+ + " \"accept\":{\"provider\":\"firecrawl\",\"capability\":\"terms/accept\","
+ + " \"options\":{\"provider\":\"provider-b\",\"version\":\"F-1.0.0\",\"digest\":null,\"confirmed\":true}}}]}}"
+ + "}");
+ });
+
+ server.createContext("/v2/agent/job-terms", exchange -> {
+ lastRequestPath.set(exchange.getRequestURI().toString());
+ respond(exchange, 200, "{"
+ + "\"success\":true,\"status\":\"completed\",\"expiresAt\":\"2026-10-07T00:00:00.000Z\","
+ + "\"pendingApproval\":{\"id\":\"" + APPROVAL_ID + "\",\"kind\":\"terms\","
+ + " \"reason\":\"Provider B could add verified work emails.\",\"calls\":[],"
+ + " \"terms\":[{\"provider\":\"provider-b\",\"name\":\"Provider B\",\"logo\":\"https://example.com/b.png\","
+ + " \"version\":\"F-1.0.0\",\"digest\":\"sha256:abc\",\"url\":\"https://www.firecrawl.dev/app/alexandria/provider-b\"}],"
+ + " \"resolution\":{\"approved\":true,\"callIds\":[],\"always\":false,\"byRunId\":\"job-next\"}}"
+ + "}");
+ });
+
server.createContext("/v2/agent/job-123/trace", exchange -> {
lastRequestPath.set(exchange.getRequestURI().toString());
respond(exchange, 200, "{"
@@ -143,6 +201,162 @@ class AgentMockTest {
assertFalse(body.contains("effort"), "Request body should not contain effort: " + body);
}
+ @Test
+ void testStartAgentSendsExchangeThreadAndMode() throws IOException {
+ AgentResponse response = client.startAgent(
+ AgentOptions.builder()
+ .prompt("Continue")
+ .threadId(THREAD_ID)
+ .mode("chat")
+ .exchange(AgentExchangeOptions.builder()
+ .enabled(true)
+ .toolkits(List.of("provider-a", "provider-b"))
+ .maxCalls(8)
+ .requireApproval(true)
+ .approve(new AgentExchangeOptions.Approve(APPROVAL_ID, List.of("call-1", "call-2"), true))
+ .decline(new AgentExchangeOptions.Decline(APPROVAL_ID))
+ .onTermsRequired("ask")
+ .build())
+ .build());
+
+ assertEquals(THREAD_ID, response.getThreadId());
+ assertEquals(2, response.getThreadTurn());
+
+ JsonNode body = MAPPER.readTree(lastRequestBody.get());
+ assertEquals(THREAD_ID, body.get("threadId").asText());
+ assertEquals("chat", body.get("mode").asText());
+ assertEquals(MAPPER.readTree("{"
+ + "\"enabled\":true,"
+ + "\"toolkits\":[\"provider-a\",\"provider-b\"],"
+ + "\"maxCalls\":8,"
+ + "\"requireApproval\":true,"
+ + "\"approve\":{\"approvalId\":\"" + APPROVAL_ID + "\",\"callIds\":[\"call-1\",\"call-2\"],\"always\":true},"
+ + "\"decline\":{\"approvalId\":\"" + APPROVAL_ID + "\"},"
+ + "\"onTermsRequired\":\"ask\""
+ + "}"), body.get("exchange"));
+ }
+
+ @Test
+ void testStartAgentOmitsThreadModeAndExchangeWhenNotSet() throws IOException {
+ AgentResponse response = client.startAgent(AgentOptions.builder().prompt("Hello").build());
+
+ JsonNode body = MAPPER.readTree(lastRequestBody.get());
+ assertFalse(body.has("threadId"), "Request body should not contain threadId: " + body);
+ assertFalse(body.has("mode"), "Request body should not contain mode: " + body);
+ assertFalse(body.has("exchange"), "Request body should not contain exchange: " + body);
+ assertEquals("job-123", response.getId());
+ }
+
+ @Test
+ void testStartAgentOmitsUnsetExchangeFields() throws IOException {
+ client.startAgent(AgentOptions.builder()
+ .prompt("Continue")
+ .threadId(THREAD_ID)
+ .exchange(AgentExchangeOptions.builder()
+ .enabled(true)
+ .approve(new AgentExchangeOptions.Approve(APPROVAL_ID))
+ .build())
+ .build());
+
+ JsonNode body = MAPPER.readTree(lastRequestBody.get());
+ assertEquals(MAPPER.readTree("{\"enabled\":true,\"approve\":{\"approvalId\":\"" + APPROVAL_ID + "\"}}"),
+ body.get("exchange"));
+ }
+
+ @Test
+ void testApproveAndDeclineRequireApprovalId() {
+ assertThrows(NullPointerException.class, () -> new AgentExchangeOptions.Approve(null));
+ assertThrows(NullPointerException.class, () -> new AgentExchangeOptions.Approve(null, List.of("call-1"), true));
+ assertThrows(NullPointerException.class, () -> new AgentExchangeOptions.Decline(null));
+ }
+
+ @Test
+ void testAgentParsesExchangeSummaryAndPendingApproval() throws IOException {
+ AgentStatusResponse status = client.agent(
+ AgentOptions.builder()
+ .prompt("Find the contact at example.com")
+ .mode("chat")
+ .exchange(AgentExchangeOptions.builder().requireApproval(true).build())
+ .build(),
+ 1, 10);
+
+ assertEquals("{\"requireApproval\":true}",
+ MAPPER.readTree(lastRequestBody.get()).get("exchange").toString());
+ assertEquals("/v2/agent/job-123", lastRequestPath.get());
+
+ assertTrue(status.isDone());
+ assertEquals(THREAD_ID, status.getThreadId());
+ assertEquals(2, status.getThreadTurn());
+ assertEquals("chat", status.getMode());
+ assertEquals("One paid call needs your approval.", status.getMessage());
+
+ AgentPendingApproval pending = status.getPendingApproval();
+ assertNotNull(pending);
+ assertEquals(APPROVAL_ID, pending.getId());
+ assertEquals("calls", pending.getKind());
+ assertEquals("Provider A charges per lookup.", pending.getReason());
+ assertNull(pending.getTerms());
+ assertNull(pending.getResolution());
+ AgentPendingApprovalCall call = pending.getCalls().get(0);
+ assertEquals("call-1", call.getId());
+ assertEquals("provider-a", call.getProvider());
+ assertEquals("people/search", call.getCapability());
+ assertEquals("example", call.getInput().get("query"));
+ assertEquals(5, call.getInput().get("limit"));
+ assertEquals("example 2", call.getMore().get(0).get("query"));
+ assertEquals(4, call.getCreditsEstimate());
+
+ AgentExchangeSummary exchange = status.getExchange();
+ assertNotNull(exchange);
+ assertTrue(exchange.isEnabled());
+ assertEquals(List.of("provider-a"), exchange.getToolkits());
+ assertTrue(exchange.getRequireApproval());
+ assertEquals("ask", exchange.getOnTermsRequired());
+ assertEquals(1, exchange.getPaidCalls());
+ assertNull(exchange.getCreditsUsed());
+
+ assertEquals(1, exchange.getSkippedProviders().size());
+ assertEquals("provider-b", exchange.getSkippedProviders().get(0).getProvider());
+ assertEquals("Provider B", exchange.getSkippedProviders().get(0).getName());
+ assertEquals("company/enrich", exchange.getSkippedProviders().get(0).getCapability());
+ assertEquals("verified work emails", exchange.getSkippedProviders().get(0).getAdds());
+ assertEquals("terms_required", exchange.getSkippedProviders().get(0).getReason());
+ assertEquals("F-1.0.0", exchange.getSkippedProviders().get(0).getVersion());
+ assertEquals("https://www.firecrawl.dev/app/alexandria/provider-b",
+ exchange.getSkippedProviders().get(0).getTermsUrl());
+
+ assertEquals("accept_terms", exchange.getRequiresAction().getType());
+ assertEquals(APPROVAL_ID, exchange.getRequiresAction().getApprovalId());
+ AgentTermsActionProvider provider = exchange.getRequiresAction().getProviders().get(0);
+ assertEquals("provider-b", provider.getProvider());
+ assertEquals("F-1.0.0", provider.getVersion());
+ assertNull(provider.getDigest());
+ assertEquals("https://www.firecrawl.dev/app/alexandria/provider-b", provider.getUrl());
+ assertEquals("terms/show", provider.getShow().get("capability"));
+ assertEquals("terms/accept", provider.getAccept().get("capability"));
+ Map<?, ?> acceptOptions = (Map<?, ?>) provider.getAccept().get("options");
+ assertTrue(acceptOptions.containsKey("digest"));
+ assertNull(acceptOptions.get("digest"));
+ assertEquals(true, acceptOptions.get("confirmed"));
+ }
+
+ @Test
+ void testGetAgentStatusParsesTermsApproval() {
+ AgentStatusResponse status = client.getAgentStatus("job-terms");
+
+ AgentPendingApproval pending = status.getPendingApproval();
+ assertEquals("terms", pending.getKind());
+ assertTrue(pending.getCalls().isEmpty());
+ assertEquals("provider-b", pending.getTerms().get(0).getProvider());
+ assertEquals("https://example.com/b.png", pending.getTerms().get(0).getLogo());
+ assertEquals("sha256:abc", pending.getTerms().get(0).getDigest());
+ assertTrue(pending.getResolution().isApproved());
+ assertFalse(pending.getResolution().isAlways());
+ assertEquals("job-next", pending.getResolution().getByRunId());
+ assertNull(status.getExchange());
+ assertNull(status.getThreadId());
+ }
+
@Test
void testGetAgentTraceParsesEvents() {
AgentTraceResponse trace = client.getAgentTrace("job-123");