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(java): agent exchange, threadId and mode (#4984)
Gergő Móricz3a5f89c5d25f
diff --git a/apps/java-sdk/README.md b/apps/java-sdk/README.mdindex 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```javadiff --git a/apps/java-sdk/build.gradle.kts b/apps/java-sdk/build.gradle.ktsindex 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_11diff --git a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.javaindex 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 minutesprivate 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.javanew file mode 100644index 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.javanew file mode 100644index 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.javaindex 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.javanew file mode 100644index 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.javanew file mode 100644index 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.javanew file mode 100644index 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.javaindex 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; }@Overridepublic 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.javanew file mode 100644index 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.javaindex 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.javanew file mode 100644index 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.javanew file mode 100644index 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.javanew file mode 100644index 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.javaindex 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());+ }+@Testvoid testGetAgentTraceParsesEvents() {AgentTraceResponse trace = client.getAgentTrace("job-123");