Skip to content

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

feat(go-sdk): add agent exchange, threadId and mode options (#4987)

Gergő Móricz13fcb07bd814
diff --git a/apps/go-sdk/README.md b/apps/go-sdk/README.md
index d7524ca4b..9f5d932d1 100644
--- a/apps/go-sdk/README.md
+++ b/apps/go-sdk/README.md
@@ -295,6 +295,15 @@ resp, err := client.StartAgent(ctx, &firecrawl.AgentOptions{
})
status, err := client.GetAgentStatus(ctx, resp.ID)
_, err = client.CancelAgent(ctx, resp.ID)
+
+// Let the agent use Exchange data providers connected to your team
+status, err = client.Agent(ctx, &firecrawl.AgentOptions{
+ Prompt: "Summarize the latest earnings for AAPL",
+ Exchange: &firecrawl.AgentExchangeOptions{
+ Enabled: firecrawl.Bool(true),
+ Toolkits: &[]string{"your-provider-slug"},
+ },
+})
```
### Browser
diff --git a/apps/go-sdk/agent_test.go b/apps/go-sdk/agent_test.go
index 39257fc55..48de41877 100644
--- a/apps/go-sdk/agent_test.go
+++ b/apps/go-sdk/agent_test.go
@@ -2,9 +2,11 @@ package firecrawl
import (
"context"
+ "encoding/json"
"io"
"net/http"
"net/http/httptest"
+ "reflect"
"strings"
"testing"
@@ -438,3 +440,317 @@ func TestListAgentsSendsBefore(t *testing.T) {
t.Errorf("next = %q", resp.Next)
}
}
+
+func TestStartAgentSendsExchangeThreadAndMode(t *testing.T) {
+ captured := make(chan capturedRequest, 1)
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ captured <- captureRequest(r)
+
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte(`{"success":true,"id":"job-2","threadId":"11111111-1111-4111-8111-111111111111","threadTurn":2}`))
+ }))
+ defer server.Close()
+
+ client, err := NewClient(
+ option.WithAPIKey("fc-test"),
+ option.WithAPIURL(server.URL),
+ )
+ if err != nil {
+ t.Fatalf("NewClient: %v", err)
+ }
+
+ resp, err := client.StartAgent(context.Background(), &AgentOptions{
+ Prompt: "go ahead",
+ ThreadID: String("11111111-1111-4111-8111-111111111111"),
+ Mode: String("chat"),
+ Exchange: &AgentExchangeOptions{
+ Enabled: Bool(true),
+ Toolkits: &[]string{"acme-markets", "acme-companies"},
+ MaxCalls: Int(5),
+ RequireApproval: Bool(true),
+ Approve: &AgentExchangeApprove{
+ ApprovalID: "22222222-2222-4222-8222-222222222222",
+ CallIDs: &[]string{"call-1", "call-2"},
+ Always: Bool(false),
+ },
+ Decline: &AgentExchangeDecline{ApprovalID: "33333333-3333-4333-8333-333333333333"},
+ OnTermsRequired: String("ask"),
+ },
+ })
+ if err != nil {
+ t.Fatalf("StartAgent: %v", err)
+ }
+
+ req := <-captured
+ if req.method != http.MethodPost || req.path != "/v2/agent" {
+ t.Errorf("unexpected request: %s %s", req.method, req.path)
+ }
+ var body map[string]interface{}
+ if err := json.Unmarshal([]byte(req.body), &body); err != nil {
+ t.Fatalf("decode body %q: %v", req.body, err)
+ }
+ var want map[string]interface{}
+ if err := json.Unmarshal([]byte(`{
+ "prompt": "go ahead",
+ "threadId": "11111111-1111-4111-8111-111111111111",
+ "mode": "chat",
+ "exchange": {
+ "enabled": true,
+ "toolkits": ["acme-markets", "acme-companies"],
+ "maxCalls": 5,
+ "requireApproval": true,
+ "approve": {
+ "approvalId": "22222222-2222-4222-8222-222222222222",
+ "callIds": ["call-1", "call-2"],
+ "always": false
+ },
+ "decline": {"approvalId": "33333333-3333-4333-8333-333333333333"},
+ "onTermsRequired": "ask"
+ }
+ }`), &want); err != nil {
+ t.Fatalf("decode want: %v", err)
+ }
+ if !reflect.DeepEqual(body, want) {
+ t.Errorf("body = %s", req.body)
+ }
+ if resp.ThreadID != "11111111-1111-4111-8111-111111111111" || resp.ThreadTurn != 2 {
+ t.Errorf("resp = %+v", resp)
+ }
+}
+
+func TestStartAgentOmitsUnsetExchangeFields(t *testing.T) {
+ tests := []struct {
+ name string
+ opts *AgentOptions
+ want string
+ }{
+ {
+ name: "no exchange",
+ opts: &AgentOptions{Prompt: "find pricing"},
+ want: `{"prompt":"find pricing"}`,
+ },
+ {
+ name: "partial exchange",
+ opts: &AgentOptions{
+ Prompt: "find pricing",
+ Exchange: &AgentExchangeOptions{
+ Enabled: Bool(true),
+ Approve: &AgentExchangeApprove{ApprovalID: "22222222-2222-4222-8222-222222222222"},
+ },
+ },
+ want: `{"prompt":"find pricing","exchange":{"enabled":true,"approve":{"approvalId":"22222222-2222-4222-8222-222222222222"}}}`,
+ },
+ {
+ name: "explicit empty lists",
+ opts: &AgentOptions{
+ Prompt: "find pricing",
+ Exchange: &AgentExchangeOptions{
+ Toolkits: &[]string{},
+ Approve: &AgentExchangeApprove{
+ ApprovalID: "22222222-2222-4222-8222-222222222222",
+ CallIDs: &[]string{},
+ },
+ },
+ },
+ want: `{"prompt":"find pricing","exchange":{"toolkits":[],"approve":{"approvalId":"22222222-2222-4222-8222-222222222222","callIds":[]}}}`,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ captured := make(chan capturedRequest, 1)
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ captured <- captureRequest(r)
+
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte(`{"success":true,"id":"job-123"}`))
+ }))
+ defer server.Close()
+
+ client, err := NewClient(
+ option.WithAPIKey("fc-test"),
+ option.WithAPIURL(server.URL),
+ )
+ if err != nil {
+ t.Fatalf("NewClient: %v", err)
+ }
+
+ if _, err := client.StartAgent(context.Background(), tt.opts); err != nil {
+ t.Fatalf("StartAgent: %v", err)
+ }
+
+ req := <-captured
+ if req.body != tt.want {
+ t.Errorf("body = %s, want %s", req.body, tt.want)
+ }
+ })
+ }
+}
+
+func TestGetAgentStatusParsesExchangeAndPendingApproval(t *testing.T) {
+ captured := make(chan capturedRequest, 1)
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ captured <- captureRequest(r)
+
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte(`{
+ "success": true,
+ "status": "completed",
+ "expiresAt": "2026-10-07T00:00:00.000Z",
+ "creditsUsed": 12,
+ "threadId": "11111111-1111-4111-8111-111111111111",
+ "threadTurn": 1,
+ "mode": "chat",
+ "message": "Two paid lookups need your approval.",
+ "suggestions": [{"label": "Approve", "prompt": "Go ahead"}],
+ "unknownTopLevel": {"ignored": true},
+ "pendingApproval": {
+ "id": "22222222-2222-4222-8222-222222222222",
+ "kind": "calls",
+ "reason": "paid provider call",
+ "calls": [{
+ "id": "call-1",
+ "provider": "acme-markets",
+ "capability": "earnings",
+ "input": {"ticker": "AAPL"},
+ "more": [{"ticker": "MSFT"}],
+ "creditsEstimate": 10
+ }, {
+ "id": "call-2",
+ "provider": "acme-companies",
+ "capability": "company",
+ "input": {"name": "Example"},
+ "creditsEstimate": null
+ }],
+ "resolution": null,
+ "unknownNested": 1
+ },
+ "exchange": {
+ "enabled": true,
+ "toolkits": ["acme-markets"],
+ "requireApproval": true,
+ "onTermsRequired": "ask",
+ "paidCalls": 0,
+ "creditsUsed": null,
+ "skippedProviders": [{
+ "provider": "acme-funding",
+ "name": "Acme Funding",
+ "capability": "funding",
+ "adds": "funding rounds",
+ "reason": "terms_required",
+ "version": "2026-01",
+ "termsUrl": "https://example.com/terms/acme-funding"
+ }],
+ "requiresAction": {
+ "type": "accept_terms",
+ "approvalId": "33333333-3333-4333-8333-333333333333",
+ "providers": [{
+ "provider": "acme-funding",
+ "name": "Acme Funding",
+ "version": "2026-01",
+ "digest": null,
+ "url": "https://example.com/terms/acme-funding",
+ "show": {"provider": "firecrawl", "capability": "terms/show", "options": {"provider": "acme-funding"}},
+ "accept": {"provider": "firecrawl", "capability": "terms/accept", "options": {"provider": "acme-funding", "version": "2026-01", "digest": null, "confirmed": true}}
+ }]
+ }
+ }
+ }`))
+ }))
+ defer server.Close()
+
+ client, err := NewClient(
+ option.WithAPIKey("fc-test"),
+ option.WithAPIURL(server.URL),
+ )
+ if err != nil {
+ t.Fatalf("NewClient: %v", err)
+ }
+
+ status, err := client.GetAgentStatus(context.Background(), "job-1")
+ if err != nil {
+ t.Fatalf("GetAgentStatus: %v", err)
+ }
+
+ req := <-captured
+ if req.method != http.MethodGet || req.path != "/v2/agent/job-1" {
+ t.Errorf("unexpected request: %s %s", req.method, req.path)
+ }
+ if status.ThreadID != "11111111-1111-4111-8111-111111111111" || status.ThreadTurn != 1 || status.Mode != "chat" {
+ t.Errorf("thread fields = %+v", status)
+ }
+ if status.Message != "Two paid lookups need your approval." {
+ t.Errorf("message = %q", status.Message)
+ }
+ if len(status.Suggestions) != 1 || status.Suggestions[0].Prompt != "Go ahead" {
+ t.Errorf("suggestions = %+v", status.Suggestions)
+ }
+
+ pending := status.PendingApproval
+ if pending == nil {
+ t.Fatalf("pendingApproval missing")
+ }
+ if pending.ID != "22222222-2222-4222-8222-222222222222" || pending.Kind != "calls" || pending.Resolution != nil {
+ t.Errorf("pendingApproval = %+v", pending)
+ }
+ if len(pending.Calls) != 2 {
+ t.Fatalf("calls = %+v", pending.Calls)
+ }
+ first := pending.Calls[0]
+ if first.ID != "call-1" || first.Provider != "acme-markets" || first.Capability != "earnings" {
+ t.Errorf("call = %+v", first)
+ }
+ if first.Input["ticker"] != "AAPL" || len(first.More) != 1 || first.More[0]["ticker"] != "MSFT" {
+ t.Errorf("call payload = %+v", first)
+ }
+ if first.CreditsEstimate == nil || *first.CreditsEstimate != 10 {
+ t.Errorf("creditsEstimate = %v", first.CreditsEstimate)
+ }
+ if pending.Calls[1].CreditsEstimate != nil {
+ t.Errorf("null creditsEstimate = %v", *pending.Calls[1].CreditsEstimate)
+ }
+
+ exchange := status.Exchange
+ if exchange == nil {
+ t.Fatalf("exchange missing")
+ }
+ if !exchange.Enabled || !exchange.RequireApproval || exchange.OnTermsRequired != "ask" || exchange.PaidCalls != 0 || exchange.CreditsUsed != nil {
+ t.Errorf("exchange = %+v", exchange)
+ }
+ if !reflect.DeepEqual(exchange.Toolkits, []string{"acme-markets"}) {
+ t.Errorf("toolkits = %v", exchange.Toolkits)
+ }
+ wantSkipped := []AgentSkippedProvider{{
+ Provider: "acme-funding",
+ Name: "Acme Funding",
+ Capability: "funding",
+ Adds: "funding rounds",
+ Reason: "terms_required",
+ Version: "2026-01",
+ TermsURL: "https://example.com/terms/acme-funding",
+ }}
+ if !reflect.DeepEqual(exchange.SkippedProviders, wantSkipped) {
+ t.Errorf("skippedProviders = %+v", exchange.SkippedProviders)
+ }
+
+ action := exchange.RequiresAction
+ if action == nil || action.Type != "accept_terms" || action.ApprovalID != "33333333-3333-4333-8333-333333333333" || len(action.Providers) != 1 {
+ t.Fatalf("requiresAction = %+v", action)
+ }
+ provider := action.Providers[0]
+ if provider.Provider != "acme-funding" || provider.Version != "2026-01" || provider.Digest != "" || provider.URL != "https://example.com/terms/acme-funding" {
+ t.Errorf("provider = %+v", provider)
+ }
+ if provider.Show.Capability != "terms/show" || provider.Show.Options["provider"] != "acme-funding" {
+ t.Errorf("show = %+v", provider.Show)
+ }
+ if provider.Accept.Provider != "firecrawl" || provider.Accept.Capability != "terms/accept" || provider.Accept.Options["confirmed"] != true {
+ t.Errorf("accept = %+v", provider.Accept)
+ }
+}
diff --git a/apps/go-sdk/models.go b/apps/go-sdk/models.go
index aac0b91dd..5d03e9d86 100644
--- a/apps/go-sdk/models.go
+++ b/apps/go-sdk/models.go
@@ -661,6 +661,11 @@ type AgentResponse struct {
Success bool `json:"success"`
ID string `json:"id,omitempty"`
Error string `json:"error,omitempty"`
+ // ThreadID is the thread this run belongs to. Pass it back in
+ // AgentOptions.ThreadID to continue the conversation.
+ ThreadID string `json:"threadId,omitempty"`
+ // ThreadTurn is the 1-based position of this run in its thread.
+ ThreadTurn int `json:"threadTurn,omitempty"`
}
// AgentStatusResponse represents the status and results of an agent task.
@@ -673,6 +678,14 @@ type AgentStatusResponse struct {
Effort string `json:"effort,omitempty"`
ExpiresAt string `json:"expiresAt,omitempty"`
CreditsUsed *int `json:"creditsUsed,omitempty"`
+ ThreadID string `json:"threadId,omitempty"`
+ ThreadTurn int `json:"threadTurn,omitempty"`
+ Mode string `json:"mode,omitempty"`
+ // Message is the text reply. Chat-mode runs answer here instead of in Data.
+ Message string `json:"message,omitempty"`
+ Suggestions []AgentSuggestion `json:"suggestions,omitempty"`
+ PendingApproval *AgentPendingApproval `json:"pendingApproval,omitempty"`
+ Exchange *AgentExchangeSummary `json:"exchange,omitempty"`
}
// IsDone returns true if the agent task has finished.
@@ -680,6 +693,108 @@ func (a *AgentStatusResponse) IsDone() bool {
return a.Status == "completed" || a.Status == "failed" || a.Status == "cancelled"
}
+// AgentSuggestion is a follow-up the agent offers for the next turn.
+type AgentSuggestion struct {
+ Label string `json:"label"`
+ Prompt string `json:"prompt"`
+}
+
+// AgentExchangeSummary reports what a run did with Exchange. Toolkits and
+// RequireApproval are what the run resolved to after thread inheritance.
+type AgentExchangeSummary struct {
+ Enabled bool `json:"enabled"`
+ Toolkits []string `json:"toolkits,omitempty"`
+ RequireApproval bool `json:"requireApproval,omitempty"`
+ OnTermsRequired string `json:"onTermsRequired,omitempty"`
+ PaidCalls int `json:"paidCalls"`
+ // CreditsUsed is nil when unknown.
+ CreditsUsed *int `json:"creditsUsed"`
+ // SkippedProviders lists providers that would have helped but were not
+ // used because their data terms are not accepted.
+ SkippedProviders []AgentSkippedProvider `json:"skippedProviders,omitempty"`
+ // RequiresAction is set in "ask" mode when a terms offer ended the turn.
+ RequiresAction *AgentTermsRequiredAction `json:"requiresAction,omitempty"`
+}
+
+// AgentSkippedProvider is a provider a run did not use because its data terms
+// are not accepted.
+type AgentSkippedProvider struct {
+ Provider string `json:"provider"`
+ Name string `json:"name"`
+ Capability string `json:"capability,omitempty"`
+ Adds string `json:"adds,omitempty"`
+ Reason string `json:"reason"`
+ Version string `json:"version"`
+ TermsURL string `json:"termsUrl"`
+}
+
+// AgentTermsRequiredAction lists the Exchange calls that show and accept
+// providers' data terms. Run Accept with ScrapeAlexandria only after the user
+// has explicitly agreed, then continue the thread with Exchange.Approve.
+type AgentTermsRequiredAction struct {
+ Type string `json:"type"`
+ ApprovalID string `json:"approvalId"`
+ Providers []AgentTermsActionProvider `json:"providers"`
+}
+
+// AgentTermsActionProvider is one provider whose data terms can be accepted.
+type AgentTermsActionProvider struct {
+ Provider string `json:"provider"`
+ Name string `json:"name"`
+ Capability string `json:"capability,omitempty"`
+ Adds string `json:"adds,omitempty"`
+ Version string `json:"version"`
+ // Digest is empty when the catalog published none; Show returns it.
+ Digest string `json:"digest"`
+ URL string `json:"url"`
+ Show AlexandriaCall `json:"show"`
+ Accept AlexandriaCall `json:"accept"`
+}
+
+// AgentPendingApproval is set when a turn ended waiting for the caller. Kind
+// "terms" asks to accept the providers in Terms and leaves Calls empty; any
+// other Kind, including empty, asks to allow or refuse Calls.
+type AgentPendingApproval struct {
+ ID string `json:"id"`
+ Kind string `json:"kind,omitempty"`
+ Reason string `json:"reason"`
+ Calls []AgentPendingApprovalCall `json:"calls"`
+ Terms []AgentTermsGate `json:"terms,omitempty"`
+ Resolution *AgentPendingApprovalResolution `json:"resolution"`
+}
+
+// AgentPendingApprovalCall is a paid provider call held back for approval.
+type AgentPendingApprovalCall struct {
+ ID string `json:"id"`
+ Provider string `json:"provider"`
+ Capability string `json:"capability"`
+ Input map[string]interface{} `json:"input"`
+ More []map[string]interface{} `json:"more,omitempty"`
+ CreditsEstimate *int `json:"creditsEstimate"`
+}
+
+// AgentTermsGate is a provider in a terms pending approval.
+type AgentTermsGate struct {
+ Provider string `json:"provider"`
+ Name string `json:"name"`
+ Logo string `json:"logo,omitempty"`
+ Capability string `json:"capability,omitempty"`
+ Adds string `json:"adds,omitempty"`
+ Version string `json:"version"`
+ // Digest is empty when the catalog published none.
+ Digest string `json:"digest"`
+ URL string `json:"url"`
+}
+
+// AgentPendingApprovalResolution records how a later turn answered a pending
+// approval.
+type AgentPendingApprovalResolution struct {
+ Approved bool `json:"approved"`
+ CallIDs []string `json:"callIds"`
+ Always bool `json:"always"`
+ ByRunID string `json:"byRunId"`
+}
+
// AgentTraceResponse is returned when fetching the event trace of an agent task.
type AgentTraceResponse struct {
Success bool `json:"success"`
diff --git a/apps/go-sdk/options.go b/apps/go-sdk/options.go
index 7bd7314ba..5acfc0394 100644
--- a/apps/go-sdk/options.go
+++ b/apps/go-sdk/options.go
@@ -195,6 +195,48 @@ type AgentOptions struct {
Effort *string `json:"effort,omitempty"`
Webhook *WebhookConfig `json:"webhook,omitempty"`
AuditMetadata *AuditMetadata `json:"auditMetadata,omitempty"`
+ // ThreadID continues an existing thread as its next turn. Nil starts a new
+ // thread.
+ ThreadID *string `json:"threadId,omitempty"`
+ // Mode is "extract" or "chat".
+ Mode *string `json:"mode,omitempty"`
+ // Exchange lets the agent call Exchange data providers. Nil on a follow-up
+ // turn inherits the previous turn's settings.
+ Exchange *AgentExchangeOptions `json:"exchange,omitempty"`
+}
+
+// AgentExchangeOptions configures Exchange for an agent run. Every field is
+// optional and the server owns the defaults.
+type AgentExchangeOptions struct {
+ Enabled *bool `json:"enabled,omitempty"`
+ // Toolkits pins up to 5 provider slugs. An empty list means every provider
+ // the team can use; nil inherits the previous turn's pin.
+ Toolkits *[]string `json:"toolkits,omitempty"`
+ MaxCalls *int `json:"maxCalls,omitempty"`
+ // RequireApproval ends the turn with a PendingApproval before a paid
+ // provider call. It needs Mode "chat" on the same request.
+ RequireApproval *bool `json:"requireApproval,omitempty"`
+ // Approve and Decline answer the previous turn's PendingApproval, so they
+ // need ThreadID.
+ Approve *AgentExchangeApprove `json:"approve,omitempty"`
+ Decline *AgentExchangeDecline `json:"decline,omitempty"`
+ // OnTermsRequired is "skip" or "ask".
+ OnTermsRequired *string `json:"onTermsRequired,omitempty"`
+}
+
+// AgentExchangeApprove approves a pending approval. CallIDs and Always are
+// ignored on a terms approval.
+type AgentExchangeApprove struct {
+ ApprovalID string `json:"approvalId"`
+ // CallIDs approves a subset of the pending calls. Nil approves all of
+ // them; an empty list approves none.
+ CallIDs *[]string `json:"callIds,omitempty"`
+ Always *bool `json:"always,omitempty"`
+}
+
+// AgentExchangeDecline declines a pending approval.
+type AgentExchangeDecline struct {
+ ApprovalID string `json:"approvalId"`
}
// AuditMetadata identifies the user associated with a SIEM logging event.
diff --git a/apps/go-sdk/version.go b/apps/go-sdk/version.go
index e52a216c4..658df228e 100644
--- a/apps/go-sdk/version.go
+++ b/apps/go-sdk/version.go
@@ -9,4 +9,4 @@ package firecrawl
// Bump this when preparing a new release. The publish-go-sdk GitHub workflow
// reads this value and creates the corresponding monorepo-prefixed tag on
// merge to main.
-const Version = "1.16.2"
+const Version = "1.16.3"