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(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.mdindex 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"},+ },+})```### Browserdiff --git a/apps/go-sdk/agent_test.go b/apps/go-sdk/agent_test.goindex 39257fc55..48de41877 100644--- a/apps/go-sdk/agent_test.go+++ b/apps/go-sdk/agent_test.go@@ -2,9 +2,11 @@ package firecrawlimport ("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.goindex 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.goindex 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.goindex 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"