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(php-sdk): add agent exchange options, threadId and mode (#4989)
Gergő Móricz36f31d905576
diff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.mdindex 87e286058..19f133b6b 100644--- a/apps/php-sdk/CHANGELOG.md+++ b/apps/php-sdk/CHANGELOG.md@@ -5,6 +5,17 @@ All notable changes to the Firecrawl PHP SDK will be documented in this file.The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).+## [1.16.2] - 2026-10-06++### Added+- `exchange` option on `AgentOptions` (`AgentExchangeOptions`, with+ `AgentExchangeApproval` and `AgentExchangeDecline` for answering a pending+ approval) so agent runs can use Exchange data providers, plus `threadId` and+ `mode` to continue a thread in extract or chat mode. Unset fields are not sent.+- `AgentResponse::getThreadId()`/`getThreadTurn()`, and thread ID, turn, mode,+ chat `message`, `pendingApproval` and the `exchange` run summary on+ `AgentStatusResponse`.+## [1.16.1] - 2026-10-02### Addeddiff --git a/apps/php-sdk/README.md b/apps/php-sdk/README.mdindex 714116f37..0dc28ee7b 100644--- a/apps/php-sdk/README.md+++ b/apps/php-sdk/README.md@@ -255,6 +255,21 @@ $result = $client->agent(AgentOptions::with(echo $result->getData();```+To let the agent use Exchange data providers connected to your team, pass+`exchange`. Omit `toolkits` to allow every provider the team can use.++```php+use Firecrawl\Models\AgentExchangeOptions;++$result = $client->agent(AgentOptions::with(+ prompt: 'Find the company behind example.com and its funding history',+ exchange: AgentExchangeOptions::with(+ enabled: true,+ toolkits: ['provider-slug'],+ ),+));+```+### Browser Sessions```phpdiff --git a/apps/php-sdk/src/Models/AgentExchangeApproval.php b/apps/php-sdk/src/Models/AgentExchangeApproval.phpnew file mode 100644index 000000000..81fe8aa9f--- /dev/null+++ b/apps/php-sdk/src/Models/AgentExchangeApproval.php@@ -0,0 +1,36 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/**+ * Approves the previous turn's pending approval. Only meaningful with a+ * thread ID. A "terms" approval is approved as a whole, so callIds and always+ * are ignored on it.+ */+final class AgentExchangeApproval+{+ /** @param list<string>|null $callIds */+ private function __construct(+ private readonly string $approvalId,+ private readonly ?array $callIds = null,+ private readonly ?bool $always = null,+ ) {}++ /** @param list<string>|null $callIds Omitted approves every pending call. */+ public static function with(string $approvalId, ?array $callIds = null, ?bool $always = null): self+ {+ return new self($approvalId, $callIds, $always);+ }++ /** @return array<string, mixed> */+ public function toArray(): array+ {+ return array_filter([+ 'approvalId' => $this->approvalId,+ 'callIds' => $this->callIds,+ 'always' => $this->always,+ ], fn (mixed $v): bool => $v !== null);+ }+}diff --git a/apps/php-sdk/src/Models/AgentExchangeDecline.php b/apps/php-sdk/src/Models/AgentExchangeDecline.phpnew file mode 100644index 000000000..1c2b27b11--- /dev/null+++ b/apps/php-sdk/src/Models/AgentExchangeDecline.php@@ -0,0 +1,24 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/** Declines the previous turn's pending approval. Only meaningful with a thread ID. */+final class AgentExchangeDecline+{+ private function __construct(+ private readonly string $approvalId,+ ) {}++ public static function with(string $approvalId): self+ {+ return new self($approvalId);+ }++ /** @return array{approvalId: string} */+ public function toArray(): array+ {+ return ['approvalId' => $this->approvalId];+ }+}diff --git a/apps/php-sdk/src/Models/AgentExchangeOptions.php b/apps/php-sdk/src/Models/AgentExchangeOptions.phpnew file mode 100644index 000000000..70dc8e426--- /dev/null+++ b/apps/php-sdk/src/Models/AgentExchangeOptions.php@@ -0,0 +1,56 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/**+ * Exchange (data provider) settings for an agent run. Sent as-is; the server+ * owns every default and limit. On a follow-up turn, omitting it inherits the+ * previous turn's settings.+ */+final class AgentExchangeOptions+{+ /** @param list<string>|null $toolkits */+ private function __construct(+ private readonly ?bool $enabled = null,+ private readonly ?array $toolkits = null,+ private readonly ?int $maxCalls = null,+ private readonly ?bool $requireApproval = null,+ private readonly ?AgentExchangeApproval $approve = null,+ private readonly ?AgentExchangeDecline $decline = null,+ private readonly ?string $onTermsRequired = null,+ ) {}++ /**+ * @param list<string>|null $toolkits Provider slugs to pin. Omitted or+ * empty means every provider the team can use.+ * @param bool|null $requireApproval Needs mode "chat" on the request.+ * @param string|null $onTermsRequired "skip" or "ask".+ */+ public static function with(+ ?bool $enabled = null,+ ?array $toolkits = null,+ ?int $maxCalls = null,+ ?bool $requireApproval = null,+ ?AgentExchangeApproval $approve = null,+ ?AgentExchangeDecline $decline = null,+ ?string $onTermsRequired = null,+ ): self {+ return new self($enabled, $toolkits, $maxCalls, $requireApproval, $approve, $decline, $onTermsRequired);+ }++ /** @return array<string, mixed> */+ public function toArray(): array+ {+ return array_filter([+ 'enabled' => $this->enabled,+ 'toolkits' => $this->toolkits,+ 'maxCalls' => $this->maxCalls,+ 'requireApproval' => $this->requireApproval,+ 'approve' => $this->approve?->toArray(),+ 'decline' => $this->decline?->toArray(),+ 'onTermsRequired' => $this->onTermsRequired,+ ], fn (mixed $v): bool => $v !== null);+ }+}diff --git a/apps/php-sdk/src/Models/AgentExchangeSummary.php b/apps/php-sdk/src/Models/AgentExchangeSummary.phpnew file mode 100644index 000000000..77e0ccbea--- /dev/null+++ b/apps/php-sdk/src/Models/AgentExchangeSummary.php@@ -0,0 +1,104 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/**+ * What an agent run did with Exchange. toolkits and requireApproval are what+ * the run resolved to after thread inheritance, not what the request sent.+ */+final class AgentExchangeSummary+{+ /**+ * @param list<string> $toolkits+ * @param list<AgentSkippedProvider> $skippedProviders+ */+ public function __construct(+ private readonly bool $enabled = false,+ private readonly array $toolkits = [],+ private readonly ?bool $requireApproval = null,+ private readonly ?string $onTermsRequired = null,+ private readonly int $paidCalls = 0,+ private readonly ?int $creditsUsed = null,+ private readonly array $skippedProviders = [],+ private readonly ?AgentTermsRequiredAction $requiresAction = null,+ ) {}++ /** @param array<string, mixed> $data */+ public static function fromArray(array $data): self+ {+ $skippedProviders = [];+ if (isset($data['skippedProviders']) && is_array($data['skippedProviders'])) {+ foreach ($data['skippedProviders'] as $provider) {+ if (is_array($provider)) {+ $skippedProviders[] = AgentSkippedProvider::fromArray($provider);+ }+ }+ }++ return new self(+ enabled: ($data['enabled'] ?? false) === true,+ toolkits: isset($data['toolkits']) && is_array($data['toolkits'])+ ? array_values($data['toolkits'])+ : [],+ requireApproval: is_bool($data['requireApproval'] ?? null) ? $data['requireApproval'] : null,+ onTermsRequired: $data['onTermsRequired'] ?? null,+ paidCalls: (int) ($data['paidCalls'] ?? 0),+ creditsUsed: isset($data['creditsUsed']) ? (int) $data['creditsUsed'] : null,+ skippedProviders: $skippedProviders,+ requiresAction: isset($data['requiresAction']) && is_array($data['requiresAction'])+ ? AgentTermsRequiredAction::fromArray($data['requiresAction'])+ : null,+ );+ }++ public function isEnabled(): bool+ {+ return $this->enabled;+ }++ /** @return list<string> */+ public function getToolkits(): array+ {+ return $this->toolkits;+ }++ public function getRequireApproval(): ?bool+ {+ return $this->requireApproval;+ }++ /** "skip" or "ask". Null until terms gating is on for the thread. */+ public function getOnTermsRequired(): ?string+ {+ return $this->onTermsRequired;+ }++ public function getPaidCalls(): int+ {+ return $this->paidCalls;+ }++ public function getCreditsUsed(): ?int+ {+ return $this->creditsUsed;+ }++ /**+ * Providers that would have helped but were not used because their data+ * terms are not accepted.+ *+ * @return list<AgentSkippedProvider>+ */+ public function getSkippedProviders(): array+ {+ return $this->skippedProviders;+ }++ /** Set in "ask" mode when a terms offer ended the turn. */+ public function getRequiresAction(): ?AgentTermsRequiredAction+ {+ return $this->requiresAction;+ }+}diff --git a/apps/php-sdk/src/Models/AgentOptions.php b/apps/php-sdk/src/Models/AgentOptions.phpindex 13a336cfe..0378f4d5c 100644--- a/apps/php-sdk/src/Models/AgentOptions.php+++ b/apps/php-sdk/src/Models/AgentOptions.php@@ -12,6 +12,9 @@ final class AgentOptions* @param string|null $effort Reasoning budget: "low", "medium",* or "high". Every level runs spark-2.* @param AuditMetadata|null $auditMetadata+ * @param string|null $threadId Continue this thread as its next+ * turn. Omitted starts a new thread.+ * @param string|null $mode "extract" or "chat".*/private function __construct(private readonly ?array $urls = null,@@ -24,6 +27,9 @@ final class AgentOptionsprivate readonly ?string $effort = null,private readonly ?WebhookConfig $webhook = null,private readonly ?AuditMetadata $auditMetadata = null,+ private readonly ?string $threadId = null,+ private readonly ?string $mode = null,+ private readonly ?AgentExchangeOptions $exchange = null,) {}/**@@ -32,6 +38,9 @@ final class AgentOptions* @param string|null $effort Reasoning budget: "low", "medium",* or "high". Every level runs spark-2.* @param AuditMetadata|null $auditMetadata+ * @param string|null $threadId Continue this thread as its next+ * turn. Omitted starts a new thread.+ * @param string|null $mode "extract" or "chat".*/public static function with(?array $urls = null,@@ -44,10 +53,14 @@ final class AgentOptions?string $effort = null,?WebhookConfig $webhook = null,?AuditMetadata $auditMetadata = null,+ ?string $threadId = null,+ ?string $mode = null,+ ?AgentExchangeOptions $exchange = null,): self {return new self($urls, $prompt, $schema, $integration,$maxCredits, $strictConstrainToURLs, $model, $effort, $webhook, $auditMetadata,+ $threadId, $mode, $exchange,);}@@ -65,6 +78,10 @@ final class AgentOptions'effort' => $this->effort,'webhook' => $this->webhook?->toArray(),'auditMetadata' => $this->auditMetadata?->toArray(),+ 'threadId' => $this->threadId,+ 'mode' => $this->mode,+ // An empty exchange still turns Exchange on, so it must encode as {} rather than [].+ 'exchange' => $this->exchange === null ? null : (object) $this->exchange->toArray(),];return array_filter($fields, fn (mixed $v): bool => $v !== null);diff --git a/apps/php-sdk/src/Models/AgentPendingApproval.php b/apps/php-sdk/src/Models/AgentPendingApproval.phpnew file mode 100644index 000000000..2b5aa6f28--- /dev/null+++ b/apps/php-sdk/src/Models/AgentPendingApproval.php@@ -0,0 +1,95 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/**+ * A turn that ended waiting for the caller. Kind "calls" holds paid calls to+ * approve or decline; kind "terms" lists providers whose data terms need+ * accepting, and its calls are always empty.+ */+final class AgentPendingApproval+{+ /**+ * @param list<AgentPendingApprovalCall> $calls+ * @param list<AgentTermsGate> $terms+ */+ public function __construct(+ private readonly ?string $id = null,+ private readonly string $kind = 'calls',+ private readonly ?string $reason = null,+ private readonly array $calls = [],+ private readonly array $terms = [],+ private readonly ?AgentPendingApprovalResolution $resolution = null,+ ) {}++ /** @param array<string, mixed> $data */+ public static function fromArray(array $data): self+ {+ $calls = [];+ if (isset($data['calls']) && is_array($data['calls'])) {+ foreach ($data['calls'] as $call) {+ if (is_array($call)) {+ $calls[] = AgentPendingApprovalCall::fromArray($call);+ }+ }+ }++ $terms = [];+ if (isset($data['terms']) && is_array($data['terms'])) {+ foreach ($data['terms'] as $gate) {+ if (is_array($gate)) {+ $terms[] = AgentTermsGate::fromArray($gate);+ }+ }+ }++ return new self(+ id: $data['id'] ?? null,+ // Approvals written before terms offers existed carry no kind.+ kind: $data['kind'] ?? 'calls',+ reason: $data['reason'] ?? null,+ calls: $calls,+ terms: $terms,+ resolution: isset($data['resolution']) && is_array($data['resolution'])+ ? AgentPendingApprovalResolution::fromArray($data['resolution'])+ : null,+ );+ }++ /** Pass this as the approvalId to approve or decline on the next turn. */+ public function getId(): ?string+ {+ return $this->id;+ }++ /** "calls" or "terms". */+ public function getKind(): string+ {+ return $this->kind;+ }++ public function getReason(): ?string+ {+ return $this->reason;+ }++ /** @return list<AgentPendingApprovalCall> */+ public function getCalls(): array+ {+ return $this->calls;+ }++ /** @return list<AgentTermsGate> */+ public function getTerms(): array+ {+ return $this->terms;+ }++ /** Null until a later turn approves or declines it. */+ public function getResolution(): ?AgentPendingApprovalResolution+ {+ return $this->resolution;+ }+}diff --git a/apps/php-sdk/src/Models/AgentPendingApprovalCall.php b/apps/php-sdk/src/Models/AgentPendingApprovalCall.phpnew file mode 100644index 000000000..56a58c3a6--- /dev/null+++ b/apps/php-sdk/src/Models/AgentPendingApprovalCall.php@@ -0,0 +1,75 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/** A paid call held back by a pending approval. */+final class AgentPendingApprovalCall+{+ /**+ * @param array<string, mixed> $input+ * @param list<array<string, mixed>> $more+ */+ public function __construct(+ private readonly ?string $id = null,+ private readonly ?string $provider = null,+ private readonly ?string $capability = null,+ private readonly array $input = [],+ private readonly array $more = [],+ private readonly ?int $creditsEstimate = null,+ ) {}++ /** @param array<string, mixed> $data */+ public static function fromArray(array $data): self+ {+ return new self(+ id: $data['id'] ?? null,+ provider: $data['provider'] ?? null,+ capability: $data['capability'] ?? null,+ input: isset($data['input']) && is_array($data['input']) ? $data['input'] : [],+ more: isset($data['more']) && is_array($data['more'])+ ? array_values(array_filter($data['more'], 'is_array'))+ : [],+ creditsEstimate: isset($data['creditsEstimate']) ? (int) $data['creditsEstimate'] : null,+ );+ }++ /** Pass in the approval's callIds to approve only some calls. */+ public function getId(): ?string+ {+ return $this->id;+ }++ public function getProvider(): ?string+ {+ return $this->provider;+ }++ public function getCapability(): ?string+ {+ return $this->capability;+ }++ /** @return array<string, mixed> */+ public function getInput(): array+ {+ return $this->input;+ }++ /**+ * Further inputs batched into this call. creditsEstimate covers them too.+ *+ * @return list<array<string, mixed>>+ */+ public function getMore(): array+ {+ return $this->more;+ }++ /** Null when the provider lists no per-call price. */+ public function getCreditsEstimate(): ?int+ {+ return $this->creditsEstimate;+ }+}diff --git a/apps/php-sdk/src/Models/AgentPendingApprovalResolution.php b/apps/php-sdk/src/Models/AgentPendingApprovalResolution.phpnew file mode 100644index 000000000..b24e30936--- /dev/null+++ b/apps/php-sdk/src/Models/AgentPendingApprovalResolution.php@@ -0,0 +1,56 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/** How a later turn answered a pending approval. */+final class AgentPendingApprovalResolution+{+ /** @param list<string> $callIds */+ public function __construct(+ private readonly bool $approved = false,+ private readonly array $callIds = [],+ private readonly bool $always = false,+ private readonly ?string $byRunId = null,+ ) {}++ /** @param array<string, mixed> $data */+ public static function fromArray(array $data): self+ {+ return new self(+ approved: ($data['approved'] ?? false) === true,+ callIds: isset($data['callIds']) && is_array($data['callIds'])+ ? array_values($data['callIds'])+ : [],+ always: ($data['always'] ?? false) === true,+ byRunId: $data['byRunId'] ?? null,+ );+ }++ public function isApproved(): bool+ {+ return $this->approved;+ }++ /**+ * The calls approved. Empty on terms approvals.+ *+ * @return list<string>+ */+ public function getCallIds(): array+ {+ return $this->callIds;+ }++ public function isAlways(): bool+ {+ return $this->always;+ }++ /** The run that answered the approval. */+ public function getByRunId(): ?string+ {+ return $this->byRunId;+ }+}diff --git a/apps/php-sdk/src/Models/AgentResponse.php b/apps/php-sdk/src/Models/AgentResponse.phpindex 865f48bf1..82b5afc5b 100644--- a/apps/php-sdk/src/Models/AgentResponse.php+++ b/apps/php-sdk/src/Models/AgentResponse.php@@ -10,6 +10,8 @@ final class AgentResponseprivate readonly bool $success = false,private readonly ?string $id = null,private readonly ?string $error = null,+ private readonly ?string $threadId = null,+ private readonly ?int $threadTurn = null,) {}/** @param array<string, mixed> $data */@@ -19,6 +21,8 @@ final class AgentResponsesuccess: (bool) ($data['success'] ?? false),id: $data['id'] ?? null,error: $data['error'] ?? null,+ threadId: $data['threadId'] ?? null,+ threadTurn: isset($data['threadTurn']) ? (int) $data['threadTurn'] : null,);}@@ -36,4 +40,16 @@ final class AgentResponse{return $this->error;}++ /** The thread this run belongs to. Pass it back as threadId to continue it. */+ public function getThreadId(): ?string+ {+ return $this->threadId;+ }++ /** 1-based position of this run in its thread. */+ public function getThreadTurn(): ?int+ {+ return $this->threadTurn;+ }}diff --git a/apps/php-sdk/src/Models/AgentSkippedProvider.php b/apps/php-sdk/src/Models/AgentSkippedProvider.phpnew file mode 100644index 000000000..d40977a49--- /dev/null+++ b/apps/php-sdk/src/Models/AgentSkippedProvider.php@@ -0,0 +1,72 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/** A provider the run would have used but skipped because its data terms are not accepted. */+final class AgentSkippedProvider+{+ public function __construct(+ private readonly ?string $provider = null,+ private readonly ?string $name = null,+ private readonly ?string $capability = null,+ private readonly ?string $adds = null,+ private readonly ?string $reason = null,+ private readonly ?string $version = null,+ private readonly ?string $termsUrl = null,+ ) {}++ /** @param array<string, mixed> $data */+ public static function fromArray(array $data): self+ {+ return new self(+ provider: $data['provider'] ?? null,+ name: $data['name'] ?? null,+ capability: $data['capability'] ?? null,+ adds: $data['adds'] ?? null,+ reason: $data['reason'] ?? null,+ version: $data['version'] ?? null,+ termsUrl: $data['termsUrl'] ?? null,+ );+ }++ public function getProvider(): ?string+ {+ return $this->provider;+ }++ public function getName(): ?string+ {+ return $this->name;+ }++ public function getCapability(): ?string+ {+ return $this->capability;+ }++ /** What the provider would have added, in the agent's words. */+ public function getAdds(): ?string+ {+ return $this->adds;+ }++ /** "terms_required". */+ public function getReason(): ?string+ {+ return $this->reason;+ }++ /** The version of the terms that gate the provider. */+ public function getVersion(): ?string+ {+ return $this->version;+ }++ /** Where a person accepts the terms in the dashboard. */+ public function getTermsUrl(): ?string+ {+ return $this->termsUrl;+ }+}diff --git a/apps/php-sdk/src/Models/AgentStatusResponse.php b/apps/php-sdk/src/Models/AgentStatusResponse.phpindex 0209a3714..8bff1529d 100644--- a/apps/php-sdk/src/Models/AgentStatusResponse.php+++ b/apps/php-sdk/src/Models/AgentStatusResponse.php@@ -15,6 +15,12 @@ final class AgentStatusResponseprivate readonly ?string $effort = null,private readonly ?string $expiresAt = null,private readonly ?int $creditsUsed = null,+ private readonly ?string $threadId = null,+ private readonly ?int $threadTurn = null,+ private readonly ?string $mode = null,+ private readonly ?string $message = null,+ private readonly ?AgentPendingApproval $pendingApproval = null,+ private readonly ?AgentExchangeSummary $exchange = null,) {}/** @param array<string, mixed> $raw */@@ -29,6 +35,16 @@ final class AgentStatusResponseeffort: $raw['effort'] ?? null,expiresAt: $raw['expiresAt'] ?? null,creditsUsed: isset($raw['creditsUsed']) ? (int) $raw['creditsUsed'] : null,+ threadId: $raw['threadId'] ?? null,+ threadTurn: isset($raw['threadTurn']) ? (int) $raw['threadTurn'] : null,+ mode: $raw['mode'] ?? null,+ message: $raw['message'] ?? null,+ pendingApproval: isset($raw['pendingApproval']) && is_array($raw['pendingApproval'])+ ? AgentPendingApproval::fromArray($raw['pendingApproval'])+ : null,+ exchange: isset($raw['exchange']) && is_array($raw['exchange'])+ ? AgentExchangeSummary::fromArray($raw['exchange'])+ : null,);}@@ -80,4 +96,38 @@ final class AgentStatusResponse{return $this->creditsUsed;}++ public function getThreadId(): ?string+ {+ return $this->threadId;+ }++ public function getThreadTurn(): ?int+ {+ return $this->threadTurn;+ }++ /** "extract" or "chat". */+ public function getMode(): ?string+ {+ return $this->mode;+ }++ /** The text reply of a chat-mode run, which answers here instead of in data. */+ public function getMessage(): ?string+ {+ return $this->message;+ }++ /** Set when the turn ended waiting for the caller to approve or decline. */+ public function getPendingApproval(): ?AgentPendingApproval+ {+ return $this->pendingApproval;+ }++ /** What the run did with Exchange. */+ public function getExchange(): ?AgentExchangeSummary+ {+ return $this->exchange;+ }}diff --git a/apps/php-sdk/src/Models/AgentTermsActionProvider.php b/apps/php-sdk/src/Models/AgentTermsActionProvider.phpnew file mode 100644index 000000000..b291a50c2--- /dev/null+++ b/apps/php-sdk/src/Models/AgentTermsActionProvider.php@@ -0,0 +1,100 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/** A provider whose data terms the caller can view and accept. */+final class AgentTermsActionProvider+{+ /**+ * @param array<string, mixed>|null $show+ * @param array<string, mixed>|null $accept+ */+ public function __construct(+ private readonly ?string $provider = null,+ private readonly ?string $name = null,+ private readonly ?string $capability = null,+ private readonly ?string $adds = null,+ private readonly ?string $version = null,+ private readonly ?string $digest = null,+ private readonly ?string $url = null,+ private readonly ?array $show = null,+ private readonly ?array $accept = null,+ ) {}++ /** @param array<string, mixed> $data */+ public static function fromArray(array $data): self+ {+ return new self(+ provider: $data['provider'] ?? null,+ name: $data['name'] ?? null,+ capability: $data['capability'] ?? null,+ adds: $data['adds'] ?? null,+ version: $data['version'] ?? null,+ digest: $data['digest'] ?? null,+ url: $data['url'] ?? null,+ show: isset($data['show']) && is_array($data['show']) ? $data['show'] : null,+ accept: isset($data['accept']) && is_array($data['accept']) ? $data['accept'] : null,+ );+ }++ public function getProvider(): ?string+ {+ return $this->provider;+ }++ public function getName(): ?string+ {+ return $this->name;+ }++ public function getCapability(): ?string+ {+ return $this->capability;+ }++ /** What the provider would add, in the agent's words. */+ public function getAdds(): ?string+ {+ return $this->adds;+ }++ public function getVersion(): ?string+ {+ return $this->version;+ }++ /** Null when the catalog published no digest; terms/show returns it. */+ public function getDigest(): ?string+ {+ return $this->digest;+ }++ /** Where a person accepts the terms in the dashboard. */+ public function getUrl(): ?string+ {+ return $this->url;+ }++ /**+ * The terms/show call: {provider, capability, options}.+ *+ * @return array<string, mixed>|null+ */+ public function getShow(): ?array+ {+ return $this->show;+ }++ /**+ * The terms/accept call: {provider, capability, options}. Make it only+ * after the user has explicitly agreed to the terms.+ *+ * @return array<string, mixed>|null+ */+ public function getAccept(): ?array+ {+ return $this->accept;+ }+}diff --git a/apps/php-sdk/src/Models/AgentTermsGate.php b/apps/php-sdk/src/Models/AgentTermsGate.phpnew file mode 100644index 000000000..426768ced--- /dev/null+++ b/apps/php-sdk/src/Models/AgentTermsGate.php@@ -0,0 +1,78 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/** A provider listed in a "terms" pending approval. */+final class AgentTermsGate+{+ public function __construct(+ private readonly ?string $provider = null,+ private readonly ?string $name = null,+ private readonly ?string $logo = null,+ private readonly ?string $capability = null,+ private readonly ?string $adds = null,+ private readonly ?string $version = null,+ private readonly ?string $digest = null,+ private readonly ?string $url = null,+ ) {}++ /** @param array<string, mixed> $data */+ public static function fromArray(array $data): self+ {+ return new self(+ provider: $data['provider'] ?? null,+ name: $data['name'] ?? null,+ logo: $data['logo'] ?? null,+ capability: $data['capability'] ?? null,+ adds: $data['adds'] ?? null,+ version: $data['version'] ?? null,+ digest: $data['digest'] ?? null,+ url: $data['url'] ?? null,+ );+ }++ public function getProvider(): ?string+ {+ return $this->provider;+ }++ public function getName(): ?string+ {+ return $this->name;+ }++ public function getLogo(): ?string+ {+ return $this->logo;+ }++ public function getCapability(): ?string+ {+ return $this->capability;+ }++ /** What the provider would add, in the agent's words. */+ public function getAdds(): ?string+ {+ return $this->adds;+ }++ public function getVersion(): ?string+ {+ return $this->version;+ }++ /** Null when the catalog published no digest; terms/show returns it. */+ public function getDigest(): ?string+ {+ return $this->digest;+ }++ /** Where a person accepts the terms in the dashboard. */+ public function getUrl(): ?string+ {+ return $this->url;+ }+}diff --git a/apps/php-sdk/src/Models/AgentTermsRequiredAction.php b/apps/php-sdk/src/Models/AgentTermsRequiredAction.phpnew file mode 100644index 000000000..cfe482604--- /dev/null+++ b/apps/php-sdk/src/Models/AgentTermsRequiredAction.php@@ -0,0 +1,57 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++/**+ * The Exchange calls to view and accept providers' data terms. Nothing here is+ * run for you: call terms/accept only after the user has explicitly agreed,+ * then continue the thread approving approvalId, or decline it.+ */+final class AgentTermsRequiredAction+{+ /** @param list<AgentTermsActionProvider> $providers */+ public function __construct(+ private readonly ?string $type = null,+ private readonly ?string $approvalId = null,+ private readonly array $providers = [],+ ) {}++ /** @param array<string, mixed> $data */+ public static function fromArray(array $data): self+ {+ $providers = [];+ if (isset($data['providers']) && is_array($data['providers'])) {+ foreach ($data['providers'] as $provider) {+ if (is_array($provider)) {+ $providers[] = AgentTermsActionProvider::fromArray($provider);+ }+ }+ }++ return new self(+ type: $data['type'] ?? null,+ approvalId: $data['approvalId'] ?? null,+ providers: $providers,+ );+ }++ /** "accept_terms". */+ public function getType(): ?string+ {+ return $this->type;+ }++ /** The ID of the "terms" pending approval that answers this. */+ public function getApprovalId(): ?string+ {+ return $this->approvalId;+ }++ /** @return list<AgentTermsActionProvider> */+ public function getProviders(): array+ {+ return $this->providers;+ }+}diff --git a/apps/php-sdk/src/Version.php b/apps/php-sdk/src/Version.phpindex 8732d8c01..8ff31edbf 100644--- a/apps/php-sdk/src/Version.php+++ b/apps/php-sdk/src/Version.php@@ -6,5 +6,5 @@ namespace Firecrawl;final class Version{- public const SDK_VERSION = '1.16.1';+ public const SDK_VERSION = '1.16.2';}diff --git a/apps/php-sdk/tests/Unit/AgentExchangeTest.php b/apps/php-sdk/tests/Unit/AgentExchangeTest.phpnew file mode 100644index 000000000..a95f3f5f2--- /dev/null+++ b/apps/php-sdk/tests/Unit/AgentExchangeTest.php@@ -0,0 +1,283 @@+<?php++declare(strict_types=1);++use Firecrawl\Models\AgentExchangeApproval;+use Firecrawl\Models\AgentExchangeDecline;+use Firecrawl\Models\AgentExchangeOptions;+use Firecrawl\Models\AgentOptions;+use GuzzleHttp\Psr7\Response;++it('sends exchange, threadId and mode with their wire names', function (): void {+ $history = new ArrayObject();+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode([+ 'success' => true,+ 'id' => 'run-2',+ 'threadId' => '7b0c2f4e-1d7a-4c4e-9a4f-2f6d8a1b3c5d',+ 'threadTurn' => 2,+ ])),+ ], $history);++ $response = $client->startAgent(AgentOptions::with(+ prompt: 'go ahead',+ threadId: '7b0c2f4e-1d7a-4c4e-9a4f-2f6d8a1b3c5d',+ mode: 'chat',+ exchange: AgentExchangeOptions::with(+ enabled: true,+ toolkits: ['acme-data', 'globex'],+ maxCalls: 4,+ requireApproval: true,+ approve: AgentExchangeApproval::with(+ approvalId: '0f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918',+ callIds: ['call-1'],+ always: false,+ ),+ onTermsRequired: 'ask',+ ),+ ));++ $body = json_decode((string) $history[0]['request']->getBody(), true);+ expect($body['threadId'])->toBe('7b0c2f4e-1d7a-4c4e-9a4f-2f6d8a1b3c5d');+ expect($body['mode'])->toBe('chat');+ expect($body['exchange'])->toBe([+ 'enabled' => true,+ 'toolkits' => ['acme-data', 'globex'],+ 'maxCalls' => 4,+ 'requireApproval' => true,+ 'approve' => [+ 'approvalId' => '0f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918',+ 'callIds' => ['call-1'],+ 'always' => false,+ ],+ 'onTermsRequired' => 'ask',+ ]);++ expect($response->getId())->toBe('run-2');+ expect($response->getThreadId())->toBe('7b0c2f4e-1d7a-4c4e-9a4f-2f6d8a1b3c5d');+ expect($response->getThreadTurn())->toBe(2);+});++it('sends a decline through the polling agent helper', function (): void {+ $history = new ArrayObject();+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode(['success' => true, 'id' => 'run-3'])),+ new Response(200, [], json_encode(['success' => true, 'status' => 'completed'])),+ ], $history);++ $client->agent(AgentOptions::with(+ prompt: 'skip it',+ threadId: '7b0c2f4e-1d7a-4c4e-9a4f-2f6d8a1b3c5d',+ mode: 'chat',+ exchange: AgentExchangeOptions::with(+ decline: AgentExchangeDecline::with('0f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918'),+ ),+ ));++ $body = json_decode((string) $history[0]['request']->getBody(), true);+ expect($body['exchange'])->toBe([+ 'decline' => ['approvalId' => '0f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918'],+ ]);+});++it('omits unset thread and exchange options', function (): void {+ $history = new ArrayObject();+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode(['success' => true, 'id' => 'run-1'])),+ new Response(200, [], json_encode(['success' => true, 'id' => 'run-2'])),+ new Response(200, [], json_encode(['success' => true, 'id' => 'run-3'])),+ ], $history);++ $response = $client->startAgent(AgentOptions::with(prompt: 'find pricing'));+ $client->startAgent(AgentOptions::with(+ prompt: 'find pricing',+ exchange: AgentExchangeOptions::with(enabled: true, toolkits: ['acme-data']),+ ));+ $client->startAgent(AgentOptions::with(+ prompt: 'find pricing',+ exchange: AgentExchangeOptions::with(),+ ));++ $plain = json_decode((string) $history[0]['request']->getBody(), true);+ expect($plain)->not->toHaveKeys(['threadId', 'mode', 'exchange']);+ expect($response->getThreadId())->toBeNull();+ expect($response->getThreadTurn())->toBeNull();++ $partial = json_decode((string) $history[1]['request']->getBody(), true);+ expect($partial['exchange'])->toBe(['enabled' => true, 'toolkits' => ['acme-data']]);++ expect((string) $history[2]['request']->getBody())->toContain('"exchange":{}');+});++it('hydrates the exchange summary and a pending calls approval on the status response', function (): void {+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode([+ 'success' => true,+ 'status' => 'completed',+ 'threadId' => '7b0c2f4e-1d7a-4c4e-9a4f-2f6d8a1b3c5d',+ 'threadTurn' => 1,+ 'mode' => 'chat',+ 'message' => 'Two paid lookups need your approval.',+ 'suggestions' => [['label' => 'Approve', 'prompt' => 'go ahead']],+ 'notYetKnownField' => ['ignored' => true],+ 'pendingApproval' => [+ 'id' => '0f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918',+ 'kind' => 'calls',+ 'reason' => 'Paid provider calls need approval.',+ 'calls' => [[+ 'id' => 'call-1',+ 'provider' => 'acme-data',+ 'capability' => 'company/lookup',+ 'input' => ['domain' => 'example.com'],+ 'more' => [['domain' => 'example.org']],+ 'creditsEstimate' => 20,+ ]],+ 'resolution' => null,+ ],+ 'exchange' => [+ 'enabled' => true,+ 'toolkits' => ['acme-data'],+ 'requireApproval' => true,+ 'onTermsRequired' => 'ask',+ 'paidCalls' => 0,+ 'creditsUsed' => null,+ 'skippedProviders' => [[+ 'provider' => 'globex',+ 'name' => 'Globex',+ 'capability' => 'people/search',+ 'adds' => 'Contact details',+ 'reason' => 'terms_required',+ 'version' => '2026-09-01',+ 'termsUrl' => 'https://example.com/terms/globex',+ ]],+ 'requiresAction' => [+ 'type' => 'accept_terms',+ 'approvalId' => '5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a',+ 'providers' => [[+ 'provider' => 'globex',+ 'name' => 'Globex',+ 'version' => '2026-09-01',+ 'digest' => null,+ 'url' => 'https://example.com/terms/globex',+ 'show' => [+ 'provider' => 'firecrawl',+ 'capability' => 'terms/show',+ 'options' => ['provider' => 'globex'],+ ],+ 'accept' => [+ 'provider' => 'firecrawl',+ 'capability' => 'terms/accept',+ 'options' => [+ 'provider' => 'globex',+ 'version' => '2026-09-01',+ 'digest' => null,+ 'confirmed' => true,+ ],+ ],+ ]],+ ],+ ],+ ])),+ ]);++ $status = $client->getAgentStatus('run-1');++ expect($status->getThreadId())->toBe('7b0c2f4e-1d7a-4c4e-9a4f-2f6d8a1b3c5d');+ expect($status->getThreadTurn())->toBe(1);+ expect($status->getMode())->toBe('chat');+ expect($status->getMessage())->toBe('Two paid lookups need your approval.');++ $approval = $status->getPendingApproval();+ expect($approval->getId())->toBe('0f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918');+ expect($approval->getKind())->toBe('calls');+ expect($approval->getReason())->toBe('Paid provider calls need approval.');+ expect($approval->getTerms())->toBe([]);+ expect($approval->getResolution())->toBeNull();+ expect($approval->getCalls())->toHaveCount(1);++ $call = $approval->getCalls()[0];+ expect($call->getId())->toBe('call-1');+ expect($call->getProvider())->toBe('acme-data');+ expect($call->getCapability())->toBe('company/lookup');+ expect($call->getInput())->toBe(['domain' => 'example.com']);+ expect($call->getMore())->toBe([['domain' => 'example.org']]);+ expect($call->getCreditsEstimate())->toBe(20);++ $exchange = $status->getExchange();+ expect($exchange->isEnabled())->toBeTrue();+ expect($exchange->getToolkits())->toBe(['acme-data']);+ expect($exchange->getRequireApproval())->toBeTrue();+ expect($exchange->getOnTermsRequired())->toBe('ask');+ expect($exchange->getPaidCalls())->toBe(0);+ expect($exchange->getCreditsUsed())->toBeNull();++ $skipped = $exchange->getSkippedProviders();+ expect($skipped)->toHaveCount(1);+ expect($skipped[0]->getProvider())->toBe('globex');+ expect($skipped[0]->getName())->toBe('Globex');+ expect($skipped[0]->getCapability())->toBe('people/search');+ expect($skipped[0]->getAdds())->toBe('Contact details');+ expect($skipped[0]->getReason())->toBe('terms_required');+ expect($skipped[0]->getVersion())->toBe('2026-09-01');+ expect($skipped[0]->getTermsUrl())->toBe('https://example.com/terms/globex');++ $action = $exchange->getRequiresAction();+ expect($action->getType())->toBe('accept_terms');+ expect($action->getApprovalId())->toBe('5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a');+ expect($action->getProviders())->toHaveCount(1);++ $provider = $action->getProviders()[0];+ expect($provider->getProvider())->toBe('globex');+ expect($provider->getVersion())->toBe('2026-09-01');+ expect($provider->getDigest())->toBeNull();+ expect($provider->getUrl())->toBe('https://example.com/terms/globex');+ expect($provider->getShow()['capability'])->toBe('terms/show');+ expect($provider->getAccept()['options'])->toBe([+ 'provider' => 'globex',+ 'version' => '2026-09-01',+ 'digest' => null,+ 'confirmed' => true,+ ]);+});++it('reads a pending approval without a kind as a calls approval', function (): void {+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode([+ 'success' => true,+ 'status' => 'completed',+ 'pendingApproval' => [+ 'id' => '0f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918',+ 'reason' => 'Paid provider calls need approval.',+ 'calls' => [],+ 'resolution' => [+ 'approved' => true,+ 'callIds' => ['call-1'],+ 'always' => false,+ 'byRunId' => 'run-2',+ ],+ ],+ ])),+ ]);++ $approval = $client->getAgentStatus('run-1')->getPendingApproval();++ expect($approval->getKind())->toBe('calls');+ expect($approval->getResolution()->isApproved())->toBeTrue();+ expect($approval->getResolution()->getCallIds())->toBe(['call-1']);+ expect($approval->getResolution()->isAlways())->toBeFalse();+ expect($approval->getResolution()->getByRunId())->toBe('run-2');+});++it('leaves thread and exchange fields null on a plain status response', function (): void {+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode(['success' => true, 'status' => 'processing'])),+ ]);++ $status = $client->getAgentStatus('run-1');++ expect($status->getThreadId())->toBeNull();+ expect($status->getMode())->toBeNull();+ expect($status->getMessage())->toBeNull();+ expect($status->getPendingApproval())->toBeNull();+ expect($status->getExchange())->toBeNull();+});