Skip to content

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

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.md
index 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
### Added
diff --git a/apps/php-sdk/README.md b/apps/php-sdk/README.md
index 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
```php
diff --git a/apps/php-sdk/src/Models/AgentExchangeApproval.php b/apps/php-sdk/src/Models/AgentExchangeApproval.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
index 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 AgentOptions
private 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.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
index 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 AgentResponse
private 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 AgentResponse
success: (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.php
new file mode 100644
index 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.php
index 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 AgentStatusResponse
private 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 AgentStatusResponse
effort: $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.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
index 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.php
new file mode 100644
index 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();
+});