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/agent) Spark 2 threads (#4490)
Nicolas2aace7b00299
diff --git a/apps/api/src/__tests__/snips/v2/agent-thread.test.ts b/apps/api/src/__tests__/snips/v2/agent-thread.test.tsnew file mode 100644index 000000000..775315f1d--- /dev/null+++ b/apps/api/src/__tests__/snips/v2/agent-thread.test.ts@@ -0,0 +1,373 @@+import request from "supertest";+import { config } from "../../../config";+import {+ describeIf,+ HAS_AI,+ Identity,+ idmux,+ scrapeTimeout,+ TEST_API_URL,+ TEST_PRODUCTION,+ TEST_SUITE_WEBSITE,+} from "../lib";++// A thread turn drives a browser and a model, so the cases that run one need+// fire-engine and AI. AGENTS.md gates fire-engine tests on+// !TEST_SUITE_SELF_HOSTED, and AI tests on !TEST_SUITE_SELF_HOSTED ||+// OPENAI_API_KEY || OLLAMA_BASE_URL. Every case that touches a thread also+// reaches the agent beta service, so that URL must be configured too.+const REQUIRES_FIRE_ENGINE = TEST_PRODUCTION;+const REQUIRES_AI = TEST_PRODUCTION || HAS_AI;+const HAS_AGENT_BETA = !!config.EXTRACT_V3_BETA_URL;++// A turn has to reach a terminal status before the next one is accepted, which+// takes several scrape budgets rather than one.+const TURN_TIMEOUT = scrapeTimeout * 6;++let identity: Identity;+let otherIdentity: Identity;++beforeAll(async () => {+ [identity, otherIdentity] = await Promise.all([+ idmux({ name: "agent-thread", credits: 1000000 }),+ idmux({ name: "agent-thread-other", credits: 1000000 }),+ ]);+}, scrapeTimeout);++const agentRaw = (body: Record<string, unknown>, apiKey?: string) =>+ request(TEST_API_URL)+ .post("/v2/agent")+ .set("Authorization", `Bearer ${apiKey ?? identity.apiKey}`)+ .set("Content-Type", "application/json")+ .send(body);++const statusOf = (jobId: string, apiKey?: string) =>+ request(TEST_API_URL)+ .get(`/v2/agent/${jobId}`)+ .set("Authorization", `Bearer ${apiKey ?? identity.apiKey}`);++const traceOf = (jobId: string) =>+ request(TEST_API_URL)+ .get(`/v2/agent/${jobId}/trace`)+ .set("Authorization", `Bearer ${identity.apiKey}`);++const threadOf = (+ threadId: string,+ options: { apiKey?: string; includeData?: boolean } = {},+) =>+ request(TEST_API_URL)+ .get(+ `/v2/agent/threads/${threadId}` ++ (options.includeData ? "?includeData=true" : ""),+ )+ .set("Authorization", `Bearer ${options.apiKey ?? identity.apiKey}`);++const cancel = (jobId: string) =>+ request(TEST_API_URL)+ .delete(`/v2/agent/${jobId}`)+ .set("Authorization", `Bearer ${identity.apiKey}`);++const listAgentIds = async () => {+ const response = await request(TEST_API_URL)+ .get("/v2/agent")+ .set("Authorization", `Bearer ${identity.apiKey}`);++ expect(response.statusCode).toBe(200);+ return ((response.body.agents ?? []) as { id: string }[]).map(a => a.id);+};++async function waitForTerminal(jobId: string) {+ const deadline = Date.now() + TURN_TIMEOUT - scrapeTimeout;++ while (Date.now() < deadline) {+ const status = await statusOf(jobId);+ expect(status.statusCode).toBe(200);+ if (status.body.status !== "processing") return status.body;+ await new Promise(resolve => setTimeout(resolve, 2000));+ }++ throw new Error(`Agent run ${jobId} did not reach a terminal status`);+}++async function startTurn(body: Record<string, unknown>) {+ const response = await agentRaw(body);++ if (response.statusCode !== 200) {+ console.warn(+ "Agent thread turn did not start",+ JSON.stringify(response.body, null, 2),+ );+ }++ expect(response.statusCode).toBe(200);+ expect(response.body.success).toBe(true);+ expect(typeof response.body.id).toBe("string");+ expect(typeof response.body.threadId).toBe("string");+ return response.body as { id: string; threadId: string; threadTurn?: number };+}++// agentRequestSchema.parse runs at the top of agentController, before the+// controller touches the agent service, a browser or a model, so these cases+// run everywhere instead of skipping with the live turns below.+describe("Agent thread parameter validation", () => {+ it(+ "rejects a threadId that is not a UUID",+ async () => {+ const response = await agentRaw({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "What does this page offer?",+ threadId: "not-a-uuid",+ });++ expect(response.statusCode).toBe(400);+ expect(response.body.success).toBe(false);+ },+ scrapeTimeout,+ );++ it(+ "rejects an unknown mode",+ async () => {+ const response = await agentRaw({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "What does this page offer?",+ mode: "argue",+ });++ expect(response.statusCode).toBe(400);+ expect(response.body.success).toBe(false);+ },+ scrapeTimeout,+ );+});++describeIf(HAS_AGENT_BETA)("Agent thread rejections", () => {+ it(+ "rejects an unknown threadId without creating a request",+ async () => {+ const before = await listAgentIds();++ const response = await agentRaw({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "What does this page offer?",+ threadId: crypto.randomUUID(),+ });++ expect(response.statusCode).toBe(404);+ expect(response.body.success).toBe(false);+ expect(response.body.code).toBe("thread_not_found");++ expect(await listAgentIds()).toEqual(before);+ },+ scrapeTimeout,+ );++ it(+ "reports an unknown thread as not found",+ async () => {+ const response = await threadOf(crypto.randomUUID());++ expect(response.statusCode).toBe(404);+ expect(response.body.success).toBe(false);+ expect(response.body.code).toBe("thread_not_found");+ },+ scrapeTimeout,+ );+});++describeIf(REQUIRES_FIRE_ENGINE && REQUIRES_AI && HAS_AGENT_BETA)(+ "Agent threads",+ () => {+ it(+ "continues an extract thread across two turns",+ async () => {+ const first = await startTurn({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "Extract the page title.",+ effort: "low",+ schema: {+ type: "object",+ properties: { title: { type: "string" } },+ required: ["title"],+ },+ });++ expect(first.threadTurn).toBe(1);+ const firstStatus = await waitForTerminal(first.id);+ expect(firstStatus.status).toBe("completed");+ expect(firstStatus.threadId).toBe(first.threadId);++ const second = await startTurn({+ threadId: first.threadId,+ prompt: "Add the page's main heading as `heading`.",+ effort: "low",+ schema: {+ type: "object",+ properties: {+ title: { type: "string" },+ heading: { type: "string" },+ },+ required: ["title", "heading"],+ },+ });++ expect(second.threadId).toBe(first.threadId);+ expect(second.threadTurn).toBe(2);++ const secondStatus = await waitForTerminal(second.id);+ expect(secondStatus.status).toBe("completed");+ expect(secondStatus.threadTurn).toBe(2);+ expect(Object.keys(secondStatus.data)).toEqual(+ expect.arrayContaining(["title", "heading"]),+ );++ const thread = await threadOf(first.threadId, { includeData: true });+ expect(thread.statusCode).toBe(200);+ expect(thread.body.success).toBe(true);+ expect(thread.body.thread.id).toBe(first.threadId);+ expect(thread.body.thread.runs).toHaveLength(2);+ expect(+ thread.body.thread.runs.map((run: { status: string }) => run.status),+ ).toEqual(["succeeded", "succeeded"]);+ expect(+ thread.body.thread.runs.map((run: { turn: number }) => run.turn),+ ).toEqual([1, 2]);+ },+ TURN_TIMEOUT * 2,+ );++ it(+ "answers a chat-mode follow-up with a message instead of data",+ async () => {+ const first = await startTurn({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "Read this page and note what it offers.",+ mode: "chat",+ effort: "low",+ });++ await waitForTerminal(first.id);++ const second = await startTurn({+ threadId: first.threadId,+ prompt: "In one sentence, what is that page about?",+ });++ const secondStatus = await waitForTerminal(second.id);+ expect(secondStatus.status).toBe("completed");+ expect(secondStatus.mode).toBe("chat");+ expect(typeof secondStatus.message).toBe("string");+ expect(secondStatus.message.length).toBeGreaterThan(0);+ expect(secondStatus.data).toBeNull();++ const trace = await traceOf(second.id);+ expect(trace.statusCode).toBe(200);+ expect(+ (trace.body.events as { type: string }[]).some(+ event => event.type === "assistant.message",+ ),+ ).toBe(true);+ },+ TURN_TIMEOUT * 2,+ );++ it(+ "rejects a follow-up while the thread is busy",+ async () => {+ const first = await startTurn({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "Extract the page title.",+ effort: "low",+ });++ const busy = await agentRaw({+ threadId: first.threadId,+ prompt: "And the heading?",+ });++ expect(busy.statusCode).toBe(409);+ expect(busy.body.success).toBe(false);+ expect(busy.body.code).toBe("thread_busy");+ expect(busy.body.runId).toBe(first.id);++ await cancel(first.id);+ await waitForTerminal(first.id);++ const second = await agentRaw({+ threadId: first.threadId,+ prompt: "And the heading?",+ effort: "low",+ });++ expect(second.statusCode).toBe(200);+ expect(second.body.threadId).toBe(first.threadId);++ await cancel(second.body.id);+ },+ TURN_TIMEOUT * 2,+ );++ it(+ "hides a thread from another team",+ async () => {+ const first = await startTurn({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "Extract the page title.",+ effort: "low",+ });++ await cancel(first.id);+ await waitForTerminal(first.id);++ const crossTeamTurn = await agentRaw(+ {+ threadId: first.threadId,+ prompt: "And the heading?",+ },+ otherIdentity.apiKey,+ );++ expect(crossTeamTurn.statusCode).toBe(404);+ expect(crossTeamTurn.body.code).toBe("thread_not_found");++ const crossTeamRead = await threadOf(first.threadId, {+ apiKey: otherIdentity.apiKey,+ });++ expect(crossTeamRead.statusCode).toBe(404);+ expect(crossTeamRead.body.code).toBe("thread_not_found");+ },+ TURN_TIMEOUT * 2,+ );++ it(+ "keeps the plain start and status shapes intact",+ async () => {+ const response = await agentRaw({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "What does this page offer?",+ effort: "low",+ });++ expect(response.statusCode).toBe(200);+ expect(response.body.success).toBe(true);+ expect(typeof response.body.id).toBe("string");+ // The start response may only have grown by the thread fields.+ expect(+ Object.keys(response.body).filter(+ key => !["success", "id", "threadId", "threadTurn"].includes(key),+ ),+ ).toEqual([]);++ const status = await statusOf(response.body.id);+ expect(status.statusCode).toBe(200);+ expect(status.body.model).toBe("spark-2");+ expect(status.body.threadId).toBe(response.body.threadId);+ expect(status.body.message).toBeUndefined();++ await cancel(response.body.id);+ },+ scrapeTimeout,+ );+ },+);diff --git a/apps/api/src/controllers/v2/agent-status.ts b/apps/api/src/controllers/v2/agent-status.tsindex 7337a4802..77cfb532f 100644--- a/apps/api/src/controllers/v2/agent-status.ts+++ b/apps/api/src/controllers/v2/agent-status.ts@@ -1,5 +1,12 @@import { Response } from "express";-import { AgentStatusResponse, RequestWithAuth } from "./types";+import {+ AgentExchangeSummary,+ AgentMode,+ AgentPendingApproval,+ AgentStatusResponse,+ AgentSuggestion,+ RequestWithAuth,+} from "./types";import {supabaseGetAgentByIdDirect,supabaseGetAgentRequestByIdDirect,@@ -40,6 +47,46 @@ function isIncompatiblePythonSdkOrigin(origin: unknown): boolean {);}+// Runs that produce more than a JSON result store an envelope instead of the+// raw result, so `data` keeps its original meaning for every existing object.+const AGENT_RESULT_KEY = "__agentResult";++type StoredAgentResult = {+ [AGENT_RESULT_KEY]: 1;+ data: unknown | null;+ message: string | null;+ suggestions?: AgentSuggestion[];+ pendingApproval?: AgentPendingApproval;+ // The per-run summary rides the envelope because options holds what the run+ // was asked to do, not what it did.+ exchange?: AgentExchangeSummary;+};++function isStoredAgentResult(value: unknown): value is StoredAgentResult {+ return (+ typeof value === "object" &&+ value !== null &&+ !Array.isArray(value) &&+ (value as Record<string, unknown>)[AGENT_RESULT_KEY] === 1+ );+}++// The agent service persists these next to `model`/`effort`, so they come from+// the same two sources and are absent on runs that predate threads.+type ThreadOptions = {+ threadId?: string;+ threadTurn?: number;+ mode?: AgentMode;+};++function readThreadOptions(options: any): ThreadOptions {+ return {+ threadId: options?.threadId,+ threadTurn: options?.threadTurn,+ mode: options?.mode,+ };+}+export async function agentStatusController(req: RequestWithAuth<{ jobId: string }, AgentStatusResponse, any>,res: Response<AgentStatusResponse>,@@ -61,12 +108,14 @@ export async function agentStatusController(// The agent service persists the effort of a run that used it. Older rows// and runs that picked a model have no effort, so this stays undefined.let effort: "low" | "medium" | "high" | undefined;+ let thread: ThreadOptions = {};if (agent) {model = (agent.options?.model ?? "spark-1-pro") as| "spark-1-pro"| "spark-1-mini"| "spark-2";effort = agent.options?.effort as "low" | "medium" | "high" | undefined;+ thread = readThreadOptions(agent.options);} else {try {const optionsRequest = await fetch(@@ -96,6 +145,7 @@ export async function agentStatusController(| "spark-1-mini"| "spark-2";effort = options.effort as "low" | "medium" | "high" | undefined;+ thread = readThreadOptions(options);}} catch (error) {logger.warn("Failed to get agent request details", {@@ -121,8 +171,21 @@ export async function agentStatusController(}let data: any = undefined;+ let message: string | undefined;+ let suggestions: AgentSuggestion[] | undefined;+ let pendingApproval: AgentPendingApproval | undefined;+ let exchange: AgentExchangeSummary | undefined;if (agent?.is_successful) {- data = await getJobFromGCS(agent.id);+ const stored: unknown = await getJobFromGCS(agent.id);+ if (isStoredAgentResult(stored)) {+ data = stored.data ?? null;+ message = stored.message ?? undefined;+ suggestions = stored.suggestions;+ pendingApproval = stored.pendingApproval;+ exchange = stored.exchange;+ } else {+ data = stored;+ }}return res.status(200).json({@@ -136,6 +199,13 @@ export async function agentStatusController(data,model,effort,+ threadId: thread.threadId,+ threadTurn: thread.threadTurn,+ mode: thread.mode,+ message,+ suggestions,+ pendingApproval,+ exchange,expiresAt: new Date(new Date(agent?.created_at ?? agentRequest.created_at).getTime() +1000 * 60 * 60 * 24,diff --git a/apps/api/src/controllers/v2/agent-thread.ts b/apps/api/src/controllers/v2/agent-thread.tsnew file mode 100644index 000000000..451ee8526--- /dev/null+++ b/apps/api/src/controllers/v2/agent-thread.ts@@ -0,0 +1,92 @@+import { Response } from "express";+import { config } from "../../config";+import { ErrorCodes } from "../../lib/error";+import { logger as _logger } from "../../lib/logger";+import { AgentThread, AgentThreadResponse, RequestWithAuth } from "./types";++const THREAD_ERRORS: Record<number, { code: ErrorCodes; error: string }> = {+ 404: { code: "thread_not_found", error: "Agent thread not found" },+ 409: {+ code: "thread_busy",+ error: "This thread already has a run in progress",+ },+ 410: { code: "thread_expired", error: "Agent thread has expired" },+ 503: { code: "threads_disabled", error: "Agent threads are not available" },+};++export function threadErrorFor(status: number) {+ return THREAD_ERRORS[status] ?? null;+}++export async function fetchAgentThread(+ threadId: string,+ teamId: string,+ options: { includeData?: boolean } = {},+) {+ if (!config.EXTRACT_V3_BETA_URL) {+ throw new Error("Agent beta is not enabled.");+ }++ const query = new URLSearchParams({ teamId });+ if (options.includeData !== undefined) {+ query.set("includeData", String(options.includeData));+ }++ return await fetch(+ `${config.EXTRACT_V3_BETA_URL}/internal/threads/${encodeURIComponent(threadId)}?${query}`,+ {+ headers: {+ Authorization: `Bearer ${config.AGENT_INTEROP_SECRET}`,+ },+ },+ );+}++export async function agentThreadController(+ req: RequestWithAuth<{ threadId: string }, AgentThreadResponse, any>,+ res: Response<AgentThreadResponse>,+) {+ const logger = _logger.child({+ threadId: req.params.threadId,+ teamId: req.auth.team_id,+ team_id: req.auth.team_id,+ module: "api/v2",+ method: "agentThreadController",+ });++ const upstream = await fetchAgentThread(+ req.params.threadId,+ req.auth.team_id,+ { includeData: req.query.includeData === "true" },+ );++ if (upstream.status !== 200) {+ const mapped = threadErrorFor(upstream.status);++ if (!mapped) {+ logger.error("Failed to get agent thread.", {+ status: upstream.status,+ text: await upstream.text(),+ });++ return res.status(500).json({+ success: false,+ error: "Failed to get agent thread.",+ });+ }++ return res.status(upstream.status).json({+ success: false,+ code: mapped.code,+ error: mapped.error,+ });+ }++ const body = (await upstream.json()) as { thread?: AgentThread };++ return res.status(200).json({+ success: true,+ // The agent service may return the thread bare or already wrapped.+ thread: (body.thread ?? body) as AgentThread,+ });+}diff --git a/apps/api/src/controllers/v2/agent.ts b/apps/api/src/controllers/v2/agent.tsindex 0ebe7fd17..38cfa18ee 100644--- a/apps/api/src/controllers/v2/agent.ts+++ b/apps/api/src/controllers/v2/agent.ts@@ -20,6 +20,7 @@ import { UnsafeDomainBlockedError } from "../../lib/threat-protection/error";import { calculateThreatScanCredits } from "../../lib/scrape-billing";import { billTeam } from "../../services/billing/credit_billing";import { emitRejectedScrapeActivityEvents } from "../../lib/siem-logging";+import { fetchAgentThread, threadErrorFor } from "./agent-thread";export async function agentController(req: RequestWithAuth<{}, AgentResponse, AgentRequest>,@@ -48,6 +49,20 @@ export async function agentController(});}+ // The agent service would reject every call from an unentitled team anyway;+ // failing here keeps the run β and its request row β from being created.+ if (+ req.body.exchange !== undefined &&+ req.body.exchange.enabled !== false &&+ !req.acuc?.flags?.exchangeRetrieve+ ) {+ return res.status(403).json({+ success: false,+ code: "exchange_not_enabled",+ error: "This option is not enabled for this team.",+ });+ }+_logger.info("Agent starting...", {request: req.body,originalRequest,@@ -130,6 +145,52 @@ export async function agentController(throw new Error("Agent beta is not enabled.");}+ // A follow-up is validated before the free request is consumed and before+ // logRequest, so a rejected continuation leaves no orphan request row.+ if (req.body.threadId) {+ const thread = await fetchAgentThread(+ req.body.threadId,+ req.auth.team_id,+ ).catch(error => {+ logger.error("Failed to check agent thread.", { error });+ return null;+ });++ if (thread === null) {+ return res.status(500).json({+ success: false,+ error: "Failed to check agent thread.",+ });+ }++ if (thread.status !== 200) {+ const mapped = threadErrorFor(thread.status);++ if (!mapped) {+ logger.error("Failed to check agent thread.", {+ status: thread.status,+ text: await thread.text(),+ });++ return res.status(500).json({+ success: false,+ error: "Failed to check agent thread.",+ });+ }++ const body = (await thread.json().catch(() => null)) as {+ runId?: unknown;+ } | null;++ return res.status(thread.status).json({+ success: false,+ code: mapped.code,+ error: mapped.error,+ ...(typeof body?.runId === "string" ? { runId: body.runId } : {}),+ });+ }+ }+// If maxCredits > 2500, skip free request consumption β this is always a paid requestconst highCreditRequest =req.body.maxCredits !== undefined && req.body.maxCredits > 2500;@@ -182,6 +243,9 @@ export async function agentController(model: req.body.model,effort: req.body.effort,auditMetadata: req.body.auditMetadata,+ threadId: req.body.threadId,+ mode: req.body.mode,+ exchange: req.body.exchange,}),},);@@ -202,8 +266,21 @@ export async function agentController(});}+ // The agent service mints the thread id, so the response body is the only+ // place it exists at this point.+ const result = (await passthrough.json().catch(() => null)) as {+ threadId?: unknown;+ threadTurn?: unknown;+ } | null;+return res.status(200).json({success: true,id: agentId,+ ...(typeof result?.threadId === "string"+ ? { threadId: result.threadId }+ : {}),+ ...(typeof result?.threadTurn === "number"+ ? { threadTurn: result.threadTurn }+ : {}),});}diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.tsindex a71adc0af..a35a795a8 100644--- a/apps/api/src/controllers/v2/types.ts+++ b/apps/api/src/controllers/v2/types.ts@@ -999,6 +999,27 @@ const agentWebhookSchema = createWebhookSchema(["cancelled",]);+// Forwarded verbatim to the agent service, which owns every default and the+// per-thread inheritance rules; the gateway only validates the shape.+const agentExchangeSchema = z.strictObject({+ enabled: z.boolean().optional(),+ toolkits: z.array(z.string()).max(5).optional(),+ maxCalls: z.number().int().min(1).max(30).optional(),+ requireApproval: z.boolean().optional(),+ approve: z+ .strictObject({+ approvalId: z.string().uuid(),+ callIds: z.array(z.string()).optional(),+ always: z.boolean().optional(),+ })+ .optional(),+ decline: z+ .strictObject({+ approvalId: z.string().uuid(),+ })+ .optional(),+});+export const agentRequestSchema = z.strictObject({urls: URL.array().optional(),@@ -1037,6 +1058,10 @@ export const agentRequestSchema = zeffort: z.enum(["low", "medium", "high"]).optional(),threatProtection: threatProtectionOverrideSchema.optional(),auditMetadata: auditMetadataSchema.optional(),+ // Continue an existing thread. Omitted starts a new one.+ threadId: z.string().uuid().optional(),+ mode: z.enum(["extract", "chat"]).optional(),+ exchange: agentExchangeSchema.optional(),})// spark-1 is retired and spark-2 is the default. The spark-1 preset names// remain valid input and silently resolve to spark-2, so every request β@@ -1538,11 +1563,53 @@ export type AgentListResponse =next?: string;};+export type AgentMode = "extract" | "chat";++export type AgentSuggestion = {+ label: string;+ prompt: string;+};++export type AgentPendingApproval = {+ id: string;+ reason: string;+ calls: {+ id: string;+ provider: string;+ capability: string;+ input: Record<string, unknown>;+ more?: Record<string, unknown>[];+ creditsEstimate: number | null;+ }[];+ resolution: null | {+ approved: boolean;+ callIds: string[];+ always: boolean;+ byRunId: string;+ };+};++// What a run did with Exchange, as the agent service reports it. `toolkits` and+// `requireApproval` are what the run resolved to after thread inheritance, so+// they describe the run rather than echoing the request.+export type AgentExchangeSummary = {+ enabled: boolean;+ toolkits?: string[];+ requireApproval?: boolean;+ paidCalls: number;+ creditsUsed: number | null;+};+export type AgentResponse =- | ErrorResponse+ | (ErrorResponse & {+ // Set on a 409 thread_busy: the run currently holding the thread.+ runId?: string;+ })| {success: boolean;id: string;+ threadId?: string;+ threadTurn?: number;};export type AgentStatusResponse =@@ -1556,6 +1623,54 @@ export type AgentStatusResponse =effort?: "low" | "medium" | "high";expiresAt: string;creditsUsed?: number;+ threadId?: string;+ threadTurn?: number;+ mode?: AgentMode;+ message?: string;+ suggestions?: AgentSuggestion[];+ pendingApproval?: AgentPendingApproval;+ exchange?: AgentExchangeSummary;+ };++type AgentThreadRun = {+ id: string;+ turn: number;+ mode: AgentMode;+ prompt: string;+ urls?: string[];+ schema?: unknown;+ effort?: "low" | "medium" | "high";+ status:+ | "processing"+ | "succeeded"+ | "failed"+ | "cancelled"+ | "refused"+ | "credit_limit_reached";+ createdAt: string;+ finishedAt: string | null;+ creditsUsed: number | null;+ message: string | null;+ // Only present when the request asked for includeData.+ data?: unknown;+ suggestions?: AgentSuggestion[] | null;+ pendingApproval?: AgentPendingApproval | null;+ exchange?: AgentExchangeSummary | null;+};++export type AgentThread = {+ id: string;+ createdAt: string;+ updatedAt: string;+ status: "idle" | "running";+ runs: AgentThreadRun[];+};++export type AgentThreadResponse =+ | ErrorResponse+ | {+ success: true;+ thread: AgentThread;};export type AgentTraceResponse =diff --git a/apps/api/src/lib/error-serde.ts b/apps/api/src/lib/error-serde.tsindex 4f973e356..8348af298 100644--- a/apps/api/src/lib/error-serde.ts+++ b/apps/api/src/lib/error-serde.ts@@ -90,6 +90,13 @@ const errorMap: Record<ErrorCodes, any> = {BAD_REQUEST: null,BAD_REQUEST_INVALID_JSON: null,PARSE_UNSUPPORTED_OPTIONS: null,++ // Agent thread rejections are API-level, never transported through workers.+ thread_not_found: null,+ thread_busy: null,+ thread_expired: null,+ threads_disabled: null,+ exchange_not_enabled: null,};export function serializeTransportableError(error: TransportableError) {diff --git a/apps/api/src/lib/error.ts b/apps/api/src/lib/error.tsindex 63814624a..67ed0f5a9 100644--- a/apps/api/src/lib/error.ts+++ b/apps/api/src/lib/error.ts@@ -42,7 +42,13 @@ export type ErrorCodes =| "CONCURRENCY_QUEUE_TIMEOUT"// Threat protection (enterprise domain risk blocking). Lowercase by design:// this is the documented, user-facing error code for the feature.- | "unsafe_domain_blocked";+ | "unsafe_domain_blocked"+ // Agent threads. Lowercase for the same reason as unsafe_domain_blocked.+ | "thread_not_found"+ | "thread_busy"+ | "thread_expired"+ | "threads_disabled"+ | "exchange_not_enabled";export class TransportableError extends Error {public readonly code: ErrorCodes;diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.tsindex 0ea7ae9ce..fae4ecd5f 100644--- a/apps/api/src/routes/v2.ts+++ b/apps/api/src/routes/v2.ts@@ -57,6 +57,7 @@ import { agentStatusController } from "../controllers/v2/agent-status";import { agentCancelController } from "../controllers/v2/agent-cancel";import { agentTraceController } from "../controllers/v2/agent-trace";import { agentSnapshotController } from "../controllers/v2/agent-snapshot";+import { agentThreadController } from "../controllers/v2/agent-thread";import {browserCreateController,browserExecuteController,@@ -383,6 +384,13 @@ v2Router.get(wrap(agentListController),);+// Registered ahead of "/agent/:jobId" so a thread id is never read as a job id.+v2Router.get(+ "/agent/threads/:threadId",+ authMiddleware(RateLimiterMode.ExtractStatus),+ wrap(agentThreadController),+);+v2Router.post("/agent",authMiddleware(RateLimiterMode.Extract),diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-effort-trace.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-effort-trace.unit.test.tsindex 2a2638e25..2a0b744e1 100644--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-effort-trace.unit.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-effort-trace.unit.test.ts@@ -1,4 +1,4 @@-import { describe, expect, test } from "@jest/globals";+import { describe, expect, jest, test } from "@jest/globals";import {startAgent,getAgentTrace,diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-thread.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-thread.unit.test.tsnew file mode 100644index 000000000..b635be6bd--- /dev/null+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-thread.unit.test.ts@@ -0,0 +1,164 @@+import { describe, expect, jest, test } from "@jest/globals";+import {+ getAgentStatus,+ getAgentThread,+ startAgent,+} from "../../../v2/methods/agent";++const okPost = () =>+ jest.fn().mockResolvedValue({+ status: 200,+ data: { success: true, id: "agent-job", threadId: "thread-1", threadTurn: 2 },+ });++describe("v2.agent threads unit", () => {+ test("startAgent forwards the thread fields when set", async () => {+ const post = okPost();++ await startAgent({ post } as any, {+ prompt: "Which tier has SSO?",+ threadId: "thread-1",+ mode: "chat",+ exchange: { enabled: true, toolkits: ["a", "b"] },+ });++ expect(post).toHaveBeenCalledWith("/v2/agent", {+ prompt: "Which tier has SSO?",+ threadId: "thread-1",+ mode: "chat",+ exchange: { enabled: true, toolkits: ["a", "b"] },+ });+ });++ test("startAgent omits the thread fields when unset", async () => {+ const post = okPost();++ await startAgent({ post } as any, { prompt: "List the pricing tiers" });++ expect(post).toHaveBeenCalledWith("/v2/agent", {+ prompt: "List the pricing tiers",+ });+ });++ test("startAgent returns the thread the run belongs to", async () => {+ const started = await startAgent({ post: okPost() } as any, {+ prompt: "Which tier has SSO?",+ threadId: "thread-1",+ });++ expect(started.threadId).toBe("thread-1");+ expect(started.threadTurn).toBe(2);+ });++ test("getAgentStatus parses a chat-mode status payload", async () => {+ const get = jest.fn().mockResolvedValue({+ status: 200,+ data: {+ success: true,+ status: "completed",+ data: null,+ model: "spark-2",+ expiresAt: "2026-09-02T00:00:00.000Z",+ threadId: "thread-1",+ threadTurn: 2,+ mode: "chat",+ message: "Only the Enterprise tier lists SSO.",+ suggestions: [{ label: "Seat caps?", prompt: "Does Team cap seats?" }],+ pendingApproval: {+ id: "approval-1",+ reason: "One paid call answers this.",+ calls: [+ {+ id: "call-1",+ provider: "provider-1",+ capability: "capability-1",+ input: { query: "sso" },+ creditsEstimate: 5,+ },+ ],+ resolution: null,+ },+ exchange: { enabled: true, paidCalls: 0, creditsUsed: null },+ },+ });++ const status = await getAgentStatus({ get } as any, "agent-job");++ expect(get).toHaveBeenCalledWith("/v2/agent/agent-job");+ expect(status.data).toBeNull();+ expect(status.message).toBe("Only the Enterprise tier lists SSO.");+ expect(status.mode).toBe("chat");+ expect(status.threadTurn).toBe(2);+ expect(status.suggestions).toHaveLength(1);+ expect(status.pendingApproval!.calls[0].creditsEstimate).toBe(5);+ expect(status.exchange!.paidCalls).toBe(0);+ });++ test("getAgentStatus parses a status payload without the thread fields", async () => {+ const get = jest.fn().mockResolvedValue({+ status: 200,+ data: {+ success: true,+ status: "completed",+ data: { price: 42 },+ model: "spark-2",+ expiresAt: "2026-09-02T00:00:00.000Z",+ creditsUsed: 12,+ },+ });++ const status = await getAgentStatus({ get } as any, "agent-job");++ expect(status.data).toEqual({ price: 42 });+ expect(status.threadId).toBeUndefined();+ expect(status.message).toBeUndefined();+ expect(status.pendingApproval).toBeUndefined();+ });++ test("getAgentThread hits the thread endpoint", async () => {+ const get = jest.fn().mockResolvedValue({+ status: 200,+ data: {+ success: true,+ thread: {+ id: "thread-1",+ createdAt: "2026-09-01T00:00:00.000Z",+ updatedAt: "2026-09-01T00:01:00.000Z",+ status: "idle",+ runs: [+ {+ id: "agent-job",+ turn: 1,+ mode: "chat",+ prompt: "List the pricing tiers",+ status: "succeeded",+ createdAt: "2026-09-01T00:00:00.000Z",+ finishedAt: "2026-09-01T00:00:30.000Z",+ creditsUsed: 212,+ message: null,+ },+ ],+ },+ },+ });++ const thread = await getAgentThread({ get } as any, "thread-1");++ expect(get).toHaveBeenCalledWith("/v2/agent/threads/thread-1");+ expect(thread.thread!.runs).toHaveLength(1);+ expect(thread.thread!.runs[0].turn).toBe(1);+ });++ test("getAgentThread appends includeData when requested", async () => {+ const get = jest.fn().mockResolvedValue({+ status: 200,+ data: { success: true, thread: { id: "thread-1", runs: [] } },+ });++ await getAgentThread({ get } as any, "thread-1", { includeData: true });++ expect(get).toHaveBeenCalledWith(+ "/v2/agent/threads/thread-1?includeData=true",+ );+ });+});diff --git a/apps/js-sdk/firecrawl/src/v2/client.ts b/apps/js-sdk/firecrawl/src/v2/client.tsindex ede04d4ac..8c3091286 100644--- a/apps/js-sdk/firecrawl/src/v2/client.ts+++ b/apps/js-sdk/firecrawl/src/v2/client.ts@@ -26,7 +26,7 @@ import {batchScrape as batchWaiter,} from "./methods/batch";import { startExtract, getExtractStatus, extract as extractWaiter } from "./methods/extract";-import { startAgent, getAgentStatus, getAgentTrace, getAgentSnapshot, cancelAgent, listAgents, agent as agentWaiter } from "./methods/agent";+import { startAgent, getAgentStatus, getAgentThread, getAgentTrace, getAgentSnapshot, cancelAgent, listAgents, agent as agentWaiter } from "./methods/agent";import {browser as browserMethod,browserExecute,@@ -70,6 +70,7 @@ import type {AgentStatusResponse,AgentTraceResponse,AgentSnapshotResponse,+ AgentThreadResponse,AgentListOptions,AgentListResponse,CrawlOptions,@@ -566,6 +567,14 @@ export class FirecrawlClient {async getAgentSnapshot(jobId: string, snapshotId: string): Promise<AgentSnapshotResponse> {return getAgentSnapshot(this.http, jobId, snapshotId);}+ /**+ * Get a thread and its runs, oldest turn first.+ * @param threadId Thread id, as returned by startAgent or getAgentStatus.+ * @param options.includeData Inline each succeeded run's data.+ */+ async getAgentThread(threadId: string, options?: { includeData?: boolean }): Promise<AgentThreadResponse> {+ return getAgentThread(this.http, threadId, options);+ }// Browser/**diff --git a/apps/js-sdk/firecrawl/src/v2/methods/agent.ts b/apps/js-sdk/firecrawl/src/v2/methods/agent.tsindex 46765e45e..0d09745c0 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/agent.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/agent.ts@@ -1,4 +1,4 @@-import { type AgentEffort, type AgentListOptions, type AgentListResponse, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentTraceResponse, type AgentWebhookConfig, type AuditMetadata, type ThreatProtectionOptions } from "../types";+import { type AgentEffort, type AgentExchangeOptions, type AgentListOptions, type AgentListResponse, type AgentMode, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentThreadResponse, type AgentTraceResponse, type AgentWebhookConfig, type AuditMetadata, type ThreatProtectionOptions } from "../types";import { HttpClient } from "../utils/httpClient";import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";import { isZodSchema, zodSchemaToJsonSchema } from "../../utils/zodSchemaToJson";@@ -17,6 +17,9 @@ function prepareAgentPayload(args: {webhook?: string | AgentWebhookConfig;threatProtection?: ThreatProtectionOptions;auditMetadata?: AuditMetadata;+ threadId?: string;+ mode?: AgentMode;+ exchange?: AgentExchangeOptions;}): Record<string, unknown> {const body: Record<string, unknown> = {};if (args.urls) body.urls = args.urls;@@ -35,6 +38,9 @@ function prepareAgentPayload(args: {body.threatProtection = args.threatProtection;if (args.auditMetadata != null)body.auditMetadata = args.auditMetadata;+ if (args.threadId != null) body.threadId = args.threadId;+ if (args.mode != null) body.mode = args.mode;+ if (args.exchange != null) body.exchange = args.exchange;return body;}@@ -129,6 +135,22 @@ export async function getAgentSnapshot(}}+export async function getAgentThread(+ http: HttpClient,+ threadId: string,+ options?: { includeData?: boolean }+): Promise<AgentThreadResponse> {+ try {+ const query = options?.includeData ? "?includeData=true" : "";+ const res = await http.get<AgentThreadResponse>(`/v2/agent/threads/${threadId}${query}`);+ if (res.status !== 200) throwForBadResponse(res, "agent thread");+ return res.data;+ } catch (err: any) {+ if (err?.isAxiosError) return normalizeAxiosError(err, "agent thread");+ throw err;+ }+}+export async function cancelAgent(http: HttpClient, jobId: string): Promise<boolean> {try {const res = await http.delete<{ success: boolean }>(`/v2/agent/${jobId}`);diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex d36ef7866..b6b750558 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -278,12 +278,7 @@ export interface ScrapeOptions {}export type RedactPIIEntity =- | "PERSON"- | "EMAIL"- | "PHONE"- | "LOCATION"- | "FINANCIAL"- | "SECRET";+ "PERSON" | "EMAIL" | "PHONE" | "LOCATION" | "FINANCIAL" | "SECRET";export interface RedactPIIOptions {/**@@ -324,12 +319,7 @@ export interface ThreatProtectionOptions {}export type ParseFileData =- | Blob- | File- | Buffer- | Uint8Array- | ArrayBuffer- | string;+ Blob | File | Buffer | Uint8Array | ArrayBuffer | string;export interface ParseFile {data: ParseFileData;@@ -364,11 +354,7 @@ export interface WebhookConfig {// Agent webhook events differ from crawl: has 'action' and 'cancelled', no 'page'export type AgentWebhookEvent =- | "started"- | "action"- | "completed"- | "failed"- | "cancelled";+ "started" | "action" | "completed" | "failed" | "cancelled";export interface AgentWebhookConfig {url: string;@@ -489,10 +475,7 @@ export interface BrandingProfile {headerHeight?: string;footerHeight?: string;[key: string]:- | number- | string- | Record<string, number | string | undefined>- | undefined;+ number | string | Record<string, number | string | undefined> | undefined;};tone?: {voice?: string;@@ -1095,9 +1078,7 @@ export interface MonitorSearchTarget {}export type MonitorTarget =- | MonitorScrapeTarget- | MonitorCrawlTarget- | MonitorSearchTarget;+ MonitorScrapeTarget | MonitorCrawlTarget | MonitorSearchTarget;export interface CreateMonitorRequest {name: string;@@ -1220,11 +1201,7 @@ export interface MonitorCheck {reservedCredits?: number | null;actualCredits?: number | null;billingStatus:- | "not_applicable"- | "reserved"- | "confirmed"- | "released"- | "failed";+ "not_applicable" | "reserved" | "confirmed" | "released" | "failed";summary: MonitorSummary;targetResults?: MonitorTargetResult[];notificationStatus?: unknown;@@ -1311,10 +1288,65 @@ export interface ExtractResponse {creditsUsed?: number;}+/** Conversation mode for an agent run. Defaults to "extract" server-side. */+export type AgentMode = "extract" | "chat";++/** Options forwarded verbatim to the agent; the server owns every default. */+export interface AgentExchangeOptions {+ enabled?: boolean;+ /** At most 5. */+ toolkits?: string[];+ maxCalls?: number;+ requireApproval?: boolean;+ /** Answers a pendingApproval from the previous turn of the thread. */+ approve?: { approvalId: string; callIds?: string[]; always?: boolean };+ decline?: { approvalId: string };+}++/** Per-run summary reported on a status response. */+export interface AgentExchangeSummary {+ enabled: boolean;+ /** What the run resolved to after thread inheritance, not what it requested. */+ toolkits?: string[];+ requireApproval?: boolean;+ paidCalls: number;+ creditsUsed: number | null;+}++/** A follow-up the agent offers for the next turn of the thread. */+export interface AgentSuggestion {+ label: string;+ prompt: string;+}++/** A turn that ended waiting for the caller to allow or refuse paid calls. */+export interface PendingApproval {+ id: string;+ reason: string;+ calls: {+ id: string;+ provider: string;+ capability: string;+ input: Record<string, unknown>;+ more?: Record<string, unknown>[];+ creditsEstimate: number | null;+ }[];+ resolution: null | {+ approved: boolean;+ callIds: string[];+ always: boolean;+ byRunId: string;+ };+}+export interface AgentResponse {success: boolean;id: string;error?: string;+ /** Thread this run belongs to; pass it back to continue the conversation. */+ threadId?: string;+ /** 1-based position of this run in its thread. */+ threadTurn?: number;}export interface AgentStatusResponse {@@ -1335,6 +1367,55 @@ export interface AgentStatusResponse {effort?: "low" | "medium" | "high";expiresAt: string;creditsUsed?: number;+ threadId?: string;+ threadTurn?: number;+ mode?: AgentMode;+ /** Assistant text reply. Chat-mode runs answer here instead of in `data`. */+ message?: string;+ suggestions?: AgentSuggestion[];+ pendingApproval?: PendingApproval;+ exchange?: AgentExchangeSummary;+}++/** A single run of a thread, as returned by getAgentThread. */+export interface AgentThreadRun {+ id: string;+ turn: number;+ mode: AgentMode;+ prompt: string;+ urls?: string[];+ schema?: unknown;+ effort?: "low" | "medium" | "high";+ status:+ | "processing"+ | "succeeded"+ | "failed"+ | "cancelled"+ | "refused"+ | "credit_limit_reached";+ createdAt: string;+ finishedAt: string | null;+ creditsUsed: number | null;+ message: string | null;+ /** Only present when the request asked for includeData. */+ data?: unknown;+ suggestions?: AgentSuggestion[] | null;+ pendingApproval?: PendingApproval | null;+ exchange?: AgentExchangeSummary | null;+}++export interface AgentThread {+ id: string;+ createdAt: string;+ updatedAt: string;+ status: "idle" | "running";+ runs: AgentThreadRun[];+}++export interface AgentThreadResponse {+ success: boolean;+ thread?: AgentThread;+ error?: string;}/** Reasoning effort for agent jobs. Every level runs spark-2. */@@ -1384,7 +1465,8 @@ export interface AgentListOptions {before?: number;}-export type AgentTraceAgentRole = "orchestrator" | "subagent" | "browser" | "system";+export type AgentTraceAgentRole =+ "orchestrator" | "subagent" | "browser" | "system";export interface AgentTraceAgentIdentity {id: string;@@ -1394,7 +1476,12 @@ export interface AgentTraceAgentIdentity {}export interface AgentTraceError {- code: "cancelled" | "credit_limit_reached" | "parent_finished" | "refused" | "internal";+ code:+ | "cancelled"+ | "credit_limit_reached"+ | "parent_finished"+ | "refused"+ | "internal";source: "agent" | "tool" | "billing" | "system";retryable: boolean;message: string;@@ -1432,7 +1519,8 @@ export interface AgentTraceRunCancelRequestedEvent extends AgentTraceEventBase {export interface AgentTraceRunFinishedEvent extends AgentTraceEventBase {type: "run.finished";- outcome: "succeeded" | "failed" | "cancelled" | "refused" | "credit_limit_reached";+ outcome:+ "succeeded" | "failed" | "cancelled" | "refused" | "credit_limit_reached";/** The canonical schema always writes this key (nullable), but older rows may omit it. */error?: AgentTraceError | null;}diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_thread.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_thread.pynew file mode 100644index 000000000..5424f959a--- /dev/null+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_thread.py@@ -0,0 +1,214 @@+"""+Unit tests for agent threads: request serialization, status parsing and the+thread read method.+"""++from unittest.mock import Mock++from firecrawl.v2.methods.agent import (+ _prepare_agent_request,+ get_agent_thread,+ start_agent,+)+from firecrawl.v2.types import (+ AgentExchangeOptions,+ AgentResponse,+ AgentThreadResponse,+)+++class TestAgentThreadRequestPreparation:+ """The thread fields must only reach the body when the caller sets them."""++ def test_thread_fields_omitted_when_unset(self):+ data = _prepare_agent_request(None, prompt="List the pricing tiers")++ assert "threadId" not in data+ assert "mode" not in data+ assert "exchange" not in data++ def test_thread_id_and_mode_forwarded(self):+ data = _prepare_agent_request(+ None,+ prompt="Which tier has SSO?",+ thread_id="thread-1",+ mode="chat",+ )++ assert data["threadId"] == "thread-1"+ assert data["mode"] == "chat"++ def test_exchange_dict_forwarded_verbatim(self):+ exchange = {"enabled": True, "toolkits": ["a", "b"], "maxCalls": 4}+ data = _prepare_agent_request(+ None, prompt="Which tier has SSO?", exchange=exchange+ )++ assert data["exchange"] == exchange++ def test_exchange_model_serialized_by_alias(self):+ data = _prepare_agent_request(+ None,+ prompt="Which tier has SSO?",+ exchange=AgentExchangeOptions(enabled=True, max_calls=4),+ )++ assert data["exchange"] == {"enabled": True, "maxCalls": 4}++ def test_start_agent_forwards_thread_id(self):+ client = Mock()+ response = Mock()+ response.ok = True+ response.json.return_value = {+ "success": True,+ "id": "job-2",+ "threadId": "thread-1",+ "threadTurn": 2,+ }+ client.post.return_value = response++ result = start_agent(+ client, None, prompt="Which tier has SSO?", thread_id="thread-1"+ )++ assert client.post.call_args[0][1]["threadId"] == "thread-1"+ assert result.thread_id == "thread-1"+ assert result.thread_turn == 2+++class TestAgentThreadStatusParsing:+ """Status payloads parse with and without the thread fields."""++ def test_status_payload_without_thread_fields(self):+ response = AgentResponse(+ **{+ "success": True,+ "id": "job-1",+ "status": "completed",+ "model": "spark-2",+ "data": {"price": 42},+ }+ )++ assert response.data == {"price": 42}+ assert response.thread_id is None+ assert response.message is None+ assert response.pending_approval is None++ def test_chat_mode_status_payload(self):+ response = AgentResponse(+ **{+ "success": True,+ "id": "job-2",+ "status": "completed",+ "model": "spark-2",+ "data": None,+ "threadId": "thread-1",+ "threadTurn": 2,+ "mode": "chat",+ "message": "Only the Enterprise tier lists SSO.",+ "suggestions": [+ {"label": "Seat caps?", "prompt": "Does Team cap seats?"}+ ],+ "pendingApproval": {+ "id": "approval-1",+ "reason": "One paid call answers this.",+ "calls": [+ {+ "id": "call-1",+ "provider": "provider-1",+ "capability": "capability-1",+ "input": {"query": "sso"},+ "creditsEstimate": 5,+ }+ ],+ "resolution": None,+ },+ "exchange": {"enabled": True, "paidCalls": 0, "creditsUsed": None},+ }+ )++ assert response.data is None+ assert response.message == "Only the Enterprise tier lists SSO."+ assert response.mode == "chat"+ assert response.thread_turn == 2+ assert response.suggestions[0].label == "Seat caps?"+ assert response.pending_approval.calls[0].credits_estimate == 5+ assert response.exchange.paid_calls == 0++ def test_status_payload_ignores_unknown_fields(self):+ """Old SDKs must survive server-side additions; new ones must too."""+ response = AgentResponse(+ **{+ "success": True,+ "id": "job-1",+ "status": "completed",+ "somethingNew": {"shipped": "later"},+ }+ )++ assert response.id == "job-1"+++class TestGetAgentThread:+ """The thread read hits the documented path."""++ def _client(self):+ client = Mock()+ response = Mock()+ response.ok = True+ response.json.return_value = {+ "success": True,+ "thread": {+ "id": "thread-1",+ "createdAt": "2026-09-01T00:00:00Z",+ "updatedAt": "2026-09-01T00:01:00Z",+ "status": "idle",+ "runs": [+ {+ "id": "job-1",+ "turn": 1,+ "mode": "chat",+ "prompt": "List the pricing tiers",+ "status": "succeeded",+ "createdAt": "2026-09-01T00:00:00Z",+ "finishedAt": "2026-09-01T00:00:30Z",+ "creditsUsed": 212,+ "message": None,+ },+ {+ "id": "job-2",+ "turn": 2,+ "mode": "chat",+ "prompt": "Which tier has SSO?",+ "status": "succeeded",+ "createdAt": "2026-09-01T00:00:40Z",+ "finishedAt": "2026-09-01T00:01:00Z",+ "creditsUsed": 31,+ "message": "Only the Enterprise tier lists SSO.",+ },+ ],+ },+ }+ client.get.return_value = response+ return client++ def test_hits_the_thread_endpoint(self):+ client = self._client()++ result = get_agent_thread(client, "thread-1")++ client.get.assert_called_once_with("/v2/agent/threads/thread-1")+ assert isinstance(result, AgentThreadResponse)+ assert len(result.thread.runs) == 2+ assert result.thread.runs[1].credits_used == 31+ assert result.thread.runs[1].message == "Only the Enterprise tier lists SSO."++ def test_include_data_query(self):+ client = self._client()++ get_agent_thread(client, "thread-1", include_data=True)++ client.get.assert_called_once_with(+ "/v2/agent/threads/thread-1?includeData=true"+ )diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex 700e63e71..a975f05c6 100644--- a/apps/python-sdk/firecrawl/v2/client.py+++ b/apps/python-sdk/firecrawl/v2/client.py@@ -26,6 +26,7 @@ from .types import (CrawlParamsData,WebhookConfig,AgentWebhookConfig,+ AgentExchangeOptions,MonitorWebhookConfig,CrawlErrorsResponse,ActiveCrawlsResponse,@@ -1403,6 +1404,9 @@ class FirecrawlClient:webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,):"""Start an agent job (non-blocking).@@ -1418,6 +1422,9 @@ class FirecrawlClient:threat_protection: Enterprise per-request override of the team'sthreat protection policyaudit_metadata: Metadata to include in SIEM logging events+ thread_id: Continue an existing thread instead of starting one+ mode: "extract" (default) or "chat"+ exchange: Data provider options, forwarded as sentReturns:Response payload with job id/status (poll with get_agent_status)"""@@ -1434,6 +1441,9 @@ class FirecrawlClient:webhook=webhook,threat_protection=threat_protection,audit_metadata=audit_metadata,+ thread_id=thread_id,+ mode=mode,+ exchange=exchange,)def agent(@@ -1452,6 +1462,9 @@ class FirecrawlClient:webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,):"""Run an agent and wait until completion.@@ -1469,6 +1482,9 @@ class FirecrawlClient:threat_protection: Enterprise per-request override of the team'sthreat protection policyaudit_metadata: Metadata to include in SIEM logging events+ thread_id: Continue an existing thread instead of starting one+ mode: "extract" (default) or "chat"+ exchange: Data provider options, forwarded as sentReturns:Final agent response when completed"""@@ -1487,6 +1503,9 @@ class FirecrawlClient:webhook=webhook,threat_protection=threat_protection,audit_metadata=audit_metadata,+ thread_id=thread_id,+ mode=mode,+ exchange=exchange,)def get_agent_status(self, job_id: str):@@ -1526,6 +1545,20 @@ class FirecrawlClient:"""return agent_module.list_agents(self.http_client, before=before)+ def get_agent_thread(self, thread_id: str, *, include_data: bool = False):+ """Get a thread and its runs, oldest turn first.++ Args:+ thread_id: Thread ID, as returned by start_agent or get_agent_status+ include_data: Inline each succeeded run's data++ Returns:+ AgentThreadResponse with the thread and its runs+ """+ return agent_module.get_agent_thread(+ self.http_client, thread_id, include_data=include_data+ )+def get_agent_trace(self, job_id: str, *, live_view: bool = False):"""Get the execution trace of an agent job (spark-2 runs only).diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.pyindex 6a73a9205..9a1e50244 100644--- a/apps/python-sdk/firecrawl/v2/client_async.py+++ b/apps/python-sdk/firecrawl/v2/client_async.py@@ -13,6 +13,7 @@ from .types import (CrawlRequest,WebhookConfig,AgentWebhookConfig,+ AgentExchangeOptions,MonitorWebhookConfig,SearchRequest,SearchData,@@ -743,6 +744,9 @@ class AsyncFirecrawlClient:webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,):return await async_agent.agent(self.async_http_client,@@ -759,6 +763,9 @@ class AsyncFirecrawlClient:webhook=webhook,threat_protection=threat_protection,audit_metadata=audit_metadata,+ thread_id=thread_id,+ mode=mode,+ exchange=exchange,)async def get_agent_status(self, job_id: str):@@ -778,6 +785,9 @@ class AsyncFirecrawlClient:webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,):return await async_agent.start_agent(self.async_http_client,@@ -792,6 +802,9 @@ class AsyncFirecrawlClient:webhook=webhook,threat_protection=threat_protection,audit_metadata=audit_metadata,+ thread_id=thread_id,+ mode=mode,+ exchange=exchange,)async def cancel_agent(self, job_id: str) -> bool:@@ -820,6 +833,20 @@ class AsyncFirecrawlClient:"""return await async_agent.list_agents(self.async_http_client, before=before)+ async def get_agent_thread(self, thread_id: str, *, include_data: bool = False):+ """Get a thread and its runs, oldest turn first.++ Args:+ thread_id: Thread ID, as returned by start_agent or get_agent_status+ include_data: Inline each succeeded run's data++ Returns:+ AgentThreadResponse with the thread and its runs+ """+ return await async_agent.get_agent_thread(+ self.async_http_client, thread_id, include_data=include_data+ )+async def get_agent_trace(self, job_id: str, *, live_view: bool = False):"""Get the execution trace of an agent job (spark-2 runs only).diff --git a/apps/python-sdk/firecrawl/v2/methods/agent.py b/apps/python-sdk/firecrawl/v2/methods/agent.pyindex a857e14fb..4e64d59bd 100644--- a/apps/python-sdk/firecrawl/v2/methods/agent.py+++ b/apps/python-sdk/firecrawl/v2/methods/agent.py@@ -2,9 +2,11 @@ from typing import Any, Dict, List, Literal, Optional, Unionimport timefrom ..types import (+ AgentExchangeOptions,AgentListResponse,AgentResponse,AgentSnapshotResponse,+ AgentThreadResponse,AgentTraceResponse,AgentWebhookConfig,AuditMetadata,@@ -28,6 +30,9 @@ def _prepare_agent_request(webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,) -> Dict[str, Any]:body: Dict[str, Any] = {}if urls is not None:@@ -63,6 +68,16 @@ def _prepare_agent_request()if audit_metadata is not None:body["auditMetadata"] = audit_metadata.model_dump()+ if thread_id is not None:+ body["threadId"] = thread_id+ if mode is not None:+ body["mode"] = mode+ if exchange is not None:+ body["exchange"] = (+ exchange+ if isinstance(exchange, dict)+ else exchange.model_dump(by_alias=True, exclude_none=True)+ )return body@@ -89,6 +104,9 @@ def start_agent(webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,) -> AgentResponse:body = _prepare_agent_request(urls,@@ -102,6 +120,9 @@ def start_agent(webhook=webhook,threat_protection=threat_protection,audit_metadata=audit_metadata,+ thread_id=thread_id,+ mode=mode,+ exchange=exchange,)resp = client.post("/v2/agent", body)if not resp.ok:@@ -178,6 +199,9 @@ def agent(webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,) -> AgentResponse:started = start_agent(client,@@ -192,6 +216,9 @@ def agent(webhook=webhook,threat_protection=threat_protection,audit_metadata=audit_metadata,+ thread_id=thread_id,+ mode=mode,+ exchange=exchange,)job_id = getattr(started, "id", None)if not job_id:@@ -221,6 +248,28 @@ def get_agent_trace(return AgentTraceResponse(**resp.json())+def get_agent_thread(+ client: HttpClient,+ thread_id: str,+ *,+ include_data: bool = False,+) -> AgentThreadResponse:+ """Get a thread and its runs, oldest turn first.++ Args:+ client: HTTP client instance+ thread_id: Thread ID, as returned by start_agent or get_agent_status+ include_data: Inline each succeeded run's data+ """+ endpoint = f"/v2/agent/threads/{thread_id}"+ if include_data:+ endpoint += "?includeData=true"+ resp = client.get(endpoint)+ if not resp.ok:+ handle_response_error(resp, "agent-thread")+ return AgentThreadResponse(**resp.json())++def get_agent_snapshot(client: HttpClient,job_id: str,diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/agent.py b/apps/python-sdk/firecrawl/v2/methods/aio/agent.pyindex 40015c2f4..023d5578f 100644--- a/apps/python-sdk/firecrawl/v2/methods/aio/agent.py+++ b/apps/python-sdk/firecrawl/v2/methods/aio/agent.py@@ -2,9 +2,11 @@ from typing import Any, Dict, List, Literal, Optional, Unionimport asynciofrom ...types import (+ AgentExchangeOptions,AgentListResponse,AgentResponse,AgentSnapshotResponse,+ AgentThreadResponse,AgentTraceResponse,AgentWebhookConfig,AuditMetadata,@@ -28,6 +30,9 @@ def _prepare_agent_request(webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,) -> Dict[str, Any]:body: Dict[str, Any] = {}if urls is not None:@@ -63,6 +68,16 @@ def _prepare_agent_request()if audit_metadata is not None:body["auditMetadata"] = audit_metadata.model_dump()+ if thread_id is not None:+ body["threadId"] = thread_id+ if mode is not None:+ body["mode"] = mode+ if exchange is not None:+ body["exchange"] = (+ exchange+ if isinstance(exchange, dict)+ else exchange.model_dump(by_alias=True, exclude_none=True)+ )return body@@ -89,6 +104,9 @@ async def start_agent(webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,) -> AgentResponse:body = _prepare_agent_request(urls,@@ -102,6 +120,9 @@ async def start_agent(webhook=webhook,threat_protection=threat_protection,audit_metadata=audit_metadata,+ thread_id=thread_id,+ mode=mode,+ exchange=exchange,)resp = await client.post("/v2/agent", body)if not resp.ok:@@ -178,6 +199,9 @@ async def agent(webhook: Optional[Union[str, AgentWebhookConfig]] = None,threat_protection: Optional[ThreatProtectionOptions] = None,audit_metadata: Optional[AuditMetadata] = None,+ thread_id: Optional[str] = None,+ mode: Optional[Literal["extract", "chat"]] = None,+ exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,) -> AgentResponse:started = await start_agent(client,@@ -192,6 +216,9 @@ async def agent(webhook=webhook,threat_protection=threat_protection,audit_metadata=audit_metadata,+ thread_id=thread_id,+ mode=mode,+ exchange=exchange,)job_id = getattr(started, "id", None)if not job_id:@@ -221,6 +248,28 @@ async def get_agent_trace(return AgentTraceResponse(**resp.json())+async def get_agent_thread(+ client: AsyncHttpClient,+ thread_id: str,+ *,+ include_data: bool = False,+) -> AgentThreadResponse:+ """Get a thread and its runs, oldest turn first.++ Args:+ client: Async HTTP client instance+ thread_id: Thread ID, as returned by start_agent or get_agent_status+ include_data: Inline each succeeded run's data+ """+ endpoint = f"/v2/agent/threads/{thread_id}"+ if include_data:+ endpoint += "?includeData=true"+ resp = await client.get(endpoint)+ if not resp.ok:+ handle_response_error(resp, "agent-thread")+ return AgentThreadResponse(**resp.json())++async def get_agent_snapshot(client: AsyncHttpClient,job_id: str,diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex 922f45e6f..6f101c2bb 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -1449,9 +1449,83 @@ class ExtractResponse(BaseModel):tokens_used: Optional[int] = None+class AgentExchangeOptions(BaseModel):+ """Options forwarded verbatim to the agent; the server owns every default."""++ model_config = {"populate_by_name": True}++ enabled: Optional[bool] = None+ # At most 5.+ toolkits: Optional[List[str]] = None+ max_calls: Optional[int] = Field(default=None, alias="maxCalls")+ require_approval: Optional[bool] = Field(default=None, alias="requireApproval")+ # Answers a pending_approval from the previous turn of the thread.+ approve: Optional[Dict[str, Any]] = None+ decline: Optional[Dict[str, Any]] = None+++class AgentExchangeSummary(BaseModel):+ """Per-run summary reported on a status response."""++ model_config = {"populate_by_name": True, "extra": "allow"}++ enabled: Optional[bool] = None+ # What the run resolved to after thread inheritance, not what it requested.+ toolkits: Optional[List[str]] = None+ require_approval: Optional[bool] = Field(default=None, alias="requireApproval")+ paid_calls: Optional[int] = Field(default=None, alias="paidCalls")+ credits_used: Optional[int] = Field(default=None, alias="creditsUsed")+++class AgentSuggestion(BaseModel):+ """A follow-up the agent offers for the next turn of the thread."""++ model_config = {"populate_by_name": True, "extra": "allow"}++ label: Optional[str] = None+ prompt: Optional[str] = None+++class PendingApprovalCall(BaseModel):+ """One call held back by a pending approval."""++ model_config = {"populate_by_name": True, "extra": "allow"}++ id: Optional[str] = None+ provider: Optional[str] = None+ capability: Optional[str] = None+ input: Optional[Dict[str, Any]] = None+ more: Optional[List[Dict[str, Any]]] = None+ credits_estimate: Optional[int] = Field(default=None, alias="creditsEstimate")+++class PendingApprovalResolution(BaseModel):+ """How a pending approval was answered by a later turn."""++ model_config = {"populate_by_name": True, "extra": "allow"}++ approved: Optional[bool] = None+ call_ids: Optional[List[str]] = Field(default=None, alias="callIds")+ always: Optional[bool] = None+ by_run_id: Optional[str] = Field(default=None, alias="byRunId")+++class PendingApproval(BaseModel):+ """A turn that ended waiting for the caller to allow or refuse paid calls."""++ model_config = {"populate_by_name": True, "extra": "allow"}++ id: Optional[str] = None+ reason: Optional[str] = None+ calls: Optional[List[PendingApprovalCall]] = None+ resolution: Optional[PendingApprovalResolution] = None++class AgentResponse(BaseModel):"""Response for agent operations (start/status/final)."""+ model_config = {"populate_by_name": True}+success: Optional[bool] = Noneid: Optional[str] = Nonestatus: Optional[Literal["processing", "completed", "failed"]] = None@@ -1465,6 +1539,18 @@ class AgentResponse(BaseModel):effort: Optional[Literal["low", "medium", "high"]] = Noneexpires_at: Optional[datetime] = Nonecredits_used: Optional[int] = None+ # Thread this run belongs to; pass it back to continue the conversation.+ thread_id: Optional[str] = Field(default=None, alias="threadId")+ # 1-based position of this run in its thread.+ thread_turn: Optional[int] = Field(default=None, alias="threadTurn")+ mode: Optional[Literal["extract", "chat"]] = None+ # Assistant text reply. Chat-mode runs answer here instead of in `data`.+ message: Optional[str] = None+ suggestions: Optional[List[AgentSuggestion]] = None+ pending_approval: Optional[PendingApproval] = Field(+ default=None, alias="pendingApproval"+ )+ exchange: Optional[AgentExchangeSummary] = Noneclass AgentListItemSettings(BaseModel):@@ -1516,6 +1602,56 @@ class AgentListResponse(BaseModel):error: Optional[str] = None+class AgentThreadRun(BaseModel):+ """A single run of a thread, as returned by get_agent_thread."""++ model_config = {"populate_by_name": True, "extra": "allow"}++ id: Optional[str] = None+ turn: Optional[int] = None+ mode: Optional[Literal["extract", "chat"]] = None+ prompt: Optional[str] = None+ urls: Optional[List[str]] = None+ # Trailing underscore because `schema` shadows a BaseModel attribute.+ schema_: Optional[Any] = Field(default=None, alias="schema")+ effort: Optional[Literal["low", "medium", "high"]] = None+ # Plain str, not a Literal: the run vocabulary is server-owned.+ status: Optional[str] = None+ created_at: Optional[str] = Field(default=None, alias="createdAt")+ finished_at: Optional[str] = Field(default=None, alias="finishedAt")+ credits_used: Optional[int] = Field(default=None, alias="creditsUsed")+ message: Optional[str] = None+ # Only present when the request asked for include_data.+ data: Optional[Any] = None+ suggestions: Optional[List[AgentSuggestion]] = None+ pending_approval: Optional[PendingApproval] = Field(+ default=None, alias="pendingApproval"+ )+ exchange: Optional[AgentExchangeSummary] = None+++class AgentThread(BaseModel):+ """A thread and its runs, oldest turn first."""++ model_config = {"populate_by_name": True, "extra": "allow"}++ id: Optional[str] = None+ created_at: Optional[str] = Field(default=None, alias="createdAt")+ updated_at: Optional[str] = Field(default=None, alias="updatedAt")+ status: Optional[Literal["idle", "running"]] = None+ runs: Optional[List[AgentThreadRun]] = None+++class AgentThreadResponse(BaseModel):+ """Response from GET /v2/agent/threads/{thread_id}."""++ model_config = {"populate_by_name": True}++ success: Optional[bool] = None+ thread: Optional[AgentThread] = None+ error: Optional[str] = None++# Agent trace types (GET /v2/agent/{job_id}/trace).# These mirror the agent service's canonical event schema (schemaVersion 1):# usage.recorded events are withheld server-side and agent.started carries no