Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

(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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 request
const 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.ts
index 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 = z
effort: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.py
new file mode 100644
index 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.py
index 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's
threat protection policy
audit_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 sent
Returns:
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's
threat protection policy
audit_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 sent
Returns:
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.py
index 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.py
index 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, Union
import time
from ..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.py
index 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, Union
import asyncio
from ...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.py
index 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] = None
id: Optional[str] = None
status: Optional[Literal["processing", "completed", "failed"]] = None
@@ -1465,6 +1539,18 @@ class AgentResponse(BaseModel):
effort: Optional[Literal["low", "medium", "high"]] = None
expires_at: Optional[datetime] = None
credits_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] = None
class 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