Skip to content

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

feat: ab

Gergő Móricz2efd0ae22521
diff --git a/apps/api/src/controllers/v1/types.ts b/apps/api/src/controllers/v1/types.ts
index 013b54901..423877100 100644
--- a/apps/api/src/controllers/v1/types.ts
+++ b/apps/api/src/controllers/v1/types.ts
@@ -1255,6 +1255,7 @@ export type TeamFlags = {
ipWhitelist?: boolean;
skipCountryCheck?: boolean;
extractV3Beta?: boolean;
+ agentBeta?: boolean;
} | null;
export type AuthCreditUsageChunkFromTeam = Omit<
diff --git a/apps/api/src/controllers/v2/agent-status.ts b/apps/api/src/controllers/v2/agent-status.ts
new file mode 100644
index 000000000..dc2619105
--- /dev/null
+++ b/apps/api/src/controllers/v2/agent-status.ts
@@ -0,0 +1,47 @@
+import { Response } from "express";
+import { AgentStatusResponse, RequestWithAuth } from "./types";
+import {
+ supabaseGetAgentByIdDirect,
+ supabaseGetAgentRequestByIdDirect,
+} from "../../lib/supabase-jobs";
+import { logger as _logger } from "../../lib/logger";
+import { getJobFromGCS } from "../../lib/gcs-jobs";
+
+export async function agentStatusController(
+ req: RequestWithAuth<{ jobId: string }, AgentStatusResponse, any>,
+ res: Response<AgentStatusResponse>,
+) {
+ const agentRequest = await supabaseGetAgentRequestByIdDirect(
+ req.params.jobId,
+ );
+
+ if (!agentRequest || agentRequest.team_id !== req.auth.team_id) {
+ return res.status(404).json({
+ success: false,
+ error: "Extract job not found",
+ });
+ }
+
+ const agent = await supabaseGetAgentByIdDirect(req.params.jobId);
+
+ let data: any = undefined;
+ if (agent.is_successful) {
+ data = await getJobFromGCS(agent.id);
+ }
+
+ return res.status(200).json({
+ success: true,
+ status: !agent
+ ? "processing"
+ : agent.is_successful
+ ? "completed"
+ : "failed",
+ error: agent?.error || undefined,
+ data,
+ expiresAt: new Date(
+ new Date(agent?.created_at ?? agentRequest.created_at).getTime() +
+ 1000 * 60 * 60 * 24,
+ ).toISOString(),
+ creditsUsed: agent?.credits_cost,
+ });
+}
diff --git a/apps/api/src/controllers/v2/agent.ts b/apps/api/src/controllers/v2/agent.ts
new file mode 100644
index 000000000..521e1031d
--- /dev/null
+++ b/apps/api/src/controllers/v2/agent.ts
@@ -0,0 +1,106 @@
+import { v7 as uuidv7 } from "uuid";
+import { Response } from "express";
+import {
+ AgentRequest,
+ AgentResponse,
+ RequestWithAuth,
+ agentRequestSchema,
+} from "./types";
+import { logger as _logger } from "../../lib/logger";
+import { logRequest } from "../../services/logging/log_job";
+import { config } from "../../config";
+
+export async function agentController(
+ req: RequestWithAuth<{}, AgentResponse, AgentRequest>,
+ res: Response<AgentResponse>,
+) {
+ const agentId = uuidv7();
+ const logger = _logger.child({
+ agentId,
+ jobId: agentId,
+ teamId: req.auth.team_id,
+ team_id: req.auth.team_id,
+ module: "api/v2",
+ method: "agentController",
+ zeroDataRetention: req.acuc?.flags?.forceZDR,
+ });
+
+ const originalRequest = { ...req.body };
+ req.body = agentRequestSchema.parse(req.body);
+
+ if (req.acuc?.flags?.forceZDR) {
+ return res.status(400).json({
+ success: false,
+ error:
+ "Your team has zero data retention enabled. This is not supported on extract. Please contact [email protected] to unblock this feature.",
+ });
+ }
+
+ _logger.info("Agent starting...", {
+ request: req.body,
+ originalRequest,
+ subId: req.acuc?.sub_id,
+ zeroDataRetention: req.acuc?.flags?.forceZDR,
+ });
+
+ if (!config.EXTRACT_V3_BETA_URL) {
+ return res.status(400).json({
+ success: false,
+ error: "Agent beta is not enabled.",
+ });
+ }
+
+ if (!req.acuc?.flags?.extractV3Beta && !req.acuc?.flags?.agentBeta) {
+ return res.status(400).json({
+ success: false,
+ error:
+ "Agent beta is not enabled for your team. Please contact [email protected] to join the beta.",
+ });
+ }
+
+ await logRequest({
+ id: agentId,
+ kind: "agent",
+ api_version: "v2",
+ team_id: req.auth.team_id,
+ origin: req.body.origin ?? "api",
+ integration: req.body.integration,
+ target_hint: req.body.urls?.[0] ?? req.body.prompt ?? "",
+ zeroDataRetention: false, // not supported for agent
+ api_key_id: req.acuc?.api_key_id ?? null,
+ });
+
+ const passthrough = await fetch(
+ config.EXTRACT_V3_BETA_URL + "/internal/extracts",
+ {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ id: agentId,
+ urls: req.body.urls,
+ schema: req.body.schema,
+ prompt: req.body.prompt,
+ }),
+ },
+ );
+
+ if (passthrough.status !== 200) {
+ const text = await passthrough.text();
+
+ logger.error("Failed to passthrough agent request.", {
+ status: passthrough.status,
+ text,
+ });
+ return res.status(500).json({
+ success: false,
+ error: "Failed to passthrough agent request.",
+ });
+ }
+
+ return res.status(200).json({
+ success: true,
+ id: agentId,
+ });
+}
diff --git a/apps/api/src/controllers/v2/extract-status.ts b/apps/api/src/controllers/v2/extract-status.ts
index 0fbfc583f..3d28dac5a 100644
--- a/apps/api/src/controllers/v2/extract-status.ts
+++ b/apps/api/src/controllers/v2/extract-status.ts
@@ -5,6 +5,7 @@ import { getExtract, getExtractExpiry } from "../../lib/extract/extract-redis";
import { getExtractQueue } from "../../services/queue-service";
import { ExtractResult } from "../../lib/extract/extraction-service";
import {
+ supabaseGetAgentByIdDirect,
supabaseGetExtractByIdDirect,
supabaseGetExtractRequestByIdDirect,
} from "../../lib/supabase-jobs";
@@ -44,8 +45,6 @@ async function getExtractJob(
: null) as Promise<DBExtract | null>,
]);
- console.log("JOBS", [bullJob, gcsJob, dbExtract]);
-
if (!bullJob && !dbExtract) return null;
// Extract results are stored in GCS, not in the DB
@@ -92,6 +91,31 @@ export async function extractStatusController(
});
}
+ if (extractRequest.kind === "agent") {
+ const agent = await supabaseGetAgentByIdDirect(req.params.jobId);
+
+ let data: any = undefined;
+ if (agent?.is_successful) {
+ data = await getJobFromGCS(agent.id);
+ }
+
+ return res.status(200).json({
+ success: true,
+ status: !agent
+ ? "processing"
+ : agent.is_successful
+ ? "completed"
+ : "failed",
+ error: agent?.error || undefined,
+ data,
+ expiresAt: new Date(
+ new Date(agent?.created_at ?? extractRequest.created_at).getTime() +
+ 1000 * 60 * 60 * 24,
+ ).toISOString(),
+ creditsUsed: agent?.credits_cost,
+ });
+ }
+
let data: ExtractResult | [] = [];
let status: string = "processing";
diff --git a/apps/api/src/controllers/v2/extract.ts b/apps/api/src/controllers/v2/extract.ts
index 28ddf100b..c48997ca2 100644
--- a/apps/api/src/controllers/v2/extract.ts
+++ b/apps/api/src/controllers/v2/extract.ts
@@ -52,7 +52,7 @@ export async function extractController(
if (!config.EXTRACT_V3_BETA_URL) {
return res.status(400).json({
success: false,
- error: "Extract v3 beta is not enabled.",
+ error: "Agent beta is not enabled.",
});
}
@@ -60,25 +60,25 @@ export async function extractController(
return res.status(400).json({
success: false,
error:
- "Extract v3 beta is not enabled for your team. Please contact [email protected] to join the beta.",
+ "Agent beta is not enabled for your team. Please contact [email protected] to join the beta.",
});
}
if (!req.body.prompt) {
return res.status(400).json({
success: false,
- error: "Prompt is required for extract v3 beta.",
+ error: "Prompt is required for agent beta.",
});
}
await logRequest({
id: extractId,
- kind: "extract",
+ kind: "agent",
api_version: "v2",
team_id: req.auth.team_id,
origin: req.body.origin ?? "api",
integration: req.body.integration,
- target_hint: req.body.urls?.[0] ?? "",
+ target_hint: req.body.urls?.[0] ?? req.body.prompt ?? "",
zeroDataRetention: false, // not supported for extract
api_key_id: req.acuc?.api_key_id ?? null,
});
@@ -102,7 +102,7 @@ export async function extractController(
if (passthrough.status !== 200) {
const text = await passthrough.text();
- _logger.error("Failed to passthrough extract v3 beta request.", {
+ _logger.error("Failed to passthrough agent beta request.", {
status: passthrough.status,
text,
teamId: req.auth.team_id,
@@ -111,7 +111,7 @@ export async function extractController(
});
return res.status(500).json({
success: false,
- error: "Failed to passthrough extract v3 beta request.",
+ error: "Failed to passthrough agent beta request.",
});
}
diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.ts
index 4f2eac8e3..d9080c7e6 100644
--- a/apps/api/src/controllers/v2/types.ts
+++ b/apps/api/src/controllers/v2/types.ts
@@ -715,6 +715,33 @@ export const extractRequestSchema = extractOptions;
export type ExtractRequest = z.infer<typeof extractRequestSchema>;
export type ExtractRequestInput = z.input<typeof extractRequestSchema>;
+export const agentRequestSchema = z.strictObject({
+ urls: URL.array().optional(),
+ prompt: z.string().max(10000),
+ schema: z
+ .any()
+ .optional()
+ .refine(
+ val => {
+ if (!val) return true; // Allow undefined schema
+ try {
+ const validate = ajv.compile(val);
+ return typeof validate === "function";
+ } catch (e) {
+ return false;
+ }
+ },
+ {
+ error: "Invalid JSON schema.",
+ },
+ ),
+ origin: z.string().optional().prefault("api"),
+ integration: integrationSchema.optional().transform(val => val || null),
+});
+
+export type AgentRequest = z.infer<typeof agentRequestSchema>;
+// export type AgentRequestInput = z.input<typeof agentRequestSchema>;
+
const scrapeRequestSchemaBase = baseScrapeOptions.extend({
url: URL,
origin: z.string().optional().prefault("api"),
@@ -1053,6 +1080,24 @@ export interface ExtractResponse {
creditsUsed?: number;
}
+export type AgentResponse =
+ | ErrorResponse
+ | {
+ success: boolean;
+ id: string;
+ };
+
+export type AgentStatusResponse =
+ | ErrorResponse
+ | {
+ success: boolean;
+ status: "processing" | "completed" | "failed";
+ error?: string;
+ data?: any;
+ expiresAt: string;
+ creditsUsed?: number;
+ };
+
export type CrawlResponse =
| ErrorResponse
| {
diff --git a/apps/api/src/lib/supabase-jobs.ts b/apps/api/src/lib/supabase-jobs.ts
index fe22329f5..b9741e6ee 100644
--- a/apps/api/src/lib/supabase-jobs.ts
+++ b/apps/api/src/lib/supabase-jobs.ts
@@ -133,7 +133,44 @@ export const supabaseGetExtractRequestByIdDirect = async (
.from("requests")
.select("*")
.eq("id", extractId)
- .eq("kind", "extract")
+ .in("kind", ["extract", "agent"])
+ .single();
+
+ if (error) {
+ return null;
+ }
+
+ if (!data) {
+ return null;
+ }
+
+ return data;
+};
+
+export const supabaseGetAgentRequestByIdDirect = async (agentId: string) => {
+ const { data, error } = await supabase_service
+ .from("requests")
+ .select("*")
+ .eq("id", agentId)
+ .eq("kind", "agent")
+ .single();
+
+ if (error) {
+ return null;
+ }
+
+ if (!data) {
+ return null;
+ }
+
+ return data;
+};
+
+export const supabaseGetAgentByIdDirect = async (agentId: string) => {
+ const { data, error } = await supabase_service
+ .from("agents")
+ .select("*")
+ .eq("id", agentId)
.single();
if (error) {
diff --git a/apps/api/src/routes/shared.ts b/apps/api/src/routes/shared.ts
index 8e7dba30c..c8aa2246e 100644
--- a/apps/api/src/routes/shared.ts
+++ b/apps/api/src/routes/shared.ts
@@ -214,7 +214,8 @@ export function countryCheck(
Object.keys(req.body.scrapeOptions.headers).length > 0) ||
req.body.scrapeOptions?.agent ||
req.body.scrapeOptions?.jsonOptions?.agent ||
- req.body.scrapeOptions?.extract?.agent);
+ req.body.scrapeOptions?.extract?.agent ||
+ req.path.startsWith("/v2/agent"));
if (!couldBeRestricted) {
return next();
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index 68b39f45b..4325596aa 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -36,6 +36,8 @@ import { creditUsageHistoricalController } from "../controllers/v2/credit-usage-
import { tokenUsageHistoricalController } from "../controllers/v2/token-usage-historical";
import { paymentMiddleware } from "x402-express";
import { facilitator } from "@coinbase/x402";
+import { agentController } from "../controllers/v2/agent";
+import { agentStatusController } from "../controllers/v2/agent-status";
expressWs(express());
@@ -299,6 +301,22 @@ v2Router.get(
wrap(extractStatusController),
);
+v2Router.post(
+ "/agent",
+ authMiddleware(RateLimiterMode.Extract),
+ countryCheck,
+ checkCreditsMiddleware(20),
+ blocklistMiddleware,
+ wrap(agentController),
+);
+
+v2Router.get(
+ "/agent/:jobId",
+ authMiddleware(RateLimiterMode.ExtractStatus),
+ validateJobIdParam,
+ wrap(agentStatusController),
+);
+
v2Router.get(
"/team/credit-usage",
authMiddleware(RateLimiterMode.CrawlStatus),
diff --git a/apps/api/src/services/logging/log_job.ts b/apps/api/src/services/logging/log_job.ts
index 0287472aa..7d26584ce 100644
--- a/apps/api/src/services/logging/log_job.ts
+++ b/apps/api/src/services/logging/log_job.ts
@@ -152,7 +152,8 @@ type LoggedRequest = {
| "extract"
| "llmstxt"
| "deep_research"
- | "map";
+ | "map"
+ | "agent";
api_version: string;
team_id: string;
origin?: string;
diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.json
index bdf01ece8..7e2b049de 100644
--- a/apps/js-sdk/firecrawl/package.json
+++ b/apps/js-sdk/firecrawl/package.json
@@ -1,6 +1,6 @@
{
"name": "@mendable/firecrawl-js",
- "version": "4.8.4",
+ "version": "4.9.0",
"description": "JavaScript SDK for Firecrawl API",
"main": "dist/index.js",
"types": "dist/index.d.ts",
diff --git a/apps/js-sdk/firecrawl/src/v2/client.ts b/apps/js-sdk/firecrawl/src/v2/client.ts
index 15bd6f78c..d753526c1 100644
--- a/apps/js-sdk/firecrawl/src/v2/client.ts
+++ b/apps/js-sdk/firecrawl/src/v2/client.ts
@@ -19,6 +19,7 @@ import {
batchScrape as batchWaiter,
} from "./methods/batch";
import { startExtract, getExtractStatus, extract as extractWaiter } from "./methods/extract";
+import { startAgent, getAgentStatus, agent as agentWaiter } from "./methods/agent";
import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";
import type {
Document,
@@ -34,6 +35,8 @@ import type {
BatchScrapeResponse,
BatchScrapeJob,
ExtractResponse,
+ AgentResponse,
+ AgentStatusResponse,
CrawlOptions,
BatchScrapeOptions,
PaginationConfig,
@@ -262,6 +265,31 @@ export class FirecrawlClient {
return extractWaiter(this.http, args);
}
+ // Agent
+ /**
+ * Start an agent job (async).
+ * @param args Agent request (urls, prompt, schema).
+ * @returns Job id or processing state.
+ */
+ async startAgent(args: Parameters<typeof startAgent>[1]): Promise<AgentResponse> {
+ return startAgent(this.http, args);
+ }
+ /**
+ * Get agent job status/data.
+ * @param jobId Agent job id.
+ */
+ async getAgentStatus(jobId: string): Promise<AgentStatusResponse> {
+ return getAgentStatus(this.http, jobId);
+ }
+ /**
+ * Convenience waiter: start an agent and poll until it finishes.
+ * @param args Agent request plus waiter controls (pollInterval, timeout seconds).
+ * @returns Final agent response.
+ */
+ async agent(args: Parameters<typeof startAgent>[1] & { pollInterval?: number; timeout?: number }): Promise<AgentStatusResponse> {
+ return agentWaiter(this.http, args);
+ }
+
// Usage
/** Current concurrency usage. */
async getConcurrency() {
diff --git a/apps/js-sdk/firecrawl/src/v2/methods/agent.ts b/apps/js-sdk/firecrawl/src/v2/methods/agent.ts
new file mode 100644
index 000000000..34c04d79b
--- /dev/null
+++ b/apps/js-sdk/firecrawl/src/v2/methods/agent.ts
@@ -0,0 +1,71 @@
+import { type AgentResponse, type AgentStatusResponse } from "../types";
+import { HttpClient } from "../utils/httpClient";
+import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import type { ZodTypeAny } from "zod";
+
+function prepareAgentPayload(args: {
+ urls?: string[];
+ prompt: string;
+ schema?: Record<string, unknown> | ZodTypeAny;
+ integration?: string;
+}): Record<string, unknown> {
+ const body: Record<string, unknown> = {};
+ if (args.urls) body.urls = args.urls;
+ body.prompt = args.prompt;
+ if (args.schema != null) {
+ const s: any = args.schema;
+ const isZod = s && (typeof s.safeParse === "function" || typeof s.parse === "function") && s._def;
+ body.schema = isZod ? zodToJsonSchema(s) : args.schema;
+ }
+ if (args.integration && args.integration.trim()) body.integration = args.integration.trim();
+ return body;
+}
+
+export async function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse> {
+ const payload = prepareAgentPayload(args);
+ try {
+ const res = await http.post<AgentResponse>("/v2/agent", payload);
+ if (res.status !== 200) throwForBadResponse(res, "agent");
+ return res.data;
+ } catch (err: any) {
+ if (err?.isAxiosError) return normalizeAxiosError(err, "agent");
+ throw err;
+ }
+}
+
+export async function getAgentStatus(http: HttpClient, jobId: string): Promise<AgentStatusResponse> {
+ try {
+ const res = await http.get<AgentStatusResponse>(`/v2/agent/${jobId}`);
+ if (res.status !== 200) throwForBadResponse(res, "agent status");
+ return res.data;
+ } catch (err: any) {
+ if (err?.isAxiosError) return normalizeAxiosError(err, "agent status");
+ throw err;
+ }
+}
+
+export async function waitAgent(
+ http: HttpClient,
+ jobId: string,
+ pollInterval = 2,
+ timeout?: number
+): Promise<AgentStatusResponse> {
+ const start = Date.now();
+ while (true) {
+ const status = await getAgentStatus(http, jobId);
+ if (["completed", "failed", "cancelled"].includes(status.status || "")) return status;
+ if (timeout != null && Date.now() - start > timeout * 1000) return status;
+ await new Promise((r) => setTimeout(r, Math.max(1000, pollInterval * 1000)));
+ }
+}
+
+export async function agent(
+ http: HttpClient,
+ args: Parameters<typeof prepareAgentPayload>[0] & { pollInterval?: number; timeout?: number }
+): Promise<AgentStatusResponse> {
+ const started = await startAgent(http, args);
+ const jobId = started.id;
+ if (!jobId) return started as unknown as AgentStatusResponse;
+ return waitAgent(http, jobId, args.pollInterval ?? 2, args.timeout);
+}
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index 8e078a219..87523e64d 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -535,6 +535,21 @@ export interface ExtractResponse {
creditsUsed?: number;
}
+export interface AgentResponse {
+ success: boolean;
+ id: string;
+ error?: string;
+}
+
+export interface AgentStatusResponse {
+ success: boolean;
+ status: 'processing' | 'completed' | 'failed';
+ error?: string;
+ data?: unknown;
+ expiresAt: string;
+ creditsUsed?: number;
+}
+
export interface AgentOptions {
model: 'FIRE-1' | 'v3-beta';
}
diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.py
index 6b63fdae6..731418692 100644
--- a/apps/python-sdk/firecrawl/__init__.py
+++ b/apps/python-sdk/firecrawl/__init__.py
@@ -17,7 +17,7 @@ from .v1 import (
V1ChangeTrackingOptions,
)
-__version__ = "4.10.5"
+__version__ = "4.11.0"
# Define the logger for the Firecrawl project
logger: logging.Logger = logging.getLogger("firecrawl")
diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.py
index ce96dc254..80002a199 100644
--- a/apps/python-sdk/firecrawl/v2/client.py
+++ b/apps/python-sdk/firecrawl/v2/client.py
@@ -49,6 +49,7 @@ from .methods import map as map_module
from .methods import batch as batch_methods
from .methods import usage as usage_methods
from .methods import extract as extract_module
+from .methods import agent as agent_module
from .watcher import Watcher
class FirecrawlClient:
@@ -754,6 +755,75 @@ class FirecrawlClient:
"""
return extract_module.get_extract_status(self.http_client, job_id)
+ def start_agent(
+ self,
+ urls: Optional[List[str]] = None,
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+ ):
+ """Start an agent job (non-blocking).
+
+ Args:
+ urls: URLs to process (optional)
+ prompt: Natural-language instruction for the agent
+ schema: Target JSON schema for the output
+ integration: Integration tag/name
+ Returns:
+ Response payload with job id/status (poll with get_agent_status)
+ """
+ return agent_module.start_agent(
+ self.http_client,
+ urls,
+ prompt=prompt,
+ schema=schema,
+ integration=integration,
+ )
+
+ def agent(
+ self,
+ urls: Optional[List[str]] = None,
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+ poll_interval: int = 2,
+ timeout: Optional[int] = None,
+ ):
+ """Run an agent and wait until completion.
+
+ Args:
+ urls: URLs to process (optional)
+ prompt: Natural-language instruction for the agent
+ schema: Target JSON schema for the output
+ integration: Integration tag/name
+ poll_interval: Seconds between status checks
+ timeout: Maximum seconds to wait (None for no timeout)
+ Returns:
+ Final agent response when completed
+ """
+ return agent_module.agent(
+ self.http_client,
+ urls,
+ prompt=prompt,
+ schema=schema,
+ integration=integration,
+ poll_interval=poll_interval,
+ timeout=timeout,
+ )
+
+ def get_agent_status(self, job_id: str):
+ """Get the current status (and data if completed) of an agent job.
+
+ Args:
+ job_id: Agent job ID
+
+ Returns:
+ Agent response payload with status and optional data
+ """
+ return agent_module.get_agent_status(self.http_client, job_id)
+
def get_concurrency(self):
"""Get current concurrency and maximum allowed for this team/key (v2)."""
return usage_methods.get_concurrency(self.http_client)
diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.py
index a72ff5dc8..0012fb88c 100644
--- a/apps/python-sdk/firecrawl/v2/client_async.py
+++ b/apps/python-sdk/firecrawl/v2/client_async.py
@@ -44,6 +44,7 @@ from .methods.aio import search as async_search # type: ignore[attr-defined]
from .methods.aio import map as async_map # type: ignore[attr-defined]
from .methods.aio import usage as async_usage # type: ignore[attr-defined]
from .methods.aio import extract as async_extract # type: ignore[attr-defined]
+from .methods.aio import agent as async_agent # type: ignore[attr-defined]
from .watcher_async import AsyncWatcher
@@ -310,6 +311,46 @@ class AsyncFirecrawlClient:
integration=integration,
)
+ # Agent
+ async def agent(
+ self,
+ urls: Optional[List[str]] = None,
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+ poll_interval: int = 2,
+ timeout: Optional[int] = None,
+ ):
+ return await async_agent.agent(
+ self.async_http_client,
+ urls,
+ prompt=prompt,
+ schema=schema,
+ integration=integration,
+ poll_interval=poll_interval,
+ timeout=timeout,
+ )
+
+ async def get_agent_status(self, job_id: str):
+ return await async_agent.get_agent_status(self.async_http_client, job_id)
+
+ async def start_agent(
+ self,
+ urls: Optional[List[str]] = None,
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+ ):
+ return await async_agent.start_agent(
+ self.async_http_client,
+ urls,
+ prompt=prompt,
+ schema=schema,
+ integration=integration,
+ )
+
# Usage endpoints
async def get_concurrency(self):
from .methods.aio import usage as async_usage # type: ignore[attr-defined]
diff --git a/apps/python-sdk/firecrawl/v2/methods/agent.py b/apps/python-sdk/firecrawl/v2/methods/agent.py
new file mode 100644
index 000000000..ec9940331
--- /dev/null
+++ b/apps/python-sdk/firecrawl/v2/methods/agent.py
@@ -0,0 +1,102 @@
+from typing import Any, Dict, List, Optional
+import time
+
+from ..types import AgentResponse
+from ..utils.http_client import HttpClient
+from ..utils.error_handler import handle_response_error
+
+
+def _prepare_agent_request(
+ urls: Optional[List[str]],
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+) -> Dict[str, Any]:
+ body: Dict[str, Any] = {}
+ if urls is not None:
+ body["urls"] = urls
+ body["prompt"] = prompt
+ if schema is not None:
+ body["schema"] = schema
+ if integration is not None and str(integration).strip():
+ body["integration"] = str(integration).strip()
+ return body
+
+
+def _normalize_agent_response_payload(payload: Dict[str, Any]) -> Dict[str, Any]:
+ out = dict(payload)
+ if "expiresAt" in out and "expires_at" not in out:
+ out["expires_at"] = out["expiresAt"]
+ if "creditsUsed" in out and "credits_used" not in out:
+ out["credits_used"] = out["creditsUsed"]
+ return out
+
+
+def start_agent(
+ client: HttpClient,
+ urls: Optional[List[str]],
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+) -> AgentResponse:
+ body = _prepare_agent_request(
+ urls,
+ prompt=prompt,
+ schema=schema,
+ integration=integration,
+ )
+ resp = client.post("/v2/agent", body)
+ if not resp.ok:
+ handle_response_error(resp, "agent")
+ payload = _normalize_agent_response_payload(resp.json())
+ return AgentResponse(**payload)
+
+
+def get_agent_status(client: HttpClient, job_id: str) -> AgentResponse:
+ resp = client.get(f"/v2/agent/{job_id}")
+ if not resp.ok:
+ handle_response_error(resp, "agent-status")
+ payload = _normalize_agent_response_payload(resp.json())
+ return AgentResponse(**payload)
+
+
+def wait_agent(
+ client: HttpClient,
+ job_id: str,
+ *,
+ poll_interval: int = 2,
+ timeout: Optional[int] = None,
+) -> AgentResponse:
+ start_ts = time.time()
+ while True:
+ status = get_agent_status(client, job_id)
+ if status.status in ("completed", "failed", "cancelled"):
+ return status
+ if timeout is not None and (time.time() - start_ts) > timeout:
+ return status
+ time.sleep(max(1, poll_interval))
+
+
+def agent(
+ client: HttpClient,
+ urls: Optional[List[str]],
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+ poll_interval: int = 2,
+ timeout: Optional[int] = None,
+) -> AgentResponse:
+ started = start_agent(
+ client,
+ urls,
+ prompt=prompt,
+ schema=schema,
+ integration=integration,
+ )
+ job_id = getattr(started, "id", None)
+ if not job_id:
+ return started
+ return wait_agent(client, job_id, poll_interval=poll_interval, timeout=timeout)
diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/agent.py b/apps/python-sdk/firecrawl/v2/methods/aio/agent.py
new file mode 100644
index 000000000..1f346fbbb
--- /dev/null
+++ b/apps/python-sdk/firecrawl/v2/methods/aio/agent.py
@@ -0,0 +1,97 @@
+from typing import Any, Dict, List, Optional
+import asyncio
+
+from ...types import AgentResponse
+from ...utils.http_client_async import AsyncHttpClient
+
+
+def _prepare_agent_request(
+ urls: Optional[List[str]],
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+) -> Dict[str, Any]:
+ body: Dict[str, Any] = {}
+ if urls is not None:
+ body["urls"] = urls
+ body["prompt"] = prompt
+ if schema is not None:
+ body["schema"] = schema
+ if integration is not None and str(integration).strip():
+ body["integration"] = str(integration).strip()
+ return body
+
+
+def _normalize_agent_response_payload(payload: Dict[str, Any]) -> Dict[str, Any]:
+ out = dict(payload)
+ if "expiresAt" in out and "expires_at" not in out:
+ out["expires_at"] = out["expiresAt"]
+ if "creditsUsed" in out and "credits_used" not in out:
+ out["credits_used"] = out["creditsUsed"]
+ return out
+
+
+async def start_agent(
+ client: AsyncHttpClient,
+ urls: Optional[List[str]],
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+) -> AgentResponse:
+ body = _prepare_agent_request(
+ urls,
+ prompt=prompt,
+ schema=schema,
+ integration=integration,
+ )
+ resp = await client.post("/v2/agent", body)
+ payload = _normalize_agent_response_payload(resp.json())
+ return AgentResponse(**payload)
+
+
+async def get_agent_status(client: AsyncHttpClient, job_id: str) -> AgentResponse:
+ resp = await client.get(f"/v2/agent/{job_id}")
+ payload = _normalize_agent_response_payload(resp.json())
+ return AgentResponse(**payload)
+
+
+async def wait_agent(
+ client: AsyncHttpClient,
+ job_id: str,
+ *,
+ poll_interval: int = 2,
+ timeout: Optional[int] = None,
+) -> AgentResponse:
+ start_ts = asyncio.get_event_loop().time()
+ while True:
+ status = await get_agent_status(client, job_id)
+ if status.status in ("completed", "failed", "cancelled"):
+ return status
+ if timeout is not None and (asyncio.get_event_loop().time() - start_ts) > timeout:
+ return status
+ await asyncio.sleep(max(1, poll_interval))
+
+
+async def agent(
+ client: AsyncHttpClient,
+ urls: Optional[List[str]],
+ *,
+ prompt: str,
+ schema: Optional[Dict[str, Any]] = None,
+ integration: Optional[str] = None,
+ poll_interval: int = 2,
+ timeout: Optional[int] = None,
+) -> AgentResponse:
+ started = await start_agent(
+ client,
+ urls,
+ prompt=prompt,
+ schema=schema,
+ integration=integration,
+ )
+ job_id = getattr(started, "id", None)
+ if not job_id:
+ return started
+ return await wait_agent(client, job_id, poll_interval=poll_interval, timeout=timeout)
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 722fa3427..5b75c892a 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -778,6 +778,18 @@ class ExtractResponse(BaseModel):
credits_used: Optional[int] = None
tokens_used: Optional[int] = None
+
+class AgentResponse(BaseModel):
+ """Response for agent operations (start/status/final)."""
+
+ success: Optional[bool] = None
+ id: Optional[str] = None
+ status: Optional[Literal["processing", "completed", "failed"]] = None
+ data: Optional[Any] = None
+ error: Optional[str] = None
+ expires_at: Optional[datetime] = None
+ credits_used: Optional[int] = None
+
# Usage/limits types
class ConcurrencyCheck(BaseModel):
"""Current concurrency and limits for the team/API key."""