Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat: ab
Gergő Móricz2efd0ae22521
diff --git a/apps/api/src/controllers/v1/types.ts b/apps/api/src/controllers/v1/types.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 extractapi_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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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__.pyindex 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 projectlogger: logging.Logger = logging.getLogger("firecrawl")diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex 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_modulefrom .methods import batch as batch_methodsfrom .methods import usage as usage_methodsfrom .methods import extract as extract_module+from .methods import agent as agent_modulefrom .watcher import Watcherclass 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.pyindex 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 endpointsasync 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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] = Nonetokens_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 typesclass ConcurrencyCheck(BaseModel):"""Current concurrency and limits for the team/API key."""