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
Add effort parameter to POST /v2/agent (#4361)
claude[bot]a4bcab66ffca
diff --git a/README.md b/README.mdindex 21f26a3cb..6260269c0 100644--- a/README.md+++ b/README.md@@ -382,14 +382,37 @@ result = app.agent()```-#### Model Selection+#### Effort Selection-Choose between two models based on your needs:+Set how much reasoning the agent spends on the task:++| Effort | Best For |+|--------|----------|+| `low` | Simple lookups on one site |+| `medium` | Multi-step tasks on a few pages |+| `high` | Deep research, complex navigation, critical data |++```python+result = app.agent(+ prompt="Compare enterprise features across Firecrawl, Apify, and ScrapingBee",+ effort="high"+)+```++Every effort level runs the `spark-2` model. Effort changes the reasoning+budget, not the model.++#### Model Selection (Legacy)++`model` still works, and it stays supported. Send `model` or `effort`, not+both. A request with both fields returns a 400 error.| Model | Cost | Best For ||-------|------|----------|| `spark-1-mini` | 60% cheaper | Most tasks || `spark-1-pro` (default) | Standard | Complex research, critical data gathering |+| `spark-2` | See [pricing](https://docs.firecrawl.dev/features/agent) | The model that `effort` runs |+```pythonresult = app.agent(prompt="Compare enterprise features across Firecrawl, Apify, and ScrapingBee",@@ -397,6 +420,7 @@ result = app.agent()```+A request without `model` and without `effort` runs `spark-1-pro`.**When to use Pro:**- Comparing data across multiple websitesdiff --git a/apps/api/src/__tests__/snips/v2/agent-effort.test.ts b/apps/api/src/__tests__/snips/v2/agent-effort.test.tsnew file mode 100644index 000000000..2cb77cac9--- /dev/null+++ b/apps/api/src/__tests__/snips/v2/agent-effort.test.ts@@ -0,0 +1,150 @@+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";++// An accepted POST /v2/agent drives a browser and a model, so the cases that+// start a run 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. Those cases also forward to 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;++let identity: Identity;++beforeAll(async () => {+ identity = await idmux({+ name: "agent-effort",+ credits: 1000000,+ });+}, scrapeTimeout);++const agentRaw = (body: Record<string, unknown>) =>+ request(TEST_API_URL)+ .post("/v2/agent")+ .set("Authorization", `Bearer ${identity.apiKey}`)+ .set("Content-Type", "application/json")+ .send(body);++// agentRequestSchema.parse runs at the top of agentController, before the+// controller touches the agent service, a browser or a model. A rejected+// request therefore needs only the API server and an authenticated team, so+// these cases run everywhere instead of skipping with the live runs below.+describe("Agent effort parameter validation", () => {+ it(+ "rejects model and effort together",+ async () => {+ const response = await agentRaw({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "What does this page offer?",+ model: "spark-1-pro",+ effort: "low",+ });++ expect(response.statusCode).toBe(400);+ expect(response.body.success).toBe(false);+ expect(response.body.error).toContain("model");+ expect(response.body.error).toContain("effort");+ },+ scrapeTimeout,+ );++ it(+ "rejects an unknown effort level",+ async () => {+ const response = await agentRaw({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "What does this page offer?",+ effort: "extreme",+ });++ expect(response.statusCode).toBe(400);+ expect(response.body.success).toBe(false);+ },+ scrapeTimeout,+ );+});++describeIf(REQUIRES_FIRE_ENGINE && REQUIRES_AI && HAS_AGENT_BETA)(+ "Agent effort parameter",+ () => {+ // Each accepted request starts a real run. Cancel it so the test does not+ // pay for work nobody reads.+ const cancel = (jobId: string) =>+ request(TEST_API_URL)+ .delete(`/v2/agent/${jobId}`)+ .set("Authorization", `Bearer ${identity.apiKey}`);++ const statusOf = (jobId: string) =>+ request(TEST_API_URL)+ .get(`/v2/agent/${jobId}`)+ .set("Authorization", `Bearer ${identity.apiKey}`);++ it(+ "accepts effort alone and runs spark-2",+ async () => {+ const response = await agentRaw({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "What does this page offer?",+ effort: "low",+ });++ if (response.statusCode !== 200) {+ console.warn(+ "Agent request with effort did not succeed",+ JSON.stringify(response.body, null, 2),+ );+ }++ expect(response.statusCode).toBe(200);+ expect(response.body.success).toBe(true);+ expect(typeof response.body.id).toBe("string");++ const status = await statusOf(response.body.id);+ expect(status.statusCode).toBe(200);+ expect(status.body.model).toBe("spark-2");++ await cancel(response.body.id);+ },+ scrapeTimeout,+ );++ it(+ "still uses the default model when the caller sends neither field",+ async () => {+ const response = await agentRaw({+ urls: [TEST_SUITE_WEBSITE],+ prompt: "What does this page offer?",+ });++ if (response.statusCode !== 200) {+ console.warn(+ "Agent request without model or effort did not succeed",+ JSON.stringify(response.body, null, 2),+ );+ }++ expect(response.statusCode).toBe(200);+ expect(response.body.success).toBe(true);+ expect(typeof response.body.id).toBe("string");++ const status = await statusOf(response.body.id);+ expect(status.statusCode).toBe(200);+ expect(status.body.model).toBe("spark-1-pro");++ await cancel(response.body.id);+ },+ scrapeTimeout,+ );+ },+);diff --git a/apps/api/src/controllers/v2/__tests__/agent-status.test.ts b/apps/api/src/controllers/v2/__tests__/agent-status.test.tsindex 77be93e55..1ab41e579 100644--- a/apps/api/src/controllers/v2/__tests__/agent-status.test.ts+++ b/apps/api/src/controllers/v2/__tests__/agent-status.test.ts@@ -1,6 +1,7 @@import type { Mock } from "vitest";import type { Response } from "express";import { agentStatusController } from "../agent-status";+import { agentRequestSchema } from "../types";import type { RequestWithAuth } from "../types";import {supabaseGetAgentByIdDirect,@@ -75,4 +76,92 @@ describe("agentStatusController", () => {expect.objectContaining({ model: "spark-1-pro" }),);});+ it("returns effort from agent options", async () => {+ (supabaseGetAgentRequestByIdDirect as Mock).mockResolvedValue({+ team_id: "team-123",+ created_at: "2025-01-01T00:00:00Z",+ });+ (supabaseGetAgentByIdDirect as Mock).mockResolvedValue({+ id: "job-123",+ is_successful: true,+ options: { model: "spark-2", effort: "high" },+ created_at: "2025-01-01T00:00:00Z",+ });+ (getJobFromGCS as Mock).mockResolvedValue({ result: "ok" });++ const res = buildRes();+ await agentStatusController(baseReq, res);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(res.json).toHaveBeenCalledWith(+ expect.objectContaining({ model: "spark-2", effort: "high" }),+ );+ });++ it("leaves effort undefined when the agent options omit it", async () => {+ (supabaseGetAgentRequestByIdDirect as Mock).mockResolvedValue({+ team_id: "team-123",+ created_at: "2025-01-01T00:00:00Z",+ });+ (supabaseGetAgentByIdDirect as Mock).mockResolvedValue({+ id: "job-123",+ is_successful: false,+ options: { model: "spark-2" },+ created_at: "2025-01-01T00:00:00Z",+ });++ const res = buildRes();+ await agentStatusController(baseReq, res);++ expect(res.status).toHaveBeenCalledWith(200);+ const body = (res.json as Mock).mock.calls[0][0];+ expect(body.model).toBe("spark-2");+ expect(body.effort).toBeUndefined();+ });+});++describe("agentRequestSchema model and effort resolution", () => {+ const base = { prompt: "Find the pricing page" };++ it("keeps the sent model and leaves effort undefined", () => {+ const parsed = agentRequestSchema.parse({ ...base, model: "spark-1-mini" });++ expect(parsed.model).toBe("spark-1-mini");+ expect(parsed.effort).toBeUndefined();+ });++ it.each(["low", "medium", "high"] as const)(+ "resolves effort %s to spark-2 and keeps the effort",+ effort => {+ const parsed = agentRequestSchema.parse({ ...base, effort });++ expect(parsed.model).toBe("spark-2");+ expect(parsed.effort).toBe(effort);+ },+ );++ it("rejects model and effort together, naming both fields", () => {+ let message = "";+ try {+ agentRequestSchema.parse({ ...base, model: "spark-2", effort: "low" });+ } catch (error) {+ message = (error as { issues: { message: string }[] }).issues[0].message;+ }++ expect(message).toContain("model");+ expect(message).toContain("effort");+ });++ it("falls back to the default model when the caller sends neither field", () => {+ const parsed = agentRequestSchema.parse({ ...base });++ expect(parsed.model).toBe("spark-1-pro");+ expect(parsed.effort).toBeUndefined();+ });++ it("rejects an unknown effort level", () => {+ expect(() =>+ agentRequestSchema.parse({ ...base, effort: "extreme" }),+ ).toThrow();+ });});diff --git a/apps/api/src/controllers/v2/agent-status.ts b/apps/api/src/controllers/v2/agent-status.tsindex dc82300b2..4cee8f3ae 100644--- a/apps/api/src/controllers/v2/agent-status.ts+++ b/apps/api/src/controllers/v2/agent-status.ts@@ -26,11 +26,15 @@ export async function agentStatusController(const agent = await supabaseGetAgentByIdDirect(req.params.jobId);let model: "spark-1-pro" | "spark-1-mini" | "spark-2";+ // 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;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;} else {try {const optionsRequest = await fetch(@@ -54,10 +58,12 @@ export async function agentStatusController(});model = "spark-1-pro"; // fall back to this value} else {- model = ((await optionsRequest.json()).model ?? "spark-1-pro") as+ const options = await optionsRequest.json();+ model = (options.model ?? "spark-1-pro") as| "spark-1-pro"| "spark-1-mini"| "spark-2";+ effort = options.effort as "low" | "medium" | "high" | undefined;}} catch (error) {logger.warn("Failed to get agent request details", {@@ -85,6 +91,7 @@ export async function agentStatusController(error: agent?.error || undefined,data,model,+ effort,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.ts b/apps/api/src/controllers/v2/agent.tsindex 25d3fdc61..38d77aa3c 100644--- a/apps/api/src/controllers/v2/agent.ts+++ b/apps/api/src/controllers/v2/agent.ts@@ -180,6 +180,7 @@ export async function agentController(strictConstrainToURLs: req.body.strictConstrainToURLs ?? undefined,webhook: req.body.webhook ?? undefined,model: req.body.model,+ effort: req.body.effort,auditMetadata: req.body.auditMetadata,}),},diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.tsindex b3349eb2c..0714db55a 100644--- a/apps/api/src/controllers/v2/types.ts+++ b/apps/api/src/controllers/v2/types.ts@@ -999,42 +999,59 @@ const agentWebhookSchema = createWebhookSchema(["cancelled",]);-export const agentRequestSchema = z.strictObject({- urls: URL.array().optional(),- prompt: z.string().max(10000),- schema: z- .any()- .optional()- .superRefine((val, ctx) => {- if (!val) return; // Allow undefined schema- try {- agentAjv.compile(val);- } catch (e) {- const message =- e instanceof Error- ? e.message- : typeof e === "string"- ? e- : "Unknown error";- ctx.addIssue({- code: "custom",- message: `Invalid JSON schema: ${message}`,- });- }- }),- origin: z.string().optional().prefault("api"),- integration: integrationSchema.optional().transform(val => val || null),- maxCredits: z.number().optional(),- strictConstrainToURLs: z.boolean().optional(),- webhook: agentWebhookSchema.optional(),-- overrideWhitelist: z.string().optional(),- model: z- .enum(["spark-1-pro", "spark-1-mini", "spark-2"])- .default("spark-1-pro"),- threatProtection: threatProtectionOverrideSchema.optional(),- auditMetadata: auditMetadataSchema.optional(),-});+export const agentRequestSchema = z+ .strictObject({+ urls: URL.array().optional(),+ prompt: z.string().max(10000),+ schema: z+ .any()+ .optional()+ .superRefine((val, ctx) => {+ if (!val) return; // Allow undefined schema+ try {+ agentAjv.compile(val);+ } catch (e) {+ const message =+ e instanceof Error+ ? e.message+ : typeof e === "string"+ ? e+ : "Unknown error";+ ctx.addIssue({+ code: "custom",+ message: `Invalid JSON schema: ${message}`,+ });+ }+ }),+ origin: z.string().optional().prefault("api"),+ integration: integrationSchema.optional().transform(val => val || null),+ maxCredits: z.number().optional(),+ strictConstrainToURLs: z.boolean().optional(),+ webhook: agentWebhookSchema.optional(),++ overrideWhitelist: z.string().optional(),+ // Optional, not defaulted: the resolver below must tell "the caller sent a+ // model" apart from "the caller sent nothing", because sending both model+ // and effort is an error rather than a precedence rule.+ model: z.enum(["spark-1-pro", "spark-1-mini", "spark-2"]).optional(),+ effort: z.enum(["low", "medium", "high"]).optional(),+ threatProtection: threatProtectionOverrideSchema.optional(),+ auditMetadata: auditMetadataSchema.optional(),+ })+ .refine(x => !(x.model !== undefined && x.effort !== undefined), {+ error:+ "Send either 'model' or 'effort', not both. 'model' picks a preset and 'effort' picks a reasoning budget.",+ })+ // Every effort level runs spark-2. The older presets have no trace or+ // snapshot endpoint and use a different credit ladder, so spreading effort+ // across presets would change features and price per level. Effort sets the+ // reasoning budget inside spark-2 instead. A request that sends neither+ // field keeps the endpoint's own default preset, so this schema introduces+ // no default of its own.+ .transform(x => ({+ ...x,+ model: x.model ?? (x.effort !== undefined ? "spark-2" : "spark-1-pro"),+ }));export type AgentRequest = z.infer<typeof agentRequestSchema>;// export type AgentRequestInput = z.input<typeof agentRequestSchema>;@@ -1513,6 +1530,7 @@ export type AgentStatusResponse =error?: string;data?: any;model?: "spark-1-pro" | "spark-1-mini" | "spark-2";+ effort?: "low" | "medium" | "high";expiresAt: string;creditsUsed?: number;};