Skip to content

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

Add effort parameter to POST /v2/agent (#4361)

claude[bot]a4bcab66ffca
diff --git a/README.md b/README.md
index 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 |
+
```python
result = 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 websites
diff --git a/apps/api/src/__tests__/snips/v2/agent-effort.test.ts b/apps/api/src/__tests__/snips/v2/agent-effort.test.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;
};