Skip to content

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

feat(api): default /v2/agent to spark-2, retire spark-1 presets (#4414)

Gergő Móriczb231f51e8cc8
diff --git a/apps/api/src/__tests__/snips/v2/agent-effort.test.ts b/apps/api/src/__tests__/snips/v2/agent-effort.test.ts
index f9866a188..7694b056e 100644
--- a/apps/api/src/__tests__/snips/v2/agent-effort.test.ts
+++ b/apps/api/src/__tests__/snips/v2/agent-effort.test.ts
@@ -41,20 +41,17 @@ const agentRaw = (body: Record<string, unknown>) =>
// 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.each(["spark-1-pro", "spark-1-mini"] as const)(
- "rejects effort with %s, which has no reasoning budget",
- async model => {
+ it(
+ "rejects an unknown model name",
+ async () => {
const response = await agentRaw({
urls: [TEST_SUITE_WEBSITE],
prompt: "What does this page offer?",
- model,
- effort: "low",
+ model: "spark-9-unreleased",
});
expect(response.statusCode).toBe(400);
expect(response.body.success).toBe(false);
- expect(response.body.error).toContain("effort");
- expect(response.body.error).toContain("spark-2");
},
scrapeTimeout,
);
@@ -151,7 +148,7 @@ describeIf(REQUIRES_FIRE_ENGINE && REQUIRES_AI && HAS_AGENT_BETA)(
);
it(
- "still uses the default model when the caller sends neither field",
+ "defaults to spark-2 when the caller sends neither field",
async () => {
const response = await agentRaw({
urls: [TEST_SUITE_WEBSITE],
@@ -169,6 +166,68 @@ describeIf(REQUIRES_FIRE_ENGINE && REQUIRES_AI && HAS_AGENT_BETA)(
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(
+ "redirects a retired spark-1 preset to spark-2",
+ async () => {
+ const response = await agentRaw({
+ urls: [TEST_SUITE_WEBSITE],
+ prompt: "What does this page offer?",
+ model: "spark-1-pro",
+ });
+
+ if (response.statusCode !== 200) {
+ console.warn(
+ "Agent request with model spark-1-pro 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,
+ );
+
+ // python-sdk < 4.37.1 crashes parsing a "spark-2" status response, so the
+ // status endpoint reports the old default to those clients instead. The
+ // origin tag is the only signal the server has, so these cases set it
+ // the way the real SDK would.
+ it(
+ "reports spark-1-pro to an incompatible python-sdk origin",
+ async () => {
+ const response = await agentRaw({
+ urls: [TEST_SUITE_WEBSITE],
+ prompt: "What does this page offer?",
+ origin: "[email protected]",
+ });
+
+ if (response.statusCode !== 200) {
+ console.warn(
+ "Agent request with python-sdk origin 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");
@@ -177,5 +236,34 @@ describeIf(REQUIRES_FIRE_ENGINE && REQUIRES_AI && HAS_AGENT_BETA)(
},
scrapeTimeout,
);
+
+ it(
+ "reports spark-2 to a compatible python-sdk origin",
+ async () => {
+ const response = await agentRaw({
+ urls: [TEST_SUITE_WEBSITE],
+ prompt: "What does this page offer?",
+ origin: "[email protected]",
+ });
+
+ if (response.statusCode !== 200) {
+ console.warn(
+ "Agent request with python-sdk origin 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,
+ );
},
);
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 82b8456a4..ff38e9132 100644
--- a/apps/api/src/controllers/v2/__tests__/agent-status.test.ts
+++ b/apps/api/src/controllers/v2/__tests__/agent-status.test.ts
@@ -118,17 +118,81 @@ describe("agentStatusController", () => {
expect(body.model).toBe("spark-2");
expect(body.effort).toBeUndefined();
});
+
+ it.each([
+ // python-sdk < 4.37.1 cannot parse "spark-2" and is lied to
+ ["[email protected]", "spark-1-pro"],
+ ["[email protected]", "spark-1-pro"],
+ ["[email protected]", "spark-1-pro"],
+ // a prerelease of the fix may predate the Literal widening, so it
+ // gets the lie too
+ ["[email protected]", "spark-1-pro"],
+ // everything else sees the real model
+ ["[email protected]", "spark-2"],
+ ["[email protected]", "spark-2"],
+ ["[email protected]", "spark-2"],
+ ["[email protected]", "spark-2"],
+ ["api", "spark-2"],
+ ] as const)(
+ "reports a spark-2 job to %s as %s",
+ async (origin, expectedModel) => {
+ (supabaseGetAgentRequestByIdDirect as Mock).mockResolvedValue({
+ team_id: "team-123",
+ created_at: "2025-01-01T00:00:00Z",
+ origin,
+ });
+ (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);
+ expect(res.json).toHaveBeenCalledWith(
+ expect.objectContaining({ model: expectedModel }),
+ );
+ },
+ );
+
+ it("keeps a genuine spark-1 model truthful even for old python-sdk clients", async () => {
+ (supabaseGetAgentRequestByIdDirect as Mock).mockResolvedValue({
+ team_id: "team-123",
+ created_at: "2025-01-01T00:00:00Z",
+ origin: "[email protected]",
+ });
+ (supabaseGetAgentByIdDirect as Mock).mockResolvedValue({
+ id: "job-123",
+ is_successful: false,
+ options: { model: "spark-1-mini" },
+ created_at: "2025-01-01T00:00:00Z",
+ });
+
+ const res = buildRes();
+ await agentStatusController(baseReq, res);
+
+ expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.json).toHaveBeenCalledWith(
+ expect.objectContaining({ model: "spark-1-mini" }),
+ );
+ });
});
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" });
+ it.each(["spark-1-pro", "spark-1-mini", "spark-2"] as const)(
+ "redirects %s to spark-2 and leaves effort undefined",
+ model => {
+ const parsed = agentRequestSchema.parse({ ...base, model });
- expect(parsed.model).toBe("spark-1-mini");
- expect(parsed.effort).toBeUndefined();
- });
+ expect(parsed.model).toBe("spark-2");
+ expect(parsed.effort).toBeUndefined();
+ },
+ );
it.each(["low", "medium", "high"] as const)(
"resolves effort %s to spark-2 and keeps the effort",
@@ -152,28 +216,32 @@ describe("agentRequestSchema model and effort resolution", () => {
});
it.each(["spark-1-pro", "spark-1-mini"] as const)(
- "rejects effort with %s, naming spark-2",
+ "accepts effort with retired preset %s, redirecting to spark-2",
model => {
- let message = "";
- try {
- agentRequestSchema.parse({ ...base, model, effort: "low" });
- } catch (error) {
- message = (error as { issues: { message: string }[] }).issues[0]
- .message;
- }
-
- expect(message).toContain("effort");
- expect(message).toContain("spark-2");
+ const parsed = agentRequestSchema.parse({
+ ...base,
+ model,
+ effort: "low",
+ });
+
+ expect(parsed.model).toBe("spark-2");
+ expect(parsed.effort).toBe("low");
},
);
- it("falls back to the default model when the caller sends neither field", () => {
+ it("defaults to spark-2 when the caller sends neither field", () => {
const parsed = agentRequestSchema.parse({ ...base });
- expect(parsed.model).toBe("spark-1-pro");
+ expect(parsed.model).toBe("spark-2");
expect(parsed.effort).toBeUndefined();
});
+ it("rejects an unknown model name", () => {
+ expect(() =>
+ agentRequestSchema.parse({ ...base, model: "spark-9-unreleased" }),
+ ).toThrow();
+ });
+
it("rejects an unknown effort level", () => {
expect(() =>
agentRequestSchema.parse({ ...base, effort: "extreme" }),
diff --git a/apps/api/src/controllers/v2/agent-status.ts b/apps/api/src/controllers/v2/agent-status.ts
index 4cee8f3ae..7337a4802 100644
--- a/apps/api/src/controllers/v2/agent-status.ts
+++ b/apps/api/src/controllers/v2/agent-status.ts
@@ -8,6 +8,38 @@ import { logger as _logger, logger } from "../../lib/logger";
import { getJobFromGCS } from "../../lib/gcs-jobs";
import { config } from "../../config";
+// python-sdk versions before 4.37.1 validate the status response's `model`
+// with pydantic as Literal["spark-1-pro", "spark-1-mini"], so any other value
+// raises ValidationError inside get_agent_status — which wait_agent() and the
+// blocking agent() wrapper both poll — killing the whole agent flow on the
+// first status check. Those versions predate spark-2, so a job they started
+// can only have requested a spark-1 preset or nothing at all; reporting the
+// old default back to them is wrong in telemetry but keeps their poll loop
+// alive. A python-sdk origin whose version does not parse cleanly is
+// treated as incompatible: the lie is cosmetic, the crash is not. The
+// version regex is end-anchored so a prerelease of the fix (e.g.
+// "4.37.1rc0", which may predate the Literal widening) also fails to
+// parse and gets lied to rather than crashed.
+const PYTHON_SDK_ORIGIN = /^python-sdk@(.+)$/;
+const PYTHON_SDK_SPARK_2_FIX = [4, 37, 1];
+
+function isIncompatiblePythonSdkOrigin(origin: unknown): boolean {
+ if (typeof origin !== "string") return false;
+ const sdk = PYTHON_SDK_ORIGIN.exec(origin);
+ if (!sdk) return false;
+ const version = /^(\d+)\.(\d+)\.(\d+)$/.exec(sdk[1]);
+ if (!version) return true;
+ const [major, minor, patch] = version.slice(1).map(Number);
+ return (
+ major < PYTHON_SDK_SPARK_2_FIX[0] ||
+ (major === PYTHON_SDK_SPARK_2_FIX[0] &&
+ minor < PYTHON_SDK_SPARK_2_FIX[1]) ||
+ (major === PYTHON_SDK_SPARK_2_FIX[0] &&
+ minor === PYTHON_SDK_SPARK_2_FIX[1] &&
+ patch < PYTHON_SDK_SPARK_2_FIX[2])
+ );
+}
+
export async function agentStatusController(
req: RequestWithAuth<{ jobId: string }, AgentStatusResponse, any>,
res: Response<AgentStatusResponse>,
@@ -76,6 +108,18 @@ export async function agentStatusController(
}
}
+ // Lie about the model to python-sdk versions that cannot parse "spark-2"
+ // (see isIncompatiblePythonSdkOrigin). Only spark-2 needs disguising — a
+ // genuine spark-1 preset name parses fine on every SDK version, so legacy
+ // rows keep their truthful value.
+ if (
+ model !== "spark-1-pro" &&
+ model !== "spark-1-mini" &&
+ isIncompatiblePythonSdkOrigin(agentRequest.origin)
+ ) {
+ model = "spark-1-pro";
+ }
+
let data: any = undefined;
if (agent?.is_successful) {
data = await getJobFromGCS(agent.id);
diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.ts
index d1f2e411c..94a83cc65 100644
--- a/apps/api/src/controllers/v2/types.ts
+++ b/apps/api/src/controllers/v2/types.ts
@@ -1030,35 +1030,20 @@ export const agentRequestSchema = z
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 effort without a
- // model resolves to spark-2 while effort against another preset is an
- // error.
+ // The spark-1 preset names stay accepted so existing callers keep working,
+ // but spark-1 is retired: the transform below runs every request on
+ // spark-2 regardless of what was sent.
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(),
})
- // spark-2 is the first model with a reasoning budget, so effort only pairs
- // with spark-2. Effort against an older preset is rejected rather than
- // silently upgrading the model the caller asked for.
- .refine(
- x =>
- x.effort === undefined || x.model === undefined || x.model === "spark-2",
- {
- error:
- "'effort' is only supported with model 'spark-2'. The spark-1 presets have no reasoning budget; omit 'model' or send 'spark-2' to set one.",
- },
- )
- // 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.
+ // 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 —
+ // with or without effort, with or without a model — runs spark-2.
.transform(x => ({
...x,
- model: x.model ?? (x.effort !== undefined ? "spark-2" : "spark-1-pro"),
+ model: "spark-2" as const,
}));
export type AgentRequest = z.infer<typeof agentRequestSchema>;