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
Agent: expose incomplete results in status and threads (#4812)
Rakshith Ramprakash2e6f6aa9089c
diff --git a/apps/api/src/controllers/v2/__tests__/agent-status.test.ts b/apps/api/src/controllers/v2/__tests__/agent-status.test.tsindex 8b32257c4..f0a6979ee 100644--- a/apps/api/src/controllers/v2/__tests__/agent-status.test.ts+++ b/apps/api/src/controllers/v2/__tests__/agent-status.test.ts@@ -131,6 +131,9 @@ describe("agentStatusController", () => {model: "spark-2",effort: "medium",data: { result: "ok" },+ partial: { stale: true },+ partialSchemaValid: false,+ stopReason: "credit_limit_reached",message: "Done",threadId: "thread-123",threadTurn: 2,@@ -152,6 +155,69 @@ describe("agentStatusController", () => {creditsUsed: 7,}),);+ const body = (res.json as Mock).mock.calls[0][0];+ expect(body).not.toHaveProperty("partial");+ expect(body).not.toHaveProperty("partialSchemaValid");+ expect(body).not.toHaveProperty("stopReason");+ });++ it("forwards a credit-limited partial without treating it as completed data", async () => {+ (getAgentJobAccess as Mock).mockResolvedValue({+ teamId: "team-123",+ expiresAtMs: Date.now() + 60_000,+ });+ (getExtractV3AgentStatus as Mock).mockResolvedValue({+ id: "job-123",+ success: true,+ status: "failed",+ error: "Agent reached max credits",+ data: { shouldNotAppear: true },+ stopReason: "credit_limit_reached",+ partial: { companies: [{ name: "Acme" }] },+ partialSchemaValid: false,+ model: "spark-2",+ });++ const res = buildRes();+ await agentStatusController(baseReq, res);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(res.json).toHaveBeenCalledWith(+ expect.objectContaining({+ status: "failed",+ data: undefined,+ stopReason: "credit_limit_reached",+ partial: { companies: [{ name: "Acme" }] },+ partialSchemaValid: false,+ }),+ );+ });++ it("does not expose a live processing checkpoint", async () => {+ (getAgentJobAccess as Mock).mockResolvedValue({+ teamId: "team-123",+ expiresAtMs: Date.now() + 60_000,+ });+ (getExtractV3AgentStatus as Mock).mockResolvedValue({+ id: "job-123",+ success: true,+ status: "processing",+ data: { companies: [{ name: "Acme" }] },+ partial: { companies: [{ name: "Acme" }] },+ partialSchemaValid: false,+ stopReason: "credit_limit_reached",+ model: "spark-2",+ });++ const res = buildRes();+ await agentStatusController(baseReq, res);++ const body = (res.json as Mock).mock.calls[0][0];+ expect(body.status).toBe("processing");+ expect(body.data).toBeUndefined();+ expect(body).not.toHaveProperty("partial");+ expect(body).not.toHaveProperty("partialSchemaValid");+ expect(body).not.toHaveProperty("stopReason");});it.each([diff --git a/apps/api/src/controllers/v2/agent-status.ts b/apps/api/src/controllers/v2/agent-status.tsindex 4c4bb7e84..b260ab77b 100644--- a/apps/api/src/controllers/v2/agent-status.ts+++ b/apps/api/src/controllers/v2/agent-status.ts@@ -98,7 +98,16 @@ export async function agentStatusController(success: true,status: agent.status === "success" ? "completed" : agent.status,error: agent.error,- data: agent.data,+ data: agent.status === "success" ? agent.data : undefined,+ // Checkpoints are internal while a job is running; only expose a partial+ // when the run has stopped without a completed result.+ ...(agent.status === "failed"+ ? {+ partial: agent.partial,+ partialSchemaValid: agent.partialSchemaValid,+ stopReason: agent.stopReason,+ }+ : {}),model,effort,threadId: thread.threadId,diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.tsindex 280d1021b..59cee1425 100644--- a/apps/api/src/controllers/v2/types.ts+++ b/apps/api/src/controllers/v2/types.ts@@ -1812,6 +1812,11 @@ export type AgentStatusResponse =status: "processing" | "completed" | "failed";error?: string;data?: any;+ /** Best-effort JSON on a failed run; `data` remains completed-only. */+ partial?: unknown;+ /** Only present when the caller supplied a JSON Schema. */+ partialSchemaValid?: boolean;+ stopReason?: "credit_limit_reached";model?: "spark-1-pro" | "spark-1-mini" | "spark-2";effort?: "low" | "medium" | "high";expiresAt: string;@@ -1846,6 +1851,9 @@ type AgentThreadRun = {message: string | null;// Only present when the request asked for includeData.data?: unknown;+ partial?: unknown;+ partialSchemaValid?: boolean;+ stopReason?: "credit_limit_reached";suggestions?: AgentSuggestion[] | null;pendingApproval?: AgentPendingApproval | null;exchange?: AgentExchangeSummary | null;diff --git a/apps/api/src/lib/extract-v3-status.ts b/apps/api/src/lib/extract-v3-status.tsindex edd14bb26..5effc65af 100644--- a/apps/api/src/lib/extract-v3-status.ts+++ b/apps/api/src/lib/extract-v3-status.ts@@ -5,6 +5,10 @@ type ExtractV3AgentStatus = {id: string;status: "processing" | "success" | "failed";data?: unknown;+ /** Incomplete JSON from an interrupted run; never a completed `data` value. */+ partial?: unknown;+ partialSchemaValid?: boolean;+ stopReason?: "credit_limit_reached";error?: string;model?: "spark-1-pro" | "spark-1-mini" | "spark-2";effort?: "low" | "medium" | "high";diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex fb0b6f8fc..b485d9e13 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -1627,6 +1627,11 @@ export interface AgentStatusResponse {status: "processing" | "completed" | "failed";error?: string;data?: unknown;+ /** Best-effort result on a failed run; never a completed `data` value. */+ partial?: unknown;+ /** Schema validity of `partial`, when a schema was supplied. */+ partialSchemaValid?: boolean;+ stopReason?: "credit_limit_reached";/*** Server-provided model name. Widened past the request-side union on* purpose: new models ship without an SDK release, so pinning this to known@@ -1672,6 +1677,9 @@ export interface AgentThreadRun {message: string | null;/** Only present when the request asked for includeData. */data?: unknown;+ partial?: unknown;+ partialSchemaValid?: boolean;+ stopReason?: "credit_limit_reached";suggestions?: AgentSuggestion[] | null;pendingApproval?: PendingApproval | null;exchange?: AgentExchangeSummary | null;diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex 8a2653000..f01591e24 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -1745,6 +1745,10 @@ class AgentResponse(BaseModel):id: Optional[str] = Nonestatus: Optional[Literal["processing", "completed", "failed"]] = Nonedata: Optional[Any] = None+ # Best-effort result on a failed run; never a completed `data` value.+ partial: Optional[Any] = None+ partial_schema_valid: Optional[bool] = Field(default=None, alias="partialSchemaValid")+ stop_reason: Optional[str] = Field(default=None, alias="stopReason")error: Optional[str] = None# Deliberately a plain str, not a Literal: this is server-provided and new# models ship without an SDK release, so a narrow type turns an unknown@@ -1838,6 +1842,9 @@ class AgentThreadRun(BaseModel):message: Optional[str] = None# Only present when the request asked for include_data.data: Optional[Any] = None+ partial: Optional[Any] = None+ partial_schema_valid: Optional[bool] = Field(default=None, alias="partialSchemaValid")+ stop_reason: Optional[str] = Field(default=None, alias="stopReason")suggestions: Optional[List[AgentSuggestion]] = Nonepending_approval: Optional[PendingApproval] = Field(default=None, alias="pendingApproval"diff --git a/apps/python-sdk/tests/test_agent_partial_types.py b/apps/python-sdk/tests/test_agent_partial_types.pynew file mode 100644index 000000000..f288ba1ee--- /dev/null+++ b/apps/python-sdk/tests/test_agent_partial_types.py@@ -0,0 +1,34 @@+from firecrawl.v2.types import AgentResponse, AgentThreadRun+++def test_agent_status_preserves_credit_limit_partial():+ response = AgentResponse.model_validate(+ {+ "success": True,+ "status": "failed",+ "stopReason": "credit_limit_reached",+ "partial": {"companies": [{"name": "Acme"}]},+ "partialSchemaValid": False,+ }+ )++ assert response.data is None+ assert response.stop_reason == "credit_limit_reached"+ assert response.partial == {"companies": [{"name": "Acme"}]}+ assert response.partial_schema_valid is False+++def test_agent_thread_run_preserves_partial_for_continuation():+ run = AgentThreadRun.model_validate(+ {+ "id": "job-123",+ "status": "credit_limit_reached",+ "stopReason": "credit_limit_reached",+ "partial": {"companies": [{"name": "Acme"}]},+ "partialSchemaValid": False,+ }+ )++ assert run.partial == {"companies": [{"name": "Acme"}]}+ assert run.partial_schema_valid is False+ assert run.stop_reason == "credit_limit_reached"