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(agent): optional location.country for /v2/agent (#5183)
Rakshith Ramprakash8b5e3423a580
diff --git a/apps/api/src/controllers/v2/__tests__/agent-location.test.ts b/apps/api/src/controllers/v2/__tests__/agent-location.test.tsnew file mode 100644index 000000000..9c81431db--- /dev/null+++ b/apps/api/src/controllers/v2/__tests__/agent-location.test.ts@@ -0,0 +1,119 @@+vi.mock("../../../lib/crawl-regex", async () => {+ const { z } = await import("zod");+ return {+ addPathRegexIssues: vi.fn(),+ pathPatternsSchema: z.array(z.string()),+ };+});+import { agentController } from "../agent";+import { agentRequestSchema } from "../types";+vi.mock("../../../lib/logger", () => {+ const logger = { info: vi.fn(), error: vi.fn(), child: vi.fn() };+ logger.child.mockReturnValue(logger);+ return { logger };+});+vi.mock("../../../services/logging/log_job", () => ({ logRequest: vi.fn() }));+vi.mock("../../../lib/external-request-id", () => ({+ externalRequestId: () => undefined,+}));+vi.mock("../../../config", () => ({+ config: {+ EXTRACT_V3_BETA_URL: "https://agent.example",+ USE_DB_AUTHENTICATION: false,+ AGENT_INTEROP_SECRET: "test",+ },+}));+vi.mock("../../../db/rpc", () => ({ agentConsumeFreeRequestIfLeft: vi.fn() }));+vi.mock("../../../lib/threat-protection/request", () => ({+ resolveThreatProtection: vi.fn().mockResolvedValue({}),+ checkUrlsAgainstThreatPolicy: vi.fn(),+}));+vi.mock("../../../lib/scrape-billing", () => ({+ calculateThreatScanCredits: vi.fn(),+}));+vi.mock("../../../services/billing/credit_billing", () => ({+ billTeam: vi.fn(),+}));+vi.mock("../../../lib/siem-logging", () => ({+ emitRejectedScrapeActivityEvents: vi.fn(),+}));+vi.mock("../agent-thread", () => ({+ fetchAgentThread: vi.fn(),+ threadErrorFor: vi.fn(),+}));++describe("agentRequestSchema location", () => {+ const base = { prompt: "Find the pricing page" };++ it.each(["DE", "de", "Gb"])("accepts %s and lowercases it", country => {+ const parsed = agentRequestSchema.parse({ ...base, location: { country } });++ expect(parsed.location).toEqual({ country: country.toLowerCase() });+ });++ it("leaves location undefined when omitted", () => {+ const parsed = agentRequestSchema.parse(base);++ expect(parsed.location).toBeUndefined();+ });++ it.each(["XX", "us-whitelist", "us-generic", "", "DEU"])(+ "rejects country %j",+ country => {+ expect(() =>+ agentRequestSchema.parse({ ...base, location: { country } }),+ ).toThrow();+ },+ );++ it("rejects a location without a country", () => {+ expect(() => agentRequestSchema.parse({ ...base, location: {} })).toThrow();+ });++ it("rejects fields other than country", () => {+ expect(() =>+ agentRequestSchema.parse({+ ...base,+ location: { country: "DE", languages: ["de"] },+ }),+ ).toThrow();+ });+});++describe("agentController location passthrough", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ vi.stubGlobal(+ "fetch",+ vi.fn().mockResolvedValue({ status: 200, json: async () => ({}) }),+ );+ });+ afterEach(() => vi.unstubAllGlobals());++ const run = async (body: Record<string, unknown>) => {+ const req = {+ body,+ auth: { team_id: "team-test" },+ acuc: { flags: {}, api_key: "test-key" },+ };+ const res = { status: vi.fn().mockReturnThis(), json: vi.fn() };+ await agentController(req as any, res as any);+ expect(res.status).toHaveBeenCalledWith(200);+ return JSON.parse(vi.mocked(fetch).mock.calls[0][1]!.body as string);+ };++ it("forwards the lowercased country to the agent service", async () => {+ const body = await run({+ prompt: "Find the pricing page",+ location: { country: "DE" },+ });++ expect(body.location).toEqual({ country: "de" });+ });++ it("sends no location key when the caller omits it", async () => {+ const body = await run({ prompt: "Find the pricing page" });++ expect(body).not.toHaveProperty("location");+ });+});diff --git a/apps/api/src/controllers/v2/agent.ts b/apps/api/src/controllers/v2/agent.tsindex 8a2078d19..a2ee1ba02 100644--- a/apps/api/src/controllers/v2/agent.ts+++ b/apps/api/src/controllers/v2/agent.ts@@ -264,6 +264,7 @@ export async function agentController(threadId: req.body.threadId,mode: req.body.mode,exchange: req.body.exchange,+ location: req.body.location,}),},);diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.tsindex 04ce0b630..b7c96fbd6 100644--- a/apps/api/src/controllers/v2/browser.ts+++ b/apps/api/src/controllers/v2/browser.ts@@ -11,9 +11,8 @@ import {} from "../../lib/keyless";import { z } from "zod";import { config } from "../../config";-import { RequestWithAuth } from "./types";+import { countryLocationSchema, RequestWithAuth } from "./types";import { integrationSchema } from "../../utils/integration";-import { countries } from "../../lib/validate-country";import { isAgentInteropSecretValid } from "../../lib/agent-interop";import {getBrowserSession,@@ -52,17 +51,7 @@ export const browserCreateRequestSchema = z.object({saveChanges: z.boolean().default(true),}).optional(),- location: z- .strictObject({- country: z- .string()- .refine(- value => Object.keys(countries).includes(value.toUpperCase()),- "Invalid country code. Use a valid ISO 3166-1 alpha-2 country code.",- )- .transform(value => value.toLowerCase()),- })- .optional(),+ location: countryLocationSchema.optional(),__agentInterop: z.object({auth: z.string(),diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.tsindex c051c9b9a..56d6afdce 100644--- a/apps/api/src/controllers/v2/types.ts+++ b/apps/api/src/controllers/v2/types.ts@@ -723,6 +723,16 @@ const locationSchema = z}).optional();+export const countryLocationSchema = z.strictObject({+ country: z+ .string()+ .refine(+ value => Object.keys(countries).includes(value.toUpperCase()),+ "Invalid country code. Use a valid ISO 3166-1 alpha-2 country code.",+ )+ .transform(value => value.toLowerCase()),+});+// Unified entity taxonomy exposed to callers. Maps to fire-privacy's// internal span kinds (PRIVATE_PERSON / EMAIL_ADDRESS / ACCOUNT_NUMBER /// etc.) inside the fire-privacy client. Names chosen to match the public@@ -1201,6 +1211,7 @@ export const agentRequestSchema = zthreadId: z.string().uuid().optional(),mode: z.enum(["extract", "chat"]).optional(),exchange: agentExchangeSchema.optional(),+ location: countryLocationSchema.optional(),})// 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 —diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-location.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-location.unit.test.tsnew file mode 100644index 000000000..5bf4e9a53--- /dev/null+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-location.unit.test.ts@@ -0,0 +1,34 @@+import { describe, test, expect, vi } from "vitest";+import { startAgent } from "../../../v2/methods/agent";++describe("JS SDK v2 agent location", () => {+ const post = () =>+ vi.fn(async () => ({+ status: 200,+ data: { success: true, id: "agent-1" },+ }));++ test("sends location when starting an agent", async () => {+ const http = { post: post() };++ await startAgent(http as any, {+ prompt: "Find the pricing page",+ location: { country: "DE" },+ });++ expect(http.post).toHaveBeenCalledWith("/v2/agent", {+ prompt: "Find the pricing page",+ location: { country: "DE" },+ });+ });++ test("omits location by default", async () => {+ const http = { post: post() };++ await startAgent(http as any, { prompt: "Find the pricing page" });++ expect(http.post).toHaveBeenCalledWith("/v2/agent", {+ prompt: "Find the pricing page",+ });+ });+});diff --git a/apps/js-sdk/firecrawl/src/v2/methods/agent.ts b/apps/js-sdk/firecrawl/src/v2/methods/agent.tsindex e2f323c28..f2a19d3a5 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/agent.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/agent.ts@@ -21,6 +21,8 @@ function prepareAgentPayload(args: {threadId?: string;mode?: AgentMode;exchange?: AgentExchangeOptions;+ /** Proxy country for every request the agent makes (ISO 3166-1 alpha-2). The agent cannot change it. */+ location?: { country: string };}): Record<string, unknown> {const body: Record<string, unknown> = {};if (args.urls) body.urls = args.urls;@@ -42,6 +44,7 @@ function prepareAgentPayload(args: {if (args.threadId != null) body.threadId = args.threadId;if (args.mode != null) body.mode = args.mode;if (args.exchange != null) body.exchange = args.exchange;+ if (args.location != null) body.location = args.location;return body;}diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_location.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_location.pynew file mode 100644index 000000000..2103d1cb6--- /dev/null+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_location.py@@ -0,0 +1,55 @@+import pytest++from firecrawl.v2.methods.agent import _prepare_agent_request, start_agent+from firecrawl.v2.methods.aio import agent as async_agent+++class _FakeResponse:+ ok = True+ status_code = 200++ def json(self):+ return {"success": True, "id": "agent-1"}+++class _FakeClient:+ def __init__(self):+ self.last_post = None++ def post(self, endpoint, payload):+ self.last_post = (endpoint, payload)+ return _FakeResponse()+++class _FakeAsyncClient(_FakeClient):+ async def post(self, endpoint, payload):+ return super().post(endpoint, payload)+++def test_prepare_includes_location():+ data = _prepare_agent_request(None, prompt="p", location={"country": "DE"})+ assert data["location"] == {"country": "DE"}+++def test_prepare_omits_location_by_default():+ data = _prepare_agent_request(None, prompt="p")+ assert "location" not in data+++def test_start_agent_sends_location():+ client = _FakeClient()+ start_agent(client, None, prompt="p", location={"country": "DE"})+ assert client.last_post == (+ "/v2/agent",+ {"prompt": "p", "location": {"country": "DE"}},+ )+++async def test_async_start_agent_sends_location():+ client = _FakeAsyncClient()+ await async_agent.start_agent(client, None, prompt="p", location={"country": "DE"})+ assert client.last_post == (+ "/v2/agent",+ {"prompt": "p", "location": {"country": "DE"}},+ )diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex 95e9d981a..648f35268 100644--- a/apps/python-sdk/firecrawl/v2/client.py+++ b/apps/python-sdk/firecrawl/v2/client.py@@ -1552,6 +1552,7 @@ class FirecrawlClient:thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,):"""Start an agent job (non-blocking).@@ -1570,6 +1571,8 @@ class FirecrawlClient:thread_id: Continue an existing thread instead of starting onemode: "extract" (default) or "chat"exchange: Data provider options, forwarded as sent+ location: Proxy country for every request the agent makes, as+ ``{"country": "DE"}`` (ISO 3166-1 alpha-2). The agent cannot change it.Returns:Response payload with job id/status (poll with get_agent_status)"""@@ -1589,6 +1592,7 @@ class FirecrawlClient:thread_id=thread_id,mode=mode,exchange=exchange,+ location=location,)def agent(@@ -1610,6 +1614,7 @@ class FirecrawlClient:thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,):"""Run an agent and wait until completion.@@ -1630,6 +1635,8 @@ class FirecrawlClient:thread_id: Continue an existing thread instead of starting onemode: "extract" (default) or "chat"exchange: Data provider options, forwarded as sent+ location: Proxy country for every request the agent makes, as+ ``{"country": "DE"}`` (ISO 3166-1 alpha-2). The agent cannot change it.Returns:Final agent response when completed"""@@ -1651,6 +1658,7 @@ class FirecrawlClient:thread_id=thread_id,mode=mode,exchange=exchange,+ location=location,)def get_agent_status(self, job_id: str):diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.pyindex 7ce44290f..7e8adec04 100644--- a/apps/python-sdk/firecrawl/v2/client_async.py+++ b/apps/python-sdk/firecrawl/v2/client_async.py@@ -876,6 +876,7 @@ class AsyncFirecrawlClient:thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,):return await async_agent.agent(self.async_http_client,@@ -895,6 +896,7 @@ class AsyncFirecrawlClient:thread_id=thread_id,mode=mode,exchange=exchange,+ location=location,)async def get_agent_status(self, job_id: str):@@ -917,6 +919,7 @@ class AsyncFirecrawlClient:thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,):return await async_agent.start_agent(self.async_http_client,@@ -934,6 +937,7 @@ class AsyncFirecrawlClient:thread_id=thread_id,mode=mode,exchange=exchange,+ location=location,)async def cancel_agent(self, job_id: str) -> bool:diff --git a/apps/python-sdk/firecrawl/v2/methods/agent.py b/apps/python-sdk/firecrawl/v2/methods/agent.pyindex 4e64d59bd..e48e121ad 100644--- a/apps/python-sdk/firecrawl/v2/methods/agent.py+++ b/apps/python-sdk/firecrawl/v2/methods/agent.py@@ -33,6 +33,7 @@ def _prepare_agent_request(thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,) -> Dict[str, Any]:body: Dict[str, Any] = {}if urls is not None:@@ -78,6 +79,8 @@ def _prepare_agent_request(if isinstance(exchange, dict)else exchange.model_dump(by_alias=True, exclude_none=True))+ if location is not None:+ body["location"] = {"country": location["country"]}return body@@ -107,6 +110,7 @@ def start_agent(thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,) -> AgentResponse:body = _prepare_agent_request(urls,@@ -123,6 +127,7 @@ def start_agent(thread_id=thread_id,mode=mode,exchange=exchange,+ location=location,)resp = client.post("/v2/agent", body)if not resp.ok:@@ -202,6 +207,7 @@ def agent(thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,) -> AgentResponse:started = start_agent(client,@@ -219,6 +225,7 @@ def agent(thread_id=thread_id,mode=mode,exchange=exchange,+ location=location,)job_id = getattr(started, "id", None)if not job_id:diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/agent.py b/apps/python-sdk/firecrawl/v2/methods/aio/agent.pyindex d4ce238cb..ae03ac07c 100644--- a/apps/python-sdk/firecrawl/v2/methods/aio/agent.py+++ b/apps/python-sdk/firecrawl/v2/methods/aio/agent.py@@ -33,6 +33,7 @@ def _prepare_agent_request(thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,) -> Dict[str, Any]:body: Dict[str, Any] = {}if urls is not None:@@ -78,6 +79,8 @@ def _prepare_agent_request(if isinstance(exchange, dict)else exchange.model_dump(by_alias=True, exclude_none=True))+ if location is not None:+ body["location"] = {"country": location["country"]}return body@@ -107,6 +110,7 @@ async def start_agent(thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,) -> AgentResponse:body = _prepare_agent_request(urls,@@ -123,6 +127,7 @@ async def start_agent(thread_id=thread_id,mode=mode,exchange=exchange,+ location=location,)resp = await client.post("/v2/agent", body)if resp.status_code >= 400:@@ -202,6 +207,7 @@ async def agent(thread_id: Optional[str] = None,mode: Optional[Literal["extract", "chat"]] = None,exchange: Optional[Union[AgentExchangeOptions, Dict[str, Any]]] = None,+ location: Optional[Dict[str, str]] = None,) -> AgentResponse:started = await start_agent(client,@@ -219,6 +225,7 @@ async def agent(thread_id=thread_id,mode=mode,exchange=exchange,+ location=location,)job_id = getattr(started, "id", None)if not job_id: