Skip to content

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

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 = z
threadId: 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.ts
new file mode 100644
index 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.ts
index 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.py
new file mode 100644
index 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.py
index 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 one
mode: "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 one
mode: "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.py
index 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.py
index 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.py
index 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: