Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

feat(interact): add langsmith grouped by browser session (#3357)

Developers Digestdb6f9cf24dac
diff --git a/apps/api/package.json b/apps/api/package.json
index 578dbe2a9..0841e65a9 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -122,6 +122,7 @@
"joplin-turndown-plugin-gfm": "^1.0.12",
"jsdom": "^26.0.0",
"koffi": "^2.9.0",
+ "langsmith": "^0.5.18",
"lodash": "^4.18.0",
"marked": "^14.1.2",
"ollama-ai-provider": "^1.2.0",
diff --git a/apps/api/pnpm-lock.yaml b/apps/api/pnpm-lock.yaml
index f3617406a..9a0848db7 100644
--- a/apps/api/pnpm-lock.yaml
+++ b/apps/api/pnpm-lock.yaml
@@ -177,6 +177,9 @@ importers:
koffi:
specifier: ^2.9.0
version: 2.9.0
+ langsmith:
+ specifier: ^0.5.18
lodash:
specifier: ^4.18.0
version: 4.18.1
@@ -3676,6 +3679,9 @@ packages:
resolution: {integrity: sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==}
engines: {node: '>=6'}
+ resolution: {integrity: sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==}
+
resolution: {integrity: sha512-GWkBvjiSZK87ELrYOSESUYeVIc9mvLLf/nXalMOS5dYrgZq9o5OVkbZAVM06CVxYsCwH9BDZFPlQTlPA1j4ahA==}
@@ -4414,6 +4420,26 @@ packages:
resolution: {integrity: sha512-Xq9nH7KlWZmXAtodXDDRE7vs6DU1gTU8zYDHDiWLSip45Egwq3plLHzPn27NgvzL2r1LMPC1vdqh98sQxtqj4A==}
+ resolution: {integrity: sha512-3zuZUWffTHQ+73EAwnodADtf534VNEZUpXr9jC12qyG8/IQuJET7PRsCpTb9wX2lmBspakwLUpqpj3tNm/0bVA==}
+ peerDependencies:
+ '@opentelemetry/api': '*'
+ '@opentelemetry/exporter-trace-otlp-proto': '*'
+ '@opentelemetry/sdk-trace-base': '*'
+ openai: '*'
+ ws: '>=7'
+ peerDependenciesMeta:
+ '@opentelemetry/api':
+ optional: true
+ '@opentelemetry/exporter-trace-otlp-proto':
+ optional: true
+ '@opentelemetry/sdk-trace-base':
+ optional: true
+ openai:
+ optional: true
+ ws:
+ optional: true
+
resolution: {integrity: sha512-y+SqErxb8h7nE/fiEX07jsbuhrpO9lL8eca7/Y1nuWV2moNlXhyd59iDGcRf6moVyDMbmTNzL40SUyrFU/yDpg==}
@@ -4791,6 +4817,10 @@ packages:
oxlint-tsgolint:
optional: true
+ resolution: {integrity: sha512-LICb2p9CB7FS+0eR1oqWnHhp0FljGLZCWBE9aix0Uye9W8LTQPwMTYVGWQWIw9RdQiDg4+epXQODwIYJtSJaow==}
+ engines: {node: '>=4'}
+
resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==}
engines: {node: '>=6'}
@@ -4803,6 +4833,14 @@ packages:
resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==}
engines: {node: '>=8'}
+ resolution: {integrity: sha512-RwFpb72c/BhQLEXIZ5K2e+AhgNVmIejGlTgiB9MzZ0e93GRvqZ7uSi0dvRF7/XIXDeNkra2fNHBxTyPDGySpjQ==}
+ engines: {node: '>=8'}
+
+ resolution: {integrity: sha512-rhIwUycgwwKcP9yTOOFK/AKsAopjjCakVqLHePO3CC6Mir1Z99xT+R63jZxAT5lFZLa2inS5h+ZS2GvR99/FBg==}
+ engines: {node: '>=8'}
+
resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==}
engines: {node: '>=6'}
@@ -5620,6 +5658,10 @@ packages:
resolution: {integrity: sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==}
engines: {node: '>= 0.4.0'}
+ resolution: {integrity: sha512-8XkAphELsDnEGrDxUOHB3RGvXz6TeuYSGEZBOjtTtPm2lwhGBjLgOzLHB63IUWfBpNucQjND6d3AOudO+H3RWQ==}
+ hasBin: true
+
resolution: {integrity: sha512-XQegIaBTVUjSHliKqcnFqYypAd4S+WCYt5NIeRs6w/UAry7z8Y9j5ZwRRL4kzq9U3sD6v+85er9FvkEaBpji2w==}
hasBin: true
@@ -9312,6 +9354,8 @@ snapshots:
+
@@ -10405,6 +10449,16 @@ snapshots:
+ dependencies:
+ p-queue: 6.6.2
+ uuid: 10.0.0
+ optionalDependencies:
+ '@opentelemetry/api': 1.9.0
+ '@opentelemetry/sdk-trace-base': 2.2.0(@opentelemetry/[email protected])
+
@@ -10759,6 +10813,8 @@ snapshots:
'@oxlint/win32-arm64': 1.14.0
'@oxlint/win32-x64': 1.14.0
+
dependencies:
p-try: 2.2.0
@@ -10771,6 +10827,15 @@ snapshots:
dependencies:
p-limit: 2.3.0
+ dependencies:
+ eventemitter3: 4.0.7
+ p-timeout: 3.2.0
+
+ dependencies:
+ p-finally: 1.0.0
+
@@ -11583,6 +11648,8 @@ snapshots:
+
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index 7caea74cd..adf824efd 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -203,6 +203,12 @@ const configSchema = z.object({
OLLAMA_BASE_URL: z.string().optional(),
VERTEX_CREDENTIALS: z.string().optional(),
+ // LangSmith (tracing for interact agent)
+ LANGSMITH_API_KEY: z.string().optional(),
+ LANGSMITH_PROJECT: z.string().optional(),
+ LANGSMITH_ENDPOINT: z.string().optional(),
+ LANGSMITH_TRACING: z.stringbool().optional(),
+
// Rate Limiting
RATE_LIMIT_TEST_API_KEY_SCRAPE: z.coerce.number().optional(),
RATE_LIMIT_TEST_API_KEY_CRAWL: z.coerce.number().optional(),
diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.ts
index 3ace5ac03..fc8e11cfc 100644
--- a/apps/api/src/controllers/v2/scrape-browser.ts
+++ b/apps/api/src/controllers/v2/scrape-browser.ts
@@ -37,8 +37,11 @@ import {
} from "../../lib/scrape-interact/scrape-replay";
import {
executePromptViaBrowserAgent,
+ executeCodeViaBrowserSession,
AgentResult,
} from "../../lib/scrape-interact/browser-agent";
+import { sanitizeUrlForTrace } from "../../lib/scrape-interact/langsmith";
+import { getScrapeZDR } from "../../lib/zdr-helpers";
import { RequestWithAuth, ScrapeOptions } from "./types";
import { billTeam } from "../../services/billing/credit_billing";
import { enqueueBrowserSessionActivity } from "../../lib/browser-session-activity";
@@ -217,6 +220,36 @@ export async function scrapeInteractController(
updateBrowserSessionActivity(session.id).catch(() => {});
// --- Execute: prompt-based agent loop OR direct code ---
+ //
+ // Skip LangSmith tracing entirely for teams with forced zero-data-retention,
+ // matching how tracking.ts skips ClickHouse writes. The trace would otherwise
+ // ship the full prompt, tool I/O, and page snapshots to a third party.
+ const zdrForced = getScrapeZDR(req.acuc?.flags) === "forced";
+
+ // Upstream context from the scrape job β€” interact extends scrape, so
+ // every run carries the URL / wait / actions / origin that set the stage
+ // for what the agent does on top of it. URLs are stripped of query
+ // strings to avoid leaking PII into LangSmith.
+ const scrapeOptions = (scrape.options ?? {}) as {
+ origin?: string;
+ };
+ const traceScrapeContext = {
+ scrapeUrl: sanitizeUrlForTrace(scrape.url),
+ targetUrl: sanitizeUrlForTrace(replayContext.targetUrl),
+ scrapeWaitForMs: replayContext.waitForMs,
+ scrapeActions: replayContext.actions.length,
+ scrapeOrigin:
+ typeof scrapeOptions.origin === "string"
+ ? scrapeOptions.origin
+ : undefined,
+ };
+
+ // Identity fields below team_id β€” optional, normalized from null β†’ undefined
+ // so LangSmith metadata filters don't match empty strings.
+ const traceIdentity = {
+ orgId: req.auth.org_id ?? undefined,
+ subUserId: req.acuc?.sub_user_id ?? undefined,
+ };
let execResult: BrowserServiceExecResponse | AgentResult;
@@ -231,6 +264,14 @@ export async function scrapeInteractController(
session.browser_id,
timeout,
logger,
+ {
+ sessionId: session.id,
+ scrapeId,
+ teamId: req.auth.team_id,
+ ...traceIdentity,
+ zeroDataRetention: zdrForced,
+ ...traceScrapeContext,
+ },
);
} catch (err) {
logger.error("Agent loop failed", { error: err });
@@ -253,10 +294,17 @@ export async function scrapeInteractController(
logger.info("Executing code in browser session", { language, timeout });
try {
- execResult = await browserServiceRequest<BrowserServiceExecResponse>(
- "POST",
- `/browsers/${session.browser_id}/exec`,
+ execResult = await executeCodeViaBrowserSession(
+ session.browser_id,
{ code: rawCode!, language, timeout, origin },
+ {
+ sessionId: session.id,
+ scrapeId,
+ teamId: req.auth.team_id,
+ ...traceIdentity,
+ zeroDataRetention: zdrForced,
+ ...traceScrapeContext,
+ },
);
} catch (err) {
logger.error("Failed to execute code via browser service", {
diff --git a/apps/api/src/lib/scrape-interact/browser-agent.ts b/apps/api/src/lib/scrape-interact/browser-agent.ts
index bb4003276..32ed7f1a4 100644
--- a/apps/api/src/lib/scrape-interact/browser-agent.ts
+++ b/apps/api/src/lib/scrape-interact/browser-agent.ts
@@ -1,7 +1,7 @@
import { z } from "zod";
import { promises as fs } from "fs";
import path from "path";
-import { generateText, tool, stepCountIs } from "ai";
+import { tool, stepCountIs } from "ai";
import { logger as _logger } from "../logger";
import { getModel } from "../generic-ai";
import {
@@ -9,6 +9,12 @@ import {
BrowserServiceExecResponse,
} from "./browser-service-client";
import { config } from "../../config";
+import {
+ generateText,
+ buildLangSmithProviderOptions,
+ traceInteract,
+ InteractTraceMetadata,
+} from "./langsmith";
// ---------------------------------------------------------------------------
// Constants
@@ -179,11 +185,26 @@ async function takeSnapshot(browserId: string): Promise<string> {
// Main agent β€” tool-calling loop via AI SDK
// ---------------------------------------------------------------------------
+export interface BrowserAgentTraceContext {
+ sessionId: string;
+ scrapeId: string;
+ teamId: string;
+ orgId?: string;
+ subUserId?: string;
+ zeroDataRetention?: boolean;
+ scrapeUrl?: string;
+ targetUrl?: string;
+ scrapeWaitForMs?: number;
+ scrapeActions?: number;
+ scrapeOrigin?: string;
+}
+
export async function executePromptViaBrowserAgent(
prompt: string,
browserId: string,
stepTimeout: number,
logger: typeof _logger,
+ trace?: BrowserAgentTraceContext,
): Promise<AgentResult> {
const debugLog = new AgentDebugLog(browserId);
debugLog.add(`=== AGENT RUN ===`);
@@ -293,6 +314,31 @@ export async function executePromptViaBrowserAgent(
},
});
+ const langsmith = trace
+ ? buildLangSmithProviderOptions(
+ {
+ thread_id: trace.sessionId,
+ session_id: trace.sessionId,
+ scrape_id: trace.scrapeId,
+ team_id: trace.teamId,
+ org_id: trace.orgId,
+ sub_user_id: trace.subUserId,
+ browser_id: browserId,
+ mode: "prompt",
+ zeroDataRetention: trace.zeroDataRetention,
+ scrape_url: trace.scrapeUrl,
+ target_url: trace.targetUrl,
+ scrape_wait_for_ms: trace.scrapeWaitForMs,
+ scrape_actions: trace.scrapeActions,
+ scrape_origin: trace.scrapeOrigin,
+ } satisfies InteractTraceMetadata,
+ {
+ name: "interact:prompt",
+ extra: { prompt_length: prompt.length },
+ },
+ )
+ : undefined;
+
try {
const result = await generateText({
model: getModel("gemini-2.5-flash", "google"),
@@ -311,6 +357,12 @@ export async function executePromptViaBrowserAgent(
tools: { browser: browserTool },
stopWhen: stepCountIs(MAX_STEPS),
temperature: 0,
+ // LangSmith's provider-options object is recognized by wrapAISDK but
+ // does not satisfy AI SDK's SharedV3ProviderOptions shape, hence the
+ // local cast β€” keeps the rest of the type surface strict.
+ ...(langsmith
+ ? { providerOptions: { langsmith } as Record<string, any> }
+ : {}),
prepareStep: async ({ stepNumber, messages }) => {
if (actionLog.length === 0) return {};
return {
@@ -363,3 +415,54 @@ export async function executePromptViaBrowserAgent(
};
}
}
+
+// ---------------------------------------------------------------------------
+// Code path β€” direct exec wrapped with the same trace metadata shape as the
+// prompt path, so tracing details don't have to live in the controller.
+// ---------------------------------------------------------------------------
+
+export async function executeCodeViaBrowserSession(
+ browserId: string,
+ params: {
+ code: string;
+ language: string;
+ timeout: number;
+ origin?: string;
+ },
+ trace?: BrowserAgentTraceContext,
+): Promise<BrowserServiceExecResponse> {
+ // Arg must be named so langsmith's traceable sees the exec params as the
+ // run's `inputs`; a zero-arg closure would record `{}` and strip the code,
+ // language, timeout, and origin from every trace.
+ const run = async (execParams: typeof params) =>
+ browserServiceRequest<BrowserServiceExecResponse>(
+ "POST",
+ `/browsers/${browserId}/exec`,
+ execParams,
+ );
+
+ if (!trace) return run(params);
+
+ const traced = traceInteract(
+ run,
+ {
+ thread_id: trace.sessionId,
+ session_id: trace.sessionId,
+ scrape_id: trace.scrapeId,
+ team_id: trace.teamId,
+ org_id: trace.orgId,
+ sub_user_id: trace.subUserId,
+ browser_id: browserId,
+ mode: "code",
+ zeroDataRetention: trace.zeroDataRetention,
+ scrape_url: trace.scrapeUrl,
+ target_url: trace.targetUrl,
+ scrape_wait_for_ms: trace.scrapeWaitForMs,
+ scrape_actions: trace.scrapeActions,
+ scrape_origin: trace.scrapeOrigin,
+ } satisfies InteractTraceMetadata,
+ { name: "interact:code" },
+ );
+
+ return traced(params);
+}
diff --git a/apps/api/src/lib/scrape-interact/langsmith.test.ts b/apps/api/src/lib/scrape-interact/langsmith.test.ts
new file mode 100644
index 000000000..33d64e288
--- /dev/null
+++ b/apps/api/src/lib/scrape-interact/langsmith.test.ts
@@ -0,0 +1,307 @@
+/**
+ * Sanity tests for the LangSmith wiring. The disabled-path block isolates
+ * modules and strips LANGSMITH_* env vars so the tests don't depend on the
+ * developer's local .env, where LANGSMITH_API_KEY may or may not be set.
+ */
+import * as ai from "ai";
+
+describe("scrape-interact/langsmith (disabled β€” no API key)", () => {
+ beforeEach(() => {
+ jest.resetModules();
+ // Mock config to ensure LANGSMITH_API_KEY is unset regardless of what's
+ // in the developer's local .env file β€” this keeps the disabled-path
+ // tests hermetic.
+ jest.doMock("../../config", () => ({
+ config: {
+ LANGSMITH_API_KEY: undefined,
+ LANGSMITH_TRACING: undefined,
+ LANGSMITH_PROJECT: undefined,
+ LANGSMITH_ENDPOINT: undefined,
+ },
+ }));
+ });
+
+ afterEach(() => {
+ jest.dontMock("../../config");
+ });
+
+ it("reports disabled when LANGSMITH_API_KEY is unset", () => {
+ const mod = require("./langsmith");
+ expect(mod.isLangSmithEnabled).toBe(false);
+ });
+
+ it("re-exports raw ai SDK functions when disabled", () => {
+ const freshAi = require("ai");
+ const mod = require("./langsmith");
+ expect(mod.generateText).toBe(freshAi.generateText);
+ expect(mod.streamText).toBe(freshAi.streamText);
+ expect(mod.generateObject).toBe(freshAi.generateObject);
+ expect(mod.streamObject).toBe(freshAi.streamObject);
+ });
+
+ it("returns undefined providerOptions when disabled", () => {
+ const mod = require("./langsmith");
+ const opts = mod.buildLangSmithProviderOptions(
+ {
+ thread_id: "t1",
+ session_id: "t1",
+ scrape_id: "s1",
+ team_id: "team1",
+ mode: "prompt",
+ },
+ { name: "test" },
+ );
+ expect(opts).toBeUndefined();
+ });
+
+ it("traceInteract returns the original function unchanged when disabled", async () => {
+ const mod = require("./langsmith");
+ const original = async (x: number) => x * 2;
+ const wrapped = mod.traceInteract(
+ original,
+ {
+ thread_id: "t1",
+ session_id: "t1",
+ scrape_id: "s1",
+ team_id: "team1",
+ mode: "code",
+ },
+ { name: "test" },
+ );
+ expect(wrapped).toBe(original);
+ await expect(wrapped(3)).resolves.toBe(6);
+ });
+
+ it("treats an API key alone (no LANGSMITH_TRACING) as disabled", () => {
+ jest.resetModules();
+ jest.doMock("../../config", () => ({
+ config: {
+ LANGSMITH_API_KEY: "real-looking-key",
+ LANGSMITH_TRACING: undefined,
+ LANGSMITH_PROJECT: undefined,
+ LANGSMITH_ENDPOINT: undefined,
+ },
+ }));
+ const mod = require("./langsmith");
+ expect(mod.isLangSmithEnabled).toBe(false);
+ });
+
+ it("treats whitespace-only LANGSMITH_API_KEY as disabled", () => {
+ jest.resetModules();
+ jest.doMock("../../config", () => ({
+ config: {
+ LANGSMITH_API_KEY: " \t\n ",
+ LANGSMITH_TRACING: true,
+ LANGSMITH_PROJECT: undefined,
+ LANGSMITH_ENDPOINT: undefined,
+ },
+ }));
+ const mod = require("./langsmith");
+ expect(mod.isLangSmithEnabled).toBe(false);
+ });
+
+ it("sanitizeUrlForTrace strips query strings and fragments", () => {
+ const { sanitizeUrlForTrace } = require("./langsmith");
+ expect(sanitizeUrlForTrace("https://example.com/page?token=abc#x")).toBe(
+ "https://example.com/page",
+ );
+ expect(sanitizeUrlForTrace("https://example.com/")).toBe(
+ "https://example.com/",
+ );
+ expect(sanitizeUrlForTrace(null)).toBeUndefined();
+ expect(sanitizeUrlForTrace(undefined)).toBeUndefined();
+ // Malformed URL still gets query/fragment stripped
+ expect(sanitizeUrlForTrace("not a url?token=secret#frag")).toBe(
+ "not a url",
+ );
+ expect(sanitizeUrlForTrace("not a url")).toBe("not a url");
+ });
+});
+
+describe("scrape-interact/langsmith (enabled β€” mocked SDK)", () => {
+ // These tests reset module state and provide fake langsmith modules so we
+ // can exercise the wrap path without network calls or a real API key.
+
+ const ORIGINAL_ENV = { ...process.env };
+ const fakeWrappedFns = {
+ generateText: jest.fn(),
+ streamText: jest.fn(),
+ generateObject: jest.fn(),
+ streamObject: jest.fn(),
+ };
+ const createProviderOptionsSpy = jest.fn((opts: unknown) => ({
+ __fake_langsmith_options__: true,
+ payload: opts,
+ }));
+ const traceableSpy = jest.fn(
+ (fn: (...args: unknown[]) => unknown, _opts: unknown) => {
+ const wrapper = (...args: unknown[]) => fn(...args);
+ (
+ wrapper as unknown as { __fake_traceable__: boolean }
+ ).__fake_traceable__ = true;
+ return wrapper;
+ },
+ );
+
+ beforeEach(() => {
+ jest.resetModules();
+ createProviderOptionsSpy.mockClear();
+ traceableSpy.mockClear();
+ // Mock config with only the fields the module reads so the test is
+ // hermetic β€” it doesn't depend on the developer's local .env making it
+ // through the zod schema at require time.
+ jest.doMock("../../config", () => ({
+ config: {
+ LANGSMITH_API_KEY: "test-fake-key",
+ LANGSMITH_TRACING: true,
+ LANGSMITH_PROJECT: "test-project",
+ LANGSMITH_ENDPOINT: undefined,
+ },
+ }));
+ jest.doMock("langsmith/experimental/vercel", () => ({
+ wrapAISDK: () => fakeWrappedFns,
+ createLangSmithProviderOptions: createProviderOptionsSpy,
+ }));
+ jest.doMock("langsmith/traceable", () => ({
+ traceable: traceableSpy,
+ }));
+ });
+
+ afterEach(() => {
+ process.env = { ...ORIGINAL_ENV };
+ jest.dontMock("../../config");
+ jest.dontMock("langsmith/experimental/vercel");
+ jest.dontMock("langsmith/traceable");
+ });
+
+ it("reports enabled and swaps generateText for the wrapped fn", () => {
+ const mod = require("./langsmith");
+ expect(mod.isLangSmithEnabled).toBe(true);
+ expect(mod.generateText).toBe(fakeWrappedFns.generateText);
+ expect(mod.generateText).not.toBe(ai.generateText);
+ });
+
+ it("builds provider options with thread_id + scrape context metadata", () => {
+ const mod = require("./langsmith");
+ const result = mod.buildLangSmithProviderOptions(
+ {
+ thread_id: "sess-abc",
+ session_id: "sess-abc",
+ scrape_id: "scrape-xyz",
+ team_id: "team-42",
+ browser_id: "browser-1",
+ mode: "prompt",
+ scrape_url: "https://example.com/pricing",
+ target_url: "https://example.com/pricing/",
+ scrape_wait_for_ms: 500,
+ scrape_actions: 2,
+ scrape_origin: "api",
+ },
+ { name: "interact:prompt", extra: { prompt_length: 123 } },
+ );
+
+ expect(createProviderOptionsSpy).toHaveBeenCalledTimes(1);
+ const callArg = createProviderOptionsSpy.mock.calls[0][0] as {
+ name: string;
+ metadata: Record<string, unknown>;
+ tags: string[];
+ };
+ expect(callArg.name).toBe("interact:prompt");
+ expect(callArg.metadata).toMatchObject({
+ thread_id: "sess-abc",
+ session_id: "sess-abc",
+ scrape_id: "scrape-xyz",
+ team_id: "team-42",
+ scrape_url: "https://example.com/pricing",
+ target_url: "https://example.com/pricing/",
+ scrape_wait_for_ms: 500,
+ scrape_actions: 2,
+ scrape_origin: "api",
+ browser_id: "browser-1",
+ mode: "prompt",
+ prompt_length: 123,
+ });
+ expect(callArg.tags).toEqual(["interact", "mode:prompt"]);
+ expect(result).toMatchObject({ __fake_langsmith_options__: true });
+ });
+
+ it("skips tracing when meta.zeroDataRetention is true", () => {
+ const mod = require("./langsmith");
+ const result = mod.buildLangSmithProviderOptions({
+ thread_id: "sess-abc",
+ session_id: "sess-abc",
+ scrape_id: "scrape-xyz",
+ team_id: "team-42",
+ mode: "prompt",
+ zeroDataRetention: true,
+ });
+ expect(result).toBeUndefined();
+ expect(createProviderOptionsSpy).not.toHaveBeenCalled();
+
+ const fn = async () => "should-still-run";
+ const wrapped = mod.traceInteract(fn, {
+ thread_id: "sess-abc",
+ session_id: "sess-abc",
+ scrape_id: "scrape-xyz",
+ team_id: "team-42",
+ mode: "code",
+ zeroDataRetention: true,
+ });
+ expect(wrapped).toBe(fn);
+ expect(traceableSpy).not.toHaveBeenCalled();
+ });
+
+ it("wraps functions via traceable when zeroDataRetention is not set", async () => {
+ const mod = require("./langsmith");
+ const fn = jest.fn(async (x: number) => x + 1);
+ const wrapped = mod.traceInteract(
+ fn,
+ {
+ thread_id: "sess-abc",
+ session_id: "sess-abc",
+ scrape_id: "scrape-xyz",
+ team_id: "team-42",
+ mode: "code",
+ },
+ { name: "interact:code" },
+ );
+ expect(traceableSpy).toHaveBeenCalledTimes(1);
+ const traceableOpts = traceableSpy.mock.calls[0][1] as {
+ name: string;
+ run_type: string;
+ metadata: Record<string, unknown>;
+ tags: string[];
+ };
+ expect(traceableOpts.name).toBe("interact:code");
+ expect(traceableOpts.run_type).toBe("chain");
+ expect(traceableOpts.tags).toEqual(["interact", "mode:code"]);
+ expect(traceableOpts.metadata).toMatchObject({
+ thread_id: "sess-abc",
+ mode: "code",
+ });
+ await expect(wrapped(5)).resolves.toBe(6);
+ expect(fn).toHaveBeenCalledWith(5);
+ });
+
+ it("falls back to raw ai SDK when langsmith require() throws", () => {
+ jest.resetModules();
+ jest.doMock("langsmith/experimental/vercel", () => {
+ throw new Error("simulated install breakage");
+ });
+ jest.doMock("langsmith/traceable", () => ({ traceable: traceableSpy }));
+ // Re-require ai from the fresh module graph so the identity check lines up
+ // with the module instance the langsmith helper imported.
+ const freshAi = require("ai");
+ const mod = require("./langsmith");
+ expect(mod.generateText).toBe(freshAi.generateText);
+ expect(
+ mod.buildLangSmithProviderOptions({
+ thread_id: "t",
+ session_id: "t",
+ scrape_id: "s",
+ team_id: "x",
+ mode: "prompt",
+ }),
+ ).toBeUndefined();
+ });
+});
diff --git a/apps/api/src/lib/scrape-interact/langsmith.ts b/apps/api/src/lib/scrape-interact/langsmith.ts
new file mode 100644
index 000000000..35be34137
--- /dev/null
+++ b/apps/api/src/lib/scrape-interact/langsmith.ts
@@ -0,0 +1,178 @@
+import * as ai from "ai";
+import { config } from "../../config";
+import { logger as _logger } from "../logger";
+
+const logger = _logger.child({ module: "scrape-interact/langsmith" });
+
+// Trim once at module load β€” a whitespace-only LANGSMITH_API_KEY would be
+// truthy in JS, flip the gate on, and then every trace POST would silently
+// 401 against LangSmith with no other signal that something's wrong.
+const LANGSMITH_API_KEY = config.LANGSMITH_API_KEY?.trim() || undefined;
+
+// Opt-in: require both a key AND explicit LANGSMITH_TRACING=true. Having a
+// key alone shouldn't start shipping traces, since operators may set the key
+// for local experimentation and be surprised when prod starts tracing too.
+export const isLangSmithEnabled = Boolean(
+ LANGSMITH_API_KEY && config.LANGSMITH_TRACING === true,
+);
+
+export type InteractTraceMetadata = {
+ thread_id: string;
+ session_id: string;
+ scrape_id: string;
+ team_id: string;
+ // Optional identifiers below team_id for finer-grained LangSmith filtering.
+ // sub_user_id is the per-request sub-user label (when the API key carries
+ // one); org_id is the parent org when teams are grouped. Neither is always
+ // present β€” team_id is the only guaranteed identity.
+ org_id?: string;
+ sub_user_id?: string;
+ browser_id?: string;
+ run_id?: string;
+ mode: "prompt" | "code";
+ // Context inherited from the upstream scrape that this interact session is
+ // continuing. Interact extends scrape, so the agent's work only makes sense
+ // alongside what the scrape set up: the target URL, how long it waited,
+ // what pre-actions ran, and where the scrape was initiated. URLs are
+ // normalized to origin+path (no query string) before being attached to
+ // avoid leaking query-string PII into LangSmith.
+ scrape_url?: string;
+ target_url?: string;
+ scrape_wait_for_ms?: number;
+ scrape_actions?: number;
+ scrape_origin?: string;
+ // When true, the caller has determined the team/scrape is under
+ // zero-data-retention and tracing must be skipped entirely so no prompt,
+ // code, or tool I/O is shipped to LangSmith.
+ zeroDataRetention?: boolean;
+};
+
+/**
+ * Strip query string + fragment from a URL so it can safely go into trace
+ * metadata. A plain split is used rather than `new URL()` so malformed inputs
+ * can't slip through a `catch` branch still carrying `?token=...` fragments.
+ */
+export function sanitizeUrlForTrace(
+ url: string | null | undefined,
+): string | undefined {
+ if (!url) return undefined;
+ return url.split("?")[0].split("#")[0];
+}
+
+type WrappedAISDK = {
+ generateText: typeof ai.generateText;
+ streamText: typeof ai.streamText;
+ generateObject: typeof ai.generateObject;
+ streamObject: typeof ai.streamObject;
+};
+
+type LangSmithProviderOptions = {
+ name?: string;
+ metadata?: Record<string, unknown>;
+ tags?: string[];
+};
+
+type TraceableOptions = {
+ name?: string;
+ run_type?:
+ | "tool"
+ | "chain"
+ | "llm"
+ | "retriever"
+ | "embedding"
+ | "prompt"
+ | "parser";
+ metadata?: Record<string, unknown>;
+ tags?: string[];
+};
+
+type LangSmithProviderOptionsReturn = Record<string, unknown>;
+
+let wrappedSDK: WrappedAISDK = ai;
+let createLangSmithProviderOptionsFn:
+ | ((opts: LangSmithProviderOptions) => LangSmithProviderOptionsReturn)
+ | null = null;
+let traceableFn:
+ | (<F extends (...args: any[]) => any>(fn: F, opts?: TraceableOptions) => F)
+ | null = null;
+
+if (isLangSmithEnabled) {
+ try {
+ const vercelWrapper = require("langsmith/experimental/vercel");
+ const traceableMod = require("langsmith/traceable");
+ wrappedSDK = vercelWrapper.wrapAISDK(ai);
+ createLangSmithProviderOptionsFn =
+ vercelWrapper.createLangSmithProviderOptions;
+ traceableFn = traceableMod.traceable;
+
+ // Mirror our config into process.env only after the langsmith modules
+ // loaded successfully. If init fails we fall back to the raw ai SDK
+ // without polluting the process env for other modules. Use the trimmed
+ // key so whitespace padding in .env can't reach the langsmith SDK.
+ process.env.LANGSMITH_TRACING = "true";
+ process.env.LANGSMITH_API_KEY = LANGSMITH_API_KEY!;
+ if (config.LANGSMITH_PROJECT) {
+ process.env.LANGSMITH_PROJECT = config.LANGSMITH_PROJECT;
+ }
+ if (config.LANGSMITH_ENDPOINT) {
+ process.env.LANGSMITH_ENDPOINT = config.LANGSMITH_ENDPOINT;
+ }
+
+ logger.info("LangSmith tracing enabled for interact agent", {
+ project: config.LANGSMITH_PROJECT ?? "(default)",
+ });
+ } catch (err) {
+ logger.error(
+ "Failed to initialize LangSmith β€” falling back to raw ai SDK",
+ {
+ error: err,
+ },
+ );
+ }
+}
+
+export const { generateText, streamText, generateObject, streamObject } =
+ wrappedSDK;
+
+// The LangSmith provider config is recognized by wrapAISDK but is not a
+// first-class AI SDK provider, so callers still need a narrow cast when
+// assigning to AI SDK's typed `providerOptions`. We keep the helper's return
+// type honest so the cast is local to the call site rather than `any`
+// propagating back here.
+export function buildLangSmithProviderOptions(
+ meta: InteractTraceMetadata,
+ opts: {
+ name?: string;
+ tags?: string[];
+ extra?: Record<string, unknown>;
+ } = {},
+): LangSmithProviderOptionsReturn | undefined {
+ if (
+ !isLangSmithEnabled ||
+ !createLangSmithProviderOptionsFn ||
+ meta.zeroDataRetention
+ ) {
+ return undefined;
+ }
+
+ return createLangSmithProviderOptionsFn({
+ name: opts.name,
+ metadata: { ...meta, ...(opts.extra ?? {}) },
+ tags: ["interact", `mode:${meta.mode}`, ...(opts.tags ?? [])],
+ });
+}
+
+export function traceInteract<F extends (...args: any[]) => any>(
+ fn: F,
+ meta: InteractTraceMetadata,
+ opts: { name?: string; runType?: TraceableOptions["run_type"] } = {},
+): F {
+ if (!isLangSmithEnabled || !traceableFn || meta.zeroDataRetention) return fn;
+
+ return traceableFn(fn, {
+ name: opts.name ?? `interact:${meta.mode}`,
+ run_type: opts.runType ?? "chain",
+ metadata: { ...meta },
+ tags: ["interact", `mode:${meta.mode}`],
+ });
+}