feat(cloudflare): Instrument Agents automatically (#22727)

Since `instrumentAgentWithSentry` is here, it also needs to be supported
within the Vite plugin and its `autoInstrument` flag. The issue here is
that we need to parse through the imports in order to understand where
the `Agent` import is coming from. (The majority of the changes are
tests again)

It could also be that external libraries are extending from `Agent`,
such as `McpAgent`, and these need to be wrapped too. It is super hacky
but it works.

For the tests I wished to add them in the
`cloudflare-integration-tests`, but unfortunately `agents` needs Node
v20+ and locally we run with v18, so it wouldn't work without either
bumping Nodejs or making the tests their own package so they are
independent.

Author: JPeer264

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/.gitignore

@@ -0,0 +1,4 @@
+dist
+.wrangler
+test-results
+pnpm-lock.yaml

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "cloudflare-autoinstrument",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+    "test": "playwright test",
+    "typecheck": "tsc --noEmit",
+    "test:build": "pnpm install && pnpm build",
+    "test:assert": "pnpm typecheck && pnpm test"
+  },
+  "dependencies": {
+    "@cloudflare/ai-chat": "^0.10.0",
+    "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+    "agents": "^0.20.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^8.0.1",
+    "@babel/plugin-proposal-decorators": "^8.0.2",
+    "@cloudflare/vite-plugin": "^1.47.0",
+    "@cloudflare/workers-types": "^5.20260727.1",
+    "@playwright/test": "~1.56.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils",
+    "@types/node": "^26.1.2",
+    "@types/ws": "^8.18.1",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.5",
+    "wrangler": "^4.114.0",
+    "ws": "^8.21.1"
+  },
+  "volta": {
+    "node": "24.15.0",
+    "extends": "../../package.json"
+  }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/playwright.config.ts

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+// `vite build` runs the Sentry auto-instrument transform over the worker entry;
+// `pnpm preview` (`wrangler dev`, following the vite plugin's `.wrangler/deploy`
+// redirect) serves the built output. The tests therefore assert on the wrapping
+// the plugin injected at build time, not on anything in the source entry.
+export default getPlaywrightConfig(
+  {
+    startCommand: 'pnpm preview',
+    port: 8787,
+  },
+  {
+    workers: '100%',
+    retries: 0,
+  },
+);

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/base.ts

@@ -0,0 +1,12 @@
+import { Agent } from 'agents';
+
+/**
+ * An Agent base class living outside the worker entry. `DerivedAgent` in
+ * `index.ts` extends this, so the plugin only learns it is an Agent by
+ * following the import into this module and resolving `MyBase -> Agent`.
+ */
+export class MyBase extends Agent<Env> {
+  async onRequest(): Promise<Response> {
+    return Response.json({ agent: 'derived' });
+  }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/env.d.ts

@@ -0,0 +1,7 @@
+interface Env {
+  E2E_TEST_DSN: string;
+  MyAgent: DurableObjectNamespace;
+  MyChatAgent: DurableObjectNamespace;
+  DerivedAgent: DurableObjectNamespace;
+  PlainDO: DurableObjectNamespace;
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/index.ts

@@ -0,0 +1,73 @@
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Agent, callable, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
+import { MyBase } from './base';
+
+// NOTE: this file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`. Everything below is wrapped at build time by
+// `sentryCloudflareVitePlugin({ _experimental: { autoInstrumentation: true } })`,
+// which reads wrangler.jsonc, wraps the default export with `withSentry`, and
+// picks a wrapper per class: `instrumentAgentWithSentry` for the three Agents,
+// `instrumentDurableObjectWithSentry` for the plain Durable Object.
+//
+// Options come from `instrument.server.ts` next to this entry.
+
+/** Agent whose base class (`Agent`) is imported directly into the entry. */
+export class MyAgent extends Agent<Env> {
+  @callable()
+  async greet(name: string): Promise<string> {
+    return `Hello, ${name}! (from MyAgent)`;
+  }
+
+  async onRequest(): Promise<Response> {
+    return Response.json({ agent: 'plain' });
+  }
+}
+
+/** Chat agent — `AIChatAgent` extends `Agent` inside `@cloudflare/ai-chat`. */
+export class MyChatAgent extends AIChatAgent<Env> {
+  @callable()
+  async greet(name: string): Promise<string> {
+    return `Hello, ${name}! (from MyChatAgent)`;
+  }
+
+  async onRequest(): Promise<Response> {
+    return Response.json({ agent: 'chat' });
+  }
+}
+
+/** Agent whose base class lives in `./base` — resolvable only across modules. */
+export class DerivedAgent extends MyBase {
+  @callable()
+  async greet(name: string): Promise<string> {
+    return `Hello, ${name}! (from DerivedAgent)`;
+  }
+}
+
+/**
+ * A genuine Durable Object. Configured identically to the Agents above, so it
+ * proves detection discriminates rather than upgrading every DO binding.
+ */
+export class PlainDO extends DurableObject<Env> {
+  async fetch(): Promise<Response> {
+    return Response.json({ durableObject: true });
+  }
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/plain-do') {
+      const stub = env.PlainDO.get(env.PlainDO.idFromName('do-instance'));
+      return stub.fetch(request);
+    }
+
+    const agentResponse = await routeAgentRequest(request, env);
+    if (agentResponse) {
+      return agentResponse;
+    }
+
+    return new Response('Not found', { status: 404 });
+  },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/instrument.server.ts

@@ -0,0 +1,14 @@
+// The auto-instrument plugin picks this file up by convention (it sits next to
+// the worker entry named in wrangler's `main`) and imports its default export as
+// the options callback for every wrapper it injects.
+export default (env: Env) => ({
+  traceLifecycle: 'static' as const,
+  dsn: env.E2E_TEST_DSN,
+  environment: 'qa',
+  tunnel: 'http://localhost:3031/',
+  tracesSampleRate: 1.0,
+  enableRpcTracePropagation: true,
+  transportOptions: {
+    bufferSize: 1000,
+  },
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import { startEventProxyServer } from '@sentry-internal/test-utils';
+
+startEventProxyServer({
+  port: 3031,
+  proxyServerName: 'cloudflare-autoinstrument',
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/agent-socket.ts

@@ -0,0 +1,46 @@
+import WebSocket from 'ws';
+
+type AgentReply = { type?: string; id?: string; done?: boolean; result?: unknown };
+
+/**
+ * Opens a WebSocket to `/agents/<binding>/<instance>`, sends one RPC frame, and
+ * resolves with the reply's `result` — the method's return value — once it arrives.
+ */
+export function callRpc(
+  baseURL: string,
+  options: { binding: string; instance: string; method: string; args: unknown[] },
+): Promise<unknown> {
+  const id = `rpc-${options.method}`;
+  const frame = { type: 'rpc', id, method: options.method, args: options.args };
+  const wsUrl = `${baseURL.replace(/^http/, 'ws')}/agents/${options.binding}/${options.instance}`;
+
+  return new Promise<unknown>((resolveSocket, rejectSocket) => {
+    const socket = new WebSocket(wsUrl);
+    const timeout = setTimeout(() => {
+      socket.close();
+      rejectSocket(new Error(`Timed out waiting for RPC reply to "${options.method}"`));
+    }, 15_000);
+
+    socket.on('open', () => {
+      socket.send(JSON.stringify(frame));
+    });
+
+    socket.on('message', data => {
+      try {
+        const parsed = JSON.parse(data.toString()) as AgentReply;
+        if (parsed.type === 'rpc' && parsed.id === id && parsed.done) {
+          clearTimeout(timeout);
+          socket.close();
+          resolveSocket(parsed.result);
+        }
+      } catch {
+        // Ignore non-JSON / unrelated frames.
+      }
+    });
+
+    socket.on('error', err => {
+      clearTimeout(timeout);
+      rejectSocket(err);
+    });
+  });
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/autoinstrument.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { callRpc } from './agent-socket';
+
+// The worker entry (`src/index.ts`) contains no Sentry calls at all — every
+// wrapper below was injected by the Vite auto-instrument plugin at build time.
+// Any transaction arriving here therefore proves the injection happened.
+
+test('wraps the default export with withSentry (options from instrument.server.ts)', async ({ baseURL }) => {
+  const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+    return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+  });
+
+  const res = await fetch(`${baseURL}/plain-do`);
+  expect(res.status).toBe(200);
+  await expect(res.json()).resolves.toEqual({ durableObject: true });
+
+  const transaction = await transactionPromise;
+
+  expect(transaction.contexts?.trace?.origin).toBe('auto.http.cloudflare');
+  // `environment: 'qa'` is only set in `instrument.server.ts`, so seeing it here
+  // proves the plugin sourced its options callback from that file rather than
+  // falling back to reading configuration off `env`.
+  expect(transaction.environment).toBe('qa');
+});
+
+// Each of these three classes is registered in wrangler.jsonc exactly like the
+// plain Durable Object below — only the base-class chain marks them as Agents.
+// An `rpc` span with origin `auto.faas.cloudflare.agents` is produced solely by
+// `instrumentAgentWithSentry`, so its presence is what distinguishes a correct
+// agent upgrade from a plain `instrumentDurableObjectWithSentry` wrap.
+for (const { title, binding, agentClass } of [
+  {
+    title: 'an Agent subclass declared in the entry',
+    binding: 'my-agent',
+    agentClass: 'MyAgent',
+  },
+  {
+    title: 'an AIChatAgent subclass declared in the entry',
+    binding: 'my-chat-agent',
+    agentClass: 'MyChatAgent',
+  },
+  {
+    title: 'an Agent subclass whose base class lives in another module',
+    binding: 'derived-agent',
+    agentClass: 'DerivedAgent',
+  },
+]) {
+  test(`applies agent instrumentation to ${title}`, async ({ baseURL }) => {
+    const instance = `${binding}-instance`;
+
+    const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+      return (
+        event.transaction === 'webSocketMessage' &&
+        (event.spans ?? []).some(span => span.op === 'rpc' && span.description === 'greet')
+      );
+    });
+
+    // Each agent's greet() returns a string naming its class, so the reply
+    // identifies exactly which class handled the call.
+    const reply = await callRpc(baseURL!, { binding, instance, method: 'greet', args: ['World'] });
+    expect(reply).toBe(`Hello, World! (from ${agentClass})`);
+
+    const transaction = await transactionPromise;
+    const rpcSpan = (transaction.spans ?? []).find(span => span.op === 'rpc' && span.description === 'greet');
+
+    expect(rpcSpan).toEqual(
+      expect.objectContaining({
+        op: 'rpc',
+        description: 'greet',
+        origin: 'auto.faas.cloudflare.agents',
+        data: expect.objectContaining({
+          // Read back off the instance at runtime (`_ParentClass.name`), so it
+          // confirms the wrapper landed on the user's real class. Matched loosely
+          // because the transform renames the class it wraps to
+          // `__SENTRY_ORIGINAL_<name>__` and the bundler infers that name.
+          'cloudflare.agent.class': expect.stringContaining(agentClass),
+          'cloudflare.agent.name': instance,
+        }),
+      }),
+    );
+  });
+}
+
+test('applies plain Durable Object instrumentation to a non-Agent class', async ({ baseURL }) => {
+  const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+    return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+  });
+
+  const res = await fetch(`${baseURL}/plain-do`);
+  expect(res.status).toBe(200);
+
+  const transaction = await transactionPromise;
+
+  // A plain Durable Object must NOT pick up agent instrumentation: detection has
+  // to discriminate, not blanket-upgrade every `durable_objects` binding.
+  const agentSpans = (transaction.spans ?? []).filter(span => span.origin === 'auto.faas.cloudflare.agents');
+  expect(agentSpans).toEqual([]);
+});