feat(dev): open the agent inspector from project dev

.gitignore

@@ -35,3 +35,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .DS_Store
 
 .agentreview
+src/assets/agent-inspector/

package.json

@@ -56,8 +56,10 @@
  "@aws-sdk/client-bedrock-agentcore-control": "^3.1102.0",
  "@aws-sdk/client-cloudwatch-logs": "^3.1092.0",
  "@aws-sdk/client-iam": "^3.1080.0",
+ "@aws/agent-inspector": "0.6.1",
  "@opentelemetry/api": "^1.9.1",
  "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+ "@opentelemetry/otlp-transformer": "0.213.0",
  "@opentelemetry/resources": "^2.10.0",
  "@opentelemetry/sdk-metrics": "^2.10.0",
  "@smithy/core": "3.29.3",
@@ -75,5 +77,8 @@
  "winston": "^3.19.0",
  "winston-daily-rotate-file": "^5.0.0",
  "zod": "^4.4.3"
+ },
+ "overrides": {
+ "@opentelemetry/core": "^2.10.0"
  }
 }

scripts/build.ts

@@ -21,6 +21,29 @@ function discoverAssets(): string[] {
  return files.sort().map((relativePath) => join(ASSETS_DIR, relativePath));
 }
 
+/**
+ * Stage the prebuilt Agent Inspector SPA into the asset tree (gitignored) so
+ * both distribution paths ship it through the ordinary asset machinery:
+ * `bundle` mirrors it into dist/assets/, `compile` embeds it in the binary.
+ * Every file gains a neutral `.asset` suffix — compile passes assets as
+ * Bun.build entrypoints, and a bare .html entrypoint would be bundled through
+ * Bun's HTML-imports pipeline instead of embedded verbatim. InspectorAssets
+ * strips the suffix when reading.
+ */
+async function stageInspectorAssets(): Promise<void> {
+ const source = join(REPO_ROOT, "node_modules", "@aws", "agent-inspector", "dist-assets");
+ if (!(await Bun.file(join(source, "index.html")).exists())) {
+ throw new Error("@aws/agent-inspector is not installed — run `bun install` before building.");
+ }
+ const target = join(ASSETS_DIR, "agent-inspector");
+ await $`rm -rf ${target}`;
+ await $`mkdir -p ${target}`;
+ const files = [...new Bun.Glob("**/*").scanSync({ cwd: source, onlyFiles: true })];
+ for (const file of files) {
+ await $`cp ${join(source, file)} ${join(target, `${file}.asset`)}`;
+ }
+}
+
 /** Force asset files through the file loader so template .ts/.js are embedded as bytes, not compiled. */
 function assetLoaderPlugin(): Bun.BunPlugin {
  return {
@@ -49,6 +72,7 @@ async function assertAssetsAreText(assets: string[]): Promise<void> {
 // Bun.build rejects with an AggregateError on failure (throw defaults to true),
 // so build errors propagate to runWithExitCode like any other.
 async function bundle(): Promise<void> {
+ await stageInspectorAssets();
  await Bun.build({
  entrypoints: [ENTRYPOINT],
  outdir: DIST,
@@ -64,6 +88,7 @@ async function bundle(): Promise<void> {
 }
 
 async function compile(target: string): Promise<void> {
+ await stageInspectorAssets();
  const assets = discoverAssets();
  await assertAssetsAreText(assets);
 

src/assets/templates/shared/env.local.template

@@ -1,7 +1,11 @@
 # Environment variables for local development.
 # `agentcore project dev` loads this file into your agent's process. Values here
 # override injected values except PORT, FASTMCP_PORT, and LOCAL_DEV, which the
-# CLI owns. This file is gitignored — keep secrets out of version control.
+# CLI owns. While trace collection is on (the default), the CLI also owns the
+# OTEL_* and AGENT_OBSERVABILITY_ENABLED variables so traces reach its local
+# collector — pass --no-traces (or set instrumentation.enableOtel to false in
+# agentcore.json) to disable collection and set your own.
+# This file is gitignored — keep secrets out of version control.
 #
 # Example:
 # MY_API_KEY=...

src/core/dev/codezip.test.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { delimiter, join, relative } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { ProjectRuntime } from "../../projectSchemas/runtime";
 import type { DevEvent, DevServerInput } from "../../handlers/project/dev/types";
-import type { ProcessEvent, ProcessStreamer, StreamProcessOptions } from "../../io";
+import type { ProcessEvent, ProcessRunner, ProcessStreamer, StreamProcessOptions } from "../../io";
 import { CodeZipDevRunner } from "./codezip";
 
 type ProcessCall = {
@@ -54,15 +54,22 @@ async function projectRoot(withNodeModules = false): Promise<string> {
  return root;
 }
 
-function harness(output: ProcessEvent[] = []) {
+function harness(output: ProcessEvent[] = [], probe: { dir?: string; fail?: boolean } = {}) {
  const calls: ProcessCall[] = [];
+ const probeCalls: string[][] = [];
  const fakeStreamProcess: ProcessStreamer = async function* (command, options) {
  calls.push({ command, options });
  yield* output;
  };
+ const fakeRunProcess: ProcessRunner = async (command, options) => {
+ probeCalls.push(command);
+ if (probe.fail) throw new Error("probe failed");
+ options.onOutput?.(`${probe.dir ?? ""}\n`);
+ };
  return {
  calls,
- runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess }),
+ probeCalls,
+ runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess, runProcess: fakeRunProcess }),
  };
 }
 
@@ -193,3 +200,69 @@ describe("CodeZipDevRunner", () => {
  ]);
  });
 });
+
+describe("CodeZipDevRunner OTEL instrumentation", () => {
+ async function sitecustomizeDir(): Promise<string> {
+ const directory = await mkdtemp(join(tmpdir(), "otel-site-"));
+ tempDirectories.push(directory);
+ await writeFile(join(directory, "sitecustomize.py"), "");
+ return directory;
+ }
+
+ function otelInput(root: string, extraEnv: Record<string, string> = {}): DevServerInput {
+ const base = input(root, runtime());
+ return {
+ ...base,
+ env: { ...base.env, OTEL_EXPORTER_OTLP_ENDPOINT: "http://127.0.0.1:4318", ...extraEnv },
+ };
+ }
+
+ test("prepends the sitecustomize directory to PYTHONPATH when instrumentation is installed", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, probeCalls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls[0]?.slice(0, 4)).toEqual(["uv", "run", "python", "-c"]);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(directory);
+ });
+
+ test("preserves an existing PYTHONPATH", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root, { PYTHONPATH: "/existing" })));
+
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(`${directory}${delimiter}/existing`);
+ });
+
+ test("does not probe without an OTEL endpoint or for Node entrypoints", async () => {
+ const root = await projectRoot(true);
+ const { probeCalls, runner } = harness();
+
+ await collect(runner.run(input(root, runtime())));
+ await collect(runner.run({ ...otelInput(root), runtime: runtime({ entrypoint: "index.js" }) }));
+
+ expect(probeCalls).toEqual([]);
+ });
+
+ test.each([
+ ["probe failure", { fail: true }],
+ ["missing sitecustomize.py", { dir: "/nonexistent" }],
+ ] as const)("warns and starts untraced on %s", async (_case, probe) => {
+ const root = await projectRoot();
+ const { calls, probeCalls, runner } = harness([], probe);
+
+ const events = await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls).toHaveLength(1);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBeUndefined();
+ expect(events).toContainEqual({
+ type: "status",
+ message: expect.stringContaining("traces will not be collected"),
+ });
+ });
+});

src/core/dev/codezip.ts

@@ -1,19 +1,28 @@
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
-import { streamProcess, type ProcessStreamer, type StreamProcessOptions } from "../../io";
+import {
+ runProcess,
+ streamProcess,
+ type ProcessRunner,
+ type ProcessStreamer,
+ type StreamProcessOptions,
+} from "../../io";
 import { isDirectory, isFile, resolvePathWithinProject } from "./path";
 
 type CodeZipDevRunnerConfig = {
  streamProcess?: ProcessStreamer;
+ runProcess?: ProcessRunner;
 };
 
 export class CodeZipDevRunner implements DevRunner {
  private readonly streamProcess: ProcessStreamer;
+ private readonly runProcess: ProcessRunner;
 
  constructor(config: CodeZipDevRunnerConfig = {}) {
  this.streamProcess = config.streamProcess ?? streamProcess;
+ this.runProcess = config.runProcess ?? runProcess;
  }
 
  public async *run(input: DevServerInput): AsyncGenerator<DevEvent, void> {
@@ -41,8 +50,48 @@ export class CodeZipDevRunner implements DevRunner {
 
  yield { type: "status", message: "Starting development server" };
  const serverProcess = commandForRuntime(entrypoint!, directory, input);
+ if (entrypoint!.endsWith(".py") && input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) {
+ const sitecustomizeDir = await this.findOtelSitecustomizeDir(directory);
+ if (sitecustomizeDir) {
+ const existing = serverProcess.options.env?.PYTHONPATH;
+ serverProcess.options.env = {
+ ...serverProcess.options.env,
+ PYTHONPATH: existing ? `${sitecustomizeDir}${delimiter}${existing}` : sitecustomizeDir,
+ };
+ } else {
+ yield {
+ type: "status",
+ message:
+ "OTEL auto-instrumentation is not installed in the agent environment; traces will not be collected. Add aws-opentelemetry-distro to the agent's dependencies to enable them.",
+ };
+ }
+ }
  yield* this.streamProcess(serverProcess.command, serverProcess.options);
  }
+
+ /**
+ * Locate the auto-instrumentation sitecustomize.py directory inside the agent's
+ * uv environment. Prepending it to PYTHONPATH instruments every Python process —
+ * an `opentelemetry-instrument` wrapper would only instrument uvicorn's reloader
+ * parent, leaving the re-spawned worker processes untraced.
+ */
+ private async findOtelSitecustomizeDir(directory: string): Promise<string | undefined> {
+ const output: string[] = [];
+ const probe =
+ "import opentelemetry.instrumentation.auto_instrumentation as m; import os; print(os.path.dirname(m.__file__))";
+ try {
+ await this.runProcess(["uv", "run", "python", "-c", probe], {
+ cwd: directory,
+ onOutput: (chunk) => output.push(chunk),
+ });
+ } catch {
+ return undefined;
+ }
+ const sitecustomizeDir = output.join("").trim().split("\n").at(-1)?.trim();
+ if (!sitecustomizeDir || !existsSync(join(sitecustomizeDir, "sitecustomize.py")))
+ return undefined;
+ return sitecustomizeDir;
+ }
 }
 
 function commandForRuntime(

.gitignore

@@ -35,3 +35,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .DS_Store
 
 .agentreview
+src/assets/agent-inspector/

package.json

@@ -56,8 +56,10 @@
  "@aws-sdk/client-bedrock-agentcore-control": "^3.1102.0",
  "@aws-sdk/client-cloudwatch-logs": "^3.1092.0",
  "@aws-sdk/client-iam": "^3.1080.0",
+ "@aws/agent-inspector": "0.6.1",
  "@opentelemetry/api": "^1.9.1",
  "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+ "@opentelemetry/otlp-transformer": "0.213.0",
  "@opentelemetry/resources": "^2.10.0",
  "@opentelemetry/sdk-metrics": "^2.10.0",
  "@smithy/core": "3.29.3",
@@ -75,5 +77,8 @@
  "winston": "^3.19.0",
  "winston-daily-rotate-file": "^5.0.0",
  "zod": "^4.4.3"
+ },
+ "overrides": {
+ "@opentelemetry/core": "^2.10.0"
  }
 }

scripts/build.ts

@@ -21,6 +21,29 @@ function discoverAssets(): string[] {
  return files.sort().map((relativePath) => join(ASSETS_DIR, relativePath));
 }
 
+/**
+ * Stage the prebuilt Agent Inspector SPA into the asset tree (gitignored) so
+ * both distribution paths ship it through the ordinary asset machinery:
+ * `bundle` mirrors it into dist/assets/, `compile` embeds it in the binary.
+ * Every file gains a neutral `.asset` suffix — compile passes assets as
+ * Bun.build entrypoints, and a bare .html entrypoint would be bundled through
+ * Bun's HTML-imports pipeline instead of embedded verbatim. InspectorAssets
+ * strips the suffix when reading.
+ */
+async function stageInspectorAssets(): Promise<void> {
+ const source = join(REPO_ROOT, "node_modules", "@aws", "agent-inspector", "dist-assets");
+ if (!(await Bun.file(join(source, "index.html")).exists())) {
+ throw new Error("@aws/agent-inspector is not installed — run `bun install` before building.");
+ }
+ const target = join(ASSETS_DIR, "agent-inspector");
+ await $`rm -rf ${target}`;
+ await $`mkdir -p ${target}`;
+ const files = [...new Bun.Glob("**/*").scanSync({ cwd: source, onlyFiles: true })];
+ for (const file of files) {
+ await $`cp ${join(source, file)} ${join(target, `${file}.asset`)}`;
+ }
+}
+
 /** Force asset files through the file loader so template .ts/.js are embedded as bytes, not compiled. */
 function assetLoaderPlugin(): Bun.BunPlugin {
  return {
@@ -49,6 +72,7 @@ async function assertAssetsAreText(assets: string[]): Promise<void> {
 // Bun.build rejects with an AggregateError on failure (throw defaults to true),
 // so build errors propagate to runWithExitCode like any other.
 async function bundle(): Promise<void> {
+ await stageInspectorAssets();
  await Bun.build({
  entrypoints: [ENTRYPOINT],
  outdir: DIST,
@@ -64,6 +88,7 @@ async function bundle(): Promise<void> {
 }
 
 async function compile(target: string): Promise<void> {
+ await stageInspectorAssets();
  const assets = discoverAssets();
  await assertAssetsAreText(assets);
 

src/assets/templates/shared/env.local.template

@@ -1,7 +1,11 @@
 # Environment variables for local development.
 # `agentcore project dev` loads this file into your agent's process. Values here
 # override injected values except PORT, FASTMCP_PORT, and LOCAL_DEV, which the
-# CLI owns. This file is gitignored — keep secrets out of version control.
+# CLI owns. While trace collection is on (the default), the CLI also owns the
+# OTEL_* and AGENT_OBSERVABILITY_ENABLED variables so traces reach its local
+# collector — pass --no-traces (or set instrumentation.enableOtel to false in
+# agentcore.json) to disable collection and set your own.
+# This file is gitignored — keep secrets out of version control.
 #
 # Example:
 # MY_API_KEY=...

src/core/dev/codezip.test.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { delimiter, join, relative } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { ProjectRuntime } from "../../projectSchemas/runtime";
 import type { DevEvent, DevServerInput } from "../../handlers/project/dev/types";
-import type { ProcessEvent, ProcessStreamer, StreamProcessOptions } from "../../io";
+import type { ProcessEvent, ProcessRunner, ProcessStreamer, StreamProcessOptions } from "../../io";
 import { CodeZipDevRunner } from "./codezip";
 
 type ProcessCall = {
@@ -54,15 +54,22 @@ async function projectRoot(withNodeModules = false): Promise<string> {
  return root;
 }
 
-function harness(output: ProcessEvent[] = []) {
+function harness(output: ProcessEvent[] = [], probe: { dir?: string; fail?: boolean } = {}) {
  const calls: ProcessCall[] = [];
+ const probeCalls: string[][] = [];
  const fakeStreamProcess: ProcessStreamer = async function* (command, options) {
  calls.push({ command, options });
  yield* output;
  };
+ const fakeRunProcess: ProcessRunner = async (command, options) => {
+ probeCalls.push(command);
+ if (probe.fail) throw new Error("probe failed");
+ options.onOutput?.(`${probe.dir ?? ""}\n`);
+ };
  return {
  calls,
- runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess }),
+ probeCalls,
+ runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess, runProcess: fakeRunProcess }),
  };
 }
 
@@ -193,3 +200,69 @@ describe("CodeZipDevRunner", () => {
  ]);
  });
 });
+
+describe("CodeZipDevRunner OTEL instrumentation", () => {
+ async function sitecustomizeDir(): Promise<string> {
+ const directory = await mkdtemp(join(tmpdir(), "otel-site-"));
+ tempDirectories.push(directory);
+ await writeFile(join(directory, "sitecustomize.py"), "");
+ return directory;
+ }
+
+ function otelInput(root: string, extraEnv: Record<string, string> = {}): DevServerInput {
+ const base = input(root, runtime());
+ return {
+ ...base,
+ env: { ...base.env, OTEL_EXPORTER_OTLP_ENDPOINT: "http://127.0.0.1:4318", ...extraEnv },
+ };
+ }
+
+ test("prepends the sitecustomize directory to PYTHONPATH when instrumentation is installed", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, probeCalls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls[0]?.slice(0, 4)).toEqual(["uv", "run", "python", "-c"]);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(directory);
+ });
+
+ test("preserves an existing PYTHONPATH", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root, { PYTHONPATH: "/existing" })));
+
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(`${directory}${delimiter}/existing`);
+ });
+
+ test("does not probe without an OTEL endpoint or for Node entrypoints", async () => {
+ const root = await projectRoot(true);
+ const { probeCalls, runner } = harness();
+
+ await collect(runner.run(input(root, runtime())));
+ await collect(runner.run({ ...otelInput(root), runtime: runtime({ entrypoint: "index.js" }) }));
+
+ expect(probeCalls).toEqual([]);
+ });
+
+ test.each([
+ ["probe failure", { fail: true }],
+ ["missing sitecustomize.py", { dir: "/nonexistent" }],
+ ] as const)("warns and starts untraced on %s", async (_case, probe) => {
+ const root = await projectRoot();
+ const { calls, probeCalls, runner } = harness([], probe);
+
+ const events = await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls).toHaveLength(1);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBeUndefined();
+ expect(events).toContainEqual({
+ type: "status",
+ message: expect.stringContaining("traces will not be collected"),
+ });
+ });
+});

src/core/dev/codezip.ts

@@ -1,19 +1,28 @@
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
-import { streamProcess, type ProcessStreamer, type StreamProcessOptions } from "../../io";
+import {
+ runProcess,
+ streamProcess,
+ type ProcessRunner,
+ type ProcessStreamer,
+ type StreamProcessOptions,
+} from "../../io";
 import { isDirectory, isFile, resolvePathWithinProject } from "./path";
 
 type CodeZipDevRunnerConfig = {
  streamProcess?: ProcessStreamer;
+ runProcess?: ProcessRunner;
 };
 
 export class CodeZipDevRunner implements DevRunner {
  private readonly streamProcess: ProcessStreamer;
+ private readonly runProcess: ProcessRunner;
 
  constructor(config: CodeZipDevRunnerConfig = {}) {
  this.streamProcess = config.streamProcess ?? streamProcess;
+ this.runProcess = config.runProcess ?? runProcess;
  }
 
  public async *run(input: DevServerInput): AsyncGenerator<DevEvent, void> {
@@ -41,8 +50,48 @@ export class CodeZipDevRunner implements DevRunner {
 
  yield { type: "status", message: "Starting development server" };
  const serverProcess = commandForRuntime(entrypoint!, directory, input);
+ if (entrypoint!.endsWith(".py") && input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) {
+ const sitecustomizeDir = await this.findOtelSitecustomizeDir(directory);
+ if (sitecustomizeDir) {
+ const existing = serverProcess.options.env?.PYTHONPATH;
+ serverProcess.options.env = {
+ ...serverProcess.options.env,
+ PYTHONPATH: existing ? `${sitecustomizeDir}${delimiter}${existing}` : sitecustomizeDir,
+ };
+ } else {
+ yield {
+ type: "status",
+ message:
+ "OTEL auto-instrumentation is not installed in the agent environment; traces will not be collected. Add aws-opentelemetry-distro to the agent's dependencies to enable them.",
+ };
+ }
+ }
  yield* this.streamProcess(serverProcess.command, serverProcess.options);
  }
+
+ /**
+ * Locate the auto-instrumentation sitecustomize.py directory inside the agent's
+ * uv environment. Prepending it to PYTHONPATH instruments every Python process —
+ * an `opentelemetry-instrument` wrapper would only instrument uvicorn's reloader
+ * parent, leaving the re-spawned worker processes untraced.
+ */
+ private async findOtelSitecustomizeDir(directory: string): Promise<string | undefined> {
+ const output: string[] = [];
+ const probe =
+ "import opentelemetry.instrumentation.auto_instrumentation as m; import os; print(os.path.dirname(m.__file__))";
+ try {
+ await this.runProcess(["uv", "run", "python", "-c", probe], {
+ cwd: directory,
+ onOutput: (chunk) => output.push(chunk),
+ });
+ } catch {
+ return undefined;
+ }
+ const sitecustomizeDir = output.join("").trim().split("\n").at(-1)?.trim();
+ if (!sitecustomizeDir || !existsSync(join(sitecustomizeDir, "sitecustomize.py")))
+ return undefined;
+ return sitecustomizeDir;
+ }
 }
 
 function commandForRuntime(

.gitignore

@@ -35,3 +35,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .DS_Store
 
 .agentreview
+src/assets/agent-inspector/

package.json

@@ -56,8 +56,10 @@
  "@aws-sdk/client-bedrock-agentcore-control": "^3.1102.0",
  "@aws-sdk/client-cloudwatch-logs": "^3.1092.0",
  "@aws-sdk/client-iam": "^3.1080.0",
+ "@aws/agent-inspector": "0.6.1",
  "@opentelemetry/api": "^1.9.1",
  "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+ "@opentelemetry/otlp-transformer": "0.213.0",
  "@opentelemetry/resources": "^2.10.0",
  "@opentelemetry/sdk-metrics": "^2.10.0",
  "@smithy/core": "3.29.3",
@@ -75,5 +77,8 @@
  "winston": "^3.19.0",
  "winston-daily-rotate-file": "^5.0.0",
  "zod": "^4.4.3"
+ },
+ "overrides": {
+ "@opentelemetry/core": "^2.10.0"
  }
 }

scripts/build.ts

@@ -21,6 +21,29 @@ function discoverAssets(): string[] {
  return files.sort().map((relativePath) => join(ASSETS_DIR, relativePath));
 }
 
+/**
+ * Stage the prebuilt Agent Inspector SPA into the asset tree (gitignored) so
+ * both distribution paths ship it through the ordinary asset machinery:
+ * `bundle` mirrors it into dist/assets/, `compile` embeds it in the binary.
+ * Every file gains a neutral `.asset` suffix — compile passes assets as
+ * Bun.build entrypoints, and a bare .html entrypoint would be bundled through
+ * Bun's HTML-imports pipeline instead of embedded verbatim. InspectorAssets
+ * strips the suffix when reading.
+ */
+async function stageInspectorAssets(): Promise<void> {
+ const source = join(REPO_ROOT, "node_modules", "@aws", "agent-inspector", "dist-assets");
+ if (!(await Bun.file(join(source, "index.html")).exists())) {
+ throw new Error("@aws/agent-inspector is not installed — run `bun install` before building.");
+ }
+ const target = join(ASSETS_DIR, "agent-inspector");
+ await $`rm -rf ${target}`;
+ await $`mkdir -p ${target}`;
+ const files = [...new Bun.Glob("**/*").scanSync({ cwd: source, onlyFiles: true })];
+ for (const file of files) {
+ await $`cp ${join(source, file)} ${join(target, `${file}.asset`)}`;
+ }
+}
+
 /** Force asset files through the file loader so template .ts/.js are embedded as bytes, not compiled. */
 function assetLoaderPlugin(): Bun.BunPlugin {
  return {
@@ -49,6 +72,7 @@ async function assertAssetsAreText(assets: string[]): Promise<void> {
 // Bun.build rejects with an AggregateError on failure (throw defaults to true),
 // so build errors propagate to runWithExitCode like any other.
 async function bundle(): Promise<void> {
+ await stageInspectorAssets();
  await Bun.build({
  entrypoints: [ENTRYPOINT],
  outdir: DIST,
@@ -64,6 +88,7 @@ async function bundle(): Promise<void> {
 }
 
 async function compile(target: string): Promise<void> {
+ await stageInspectorAssets();
  const assets = discoverAssets();
  await assertAssetsAreText(assets);
 

src/assets/templates/shared/env.local.template

@@ -1,7 +1,11 @@
 # Environment variables for local development.
 # `agentcore project dev` loads this file into your agent's process. Values here
 # override injected values except PORT, FASTMCP_PORT, and LOCAL_DEV, which the
-# CLI owns. This file is gitignored — keep secrets out of version control.
+# CLI owns. While trace collection is on (the default), the CLI also owns the
+# OTEL_* and AGENT_OBSERVABILITY_ENABLED variables so traces reach its local
+# collector — pass --no-traces (or set instrumentation.enableOtel to false in
+# agentcore.json) to disable collection and set your own.
+# This file is gitignored — keep secrets out of version control.
 #
 # Example:
 # MY_API_KEY=...

src/core/dev/codezip.test.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { delimiter, join, relative } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { ProjectRuntime } from "../../projectSchemas/runtime";
 import type { DevEvent, DevServerInput } from "../../handlers/project/dev/types";
-import type { ProcessEvent, ProcessStreamer, StreamProcessOptions } from "../../io";
+import type { ProcessEvent, ProcessRunner, ProcessStreamer, StreamProcessOptions } from "../../io";
 import { CodeZipDevRunner } from "./codezip";
 
 type ProcessCall = {
@@ -54,15 +54,22 @@ async function projectRoot(withNodeModules = false): Promise<string> {
  return root;
 }
 
-function harness(output: ProcessEvent[] = []) {
+function harness(output: ProcessEvent[] = [], probe: { dir?: string; fail?: boolean } = {}) {
  const calls: ProcessCall[] = [];
+ const probeCalls: string[][] = [];
  const fakeStreamProcess: ProcessStreamer = async function* (command, options) {
  calls.push({ command, options });
  yield* output;
  };
+ const fakeRunProcess: ProcessRunner = async (command, options) => {
+ probeCalls.push(command);
+ if (probe.fail) throw new Error("probe failed");
+ options.onOutput?.(`${probe.dir ?? ""}\n`);
+ };
  return {
  calls,
- runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess }),
+ probeCalls,
+ runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess, runProcess: fakeRunProcess }),
  };
 }
 
@@ -193,3 +200,69 @@ describe("CodeZipDevRunner", () => {
  ]);
  });
 });
+
+describe("CodeZipDevRunner OTEL instrumentation", () => {
+ async function sitecustomizeDir(): Promise<string> {
+ const directory = await mkdtemp(join(tmpdir(), "otel-site-"));
+ tempDirectories.push(directory);
+ await writeFile(join(directory, "sitecustomize.py"), "");
+ return directory;
+ }
+
+ function otelInput(root: string, extraEnv: Record<string, string> = {}): DevServerInput {
+ const base = input(root, runtime());
+ return {
+ ...base,
+ env: { ...base.env, OTEL_EXPORTER_OTLP_ENDPOINT: "http://127.0.0.1:4318", ...extraEnv },
+ };
+ }
+
+ test("prepends the sitecustomize directory to PYTHONPATH when instrumentation is installed", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, probeCalls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls[0]?.slice(0, 4)).toEqual(["uv", "run", "python", "-c"]);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(directory);
+ });
+
+ test("preserves an existing PYTHONPATH", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root, { PYTHONPATH: "/existing" })));
+
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(`${directory}${delimiter}/existing`);
+ });
+
+ test("does not probe without an OTEL endpoint or for Node entrypoints", async () => {
+ const root = await projectRoot(true);
+ const { probeCalls, runner } = harness();
+
+ await collect(runner.run(input(root, runtime())));
+ await collect(runner.run({ ...otelInput(root), runtime: runtime({ entrypoint: "index.js" }) }));
+
+ expect(probeCalls).toEqual([]);
+ });
+
+ test.each([
+ ["probe failure", { fail: true }],
+ ["missing sitecustomize.py", { dir: "/nonexistent" }],
+ ] as const)("warns and starts untraced on %s", async (_case, probe) => {
+ const root = await projectRoot();
+ const { calls, probeCalls, runner } = harness([], probe);
+
+ const events = await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls).toHaveLength(1);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBeUndefined();
+ expect(events).toContainEqual({
+ type: "status",
+ message: expect.stringContaining("traces will not be collected"),
+ });
+ });
+});

src/core/dev/codezip.ts

@@ -1,19 +1,28 @@
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
-import { streamProcess, type ProcessStreamer, type StreamProcessOptions } from "../../io";
+import {
+ runProcess,
+ streamProcess,
+ type ProcessRunner,
+ type ProcessStreamer,
+ type StreamProcessOptions,
+} from "../../io";
 import { isDirectory, isFile, resolvePathWithinProject } from "./path";
 
 type CodeZipDevRunnerConfig = {
  streamProcess?: ProcessStreamer;
+ runProcess?: ProcessRunner;
 };
 
 export class CodeZipDevRunner implements DevRunner {
  private readonly streamProcess: ProcessStreamer;
+ private readonly runProcess: ProcessRunner;
 
  constructor(config: CodeZipDevRunnerConfig = {}) {
  this.streamProcess = config.streamProcess ?? streamProcess;
+ this.runProcess = config.runProcess ?? runProcess;
  }
 
  public async *run(input: DevServerInput): AsyncGenerator<DevEvent, void> {
@@ -41,8 +50,48 @@ export class CodeZipDevRunner implements DevRunner {
 
  yield { type: "status", message: "Starting development server" };
  const serverProcess = commandForRuntime(entrypoint!, directory, input);
+ if (entrypoint!.endsWith(".py") && input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) {
+ const sitecustomizeDir = await this.findOtelSitecustomizeDir(directory);
+ if (sitecustomizeDir) {
+ const existing = serverProcess.options.env?.PYTHONPATH;
+ serverProcess.options.env = {
+ ...serverProcess.options.env,
+ PYTHONPATH: existing ? `${sitecustomizeDir}${delimiter}${existing}` : sitecustomizeDir,
+ };
+ } else {
+ yield {
+ type: "status",
+ message:
+ "OTEL auto-instrumentation is not installed in the agent environment; traces will not be collected. Add aws-opentelemetry-distro to the agent's dependencies to enable them.",
+ };
+ }
+ }
  yield* this.streamProcess(serverProcess.command, serverProcess.options);
  }
+
+ /**
+ * Locate the auto-instrumentation sitecustomize.py directory inside the agent's
+ * uv environment. Prepending it to PYTHONPATH instruments every Python process —
+ * an `opentelemetry-instrument` wrapper would only instrument uvicorn's reloader
+ * parent, leaving the re-spawned worker processes untraced.
+ */
+ private async findOtelSitecustomizeDir(directory: string): Promise<string | undefined> {
+ const output: string[] = [];
+ const probe =
+ "import opentelemetry.instrumentation.auto_instrumentation as m; import os; print(os.path.dirname(m.__file__))";
+ try {
+ await this.runProcess(["uv", "run", "python", "-c", probe], {
+ cwd: directory,
+ onOutput: (chunk) => output.push(chunk),
+ });
+ } catch {
+ return undefined;
+ }
+ const sitecustomizeDir = output.join("").trim().split("\n").at(-1)?.trim();
+ if (!sitecustomizeDir || !existsSync(join(sitecustomizeDir, "sitecustomize.py")))
+ return undefined;
+ return sitecustomizeDir;
+ }
 }
 
 function commandForRuntime(

.gitignore

@@ -35,3 +35,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .DS_Store
 
 .agentreview
+src/assets/agent-inspector/

package.json

@@ -56,8 +56,10 @@
  "@aws-sdk/client-bedrock-agentcore-control": "^3.1102.0",
  "@aws-sdk/client-cloudwatch-logs": "^3.1092.0",
  "@aws-sdk/client-iam": "^3.1080.0",
+ "@aws/agent-inspector": "0.6.1",
  "@opentelemetry/api": "^1.9.1",
  "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+ "@opentelemetry/otlp-transformer": "0.213.0",
  "@opentelemetry/resources": "^2.10.0",
  "@opentelemetry/sdk-metrics": "^2.10.0",
  "@smithy/core": "3.29.3",
@@ -75,5 +77,8 @@
  "winston": "^3.19.0",
  "winston-daily-rotate-file": "^5.0.0",
  "zod": "^4.4.3"
+ },
+ "overrides": {
+ "@opentelemetry/core": "^2.10.0"
  }
 }

scripts/build.ts

@@ -21,6 +21,29 @@ function discoverAssets(): string[] {
  return files.sort().map((relativePath) => join(ASSETS_DIR, relativePath));
 }
 
+/**
+ * Stage the prebuilt Agent Inspector SPA into the asset tree (gitignored) so
+ * both distribution paths ship it through the ordinary asset machinery:
+ * `bundle` mirrors it into dist/assets/, `compile` embeds it in the binary.
+ * Every file gains a neutral `.asset` suffix — compile passes assets as
+ * Bun.build entrypoints, and a bare .html entrypoint would be bundled through
+ * Bun's HTML-imports pipeline instead of embedded verbatim. InspectorAssets
+ * strips the suffix when reading.
+ */
+async function stageInspectorAssets(): Promise<void> {
+ const source = join(REPO_ROOT, "node_modules", "@aws", "agent-inspector", "dist-assets");
+ if (!(await Bun.file(join(source, "index.html")).exists())) {
+ throw new Error("@aws/agent-inspector is not installed — run `bun install` before building.");
+ }
+ const target = join(ASSETS_DIR, "agent-inspector");
+ await $`rm -rf ${target}`;
+ await $`mkdir -p ${target}`;
+ const files = [...new Bun.Glob("**/*").scanSync({ cwd: source, onlyFiles: true })];
+ for (const file of files) {
+ await $`cp ${join(source, file)} ${join(target, `${file}.asset`)}`;
+ }
+}
+
 /** Force asset files through the file loader so template .ts/.js are embedded as bytes, not compiled. */
 function assetLoaderPlugin(): Bun.BunPlugin {
  return {
@@ -49,6 +72,7 @@ async function assertAssetsAreText(assets: string[]): Promise<void> {
 // Bun.build rejects with an AggregateError on failure (throw defaults to true),
 // so build errors propagate to runWithExitCode like any other.
 async function bundle(): Promise<void> {
+ await stageInspectorAssets();
  await Bun.build({
  entrypoints: [ENTRYPOINT],
  outdir: DIST,
@@ -64,6 +88,7 @@ async function bundle(): Promise<void> {
 }
 
 async function compile(target: string): Promise<void> {
+ await stageInspectorAssets();
  const assets = discoverAssets();
  await assertAssetsAreText(assets);
 

src/assets/templates/shared/env.local.template

@@ -1,7 +1,11 @@
 # Environment variables for local development.
 # `agentcore project dev` loads this file into your agent's process. Values here
 # override injected values except PORT, FASTMCP_PORT, and LOCAL_DEV, which the
-# CLI owns. This file is gitignored — keep secrets out of version control.
+# CLI owns. While trace collection is on (the default), the CLI also owns the
+# OTEL_* and AGENT_OBSERVABILITY_ENABLED variables so traces reach its local
+# collector — pass --no-traces (or set instrumentation.enableOtel to false in
+# agentcore.json) to disable collection and set your own.
+# This file is gitignored — keep secrets out of version control.
 #
 # Example:
 # MY_API_KEY=...

src/core/dev/codezip.test.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { delimiter, join, relative } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { ProjectRuntime } from "../../projectSchemas/runtime";
 import type { DevEvent, DevServerInput } from "../../handlers/project/dev/types";
-import type { ProcessEvent, ProcessStreamer, StreamProcessOptions } from "../../io";
+import type { ProcessEvent, ProcessRunner, ProcessStreamer, StreamProcessOptions } from "../../io";
 import { CodeZipDevRunner } from "./codezip";
 
 type ProcessCall = {
@@ -54,15 +54,22 @@ async function projectRoot(withNodeModules = false): Promise<string> {
  return root;
 }
 
-function harness(output: ProcessEvent[] = []) {
+function harness(output: ProcessEvent[] = [], probe: { dir?: string; fail?: boolean } = {}) {
  const calls: ProcessCall[] = [];
+ const probeCalls: string[][] = [];
  const fakeStreamProcess: ProcessStreamer = async function* (command, options) {
  calls.push({ command, options });
  yield* output;
  };
+ const fakeRunProcess: ProcessRunner = async (command, options) => {
+ probeCalls.push(command);
+ if (probe.fail) throw new Error("probe failed");
+ options.onOutput?.(`${probe.dir ?? ""}\n`);
+ };
  return {
  calls,
- runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess }),
+ probeCalls,
+ runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess, runProcess: fakeRunProcess }),
  };
 }
 
@@ -193,3 +200,69 @@ describe("CodeZipDevRunner", () => {
  ]);
  });
 });
+
+describe("CodeZipDevRunner OTEL instrumentation", () => {
+ async function sitecustomizeDir(): Promise<string> {
+ const directory = await mkdtemp(join(tmpdir(), "otel-site-"));
+ tempDirectories.push(directory);
+ await writeFile(join(directory, "sitecustomize.py"), "");
+ return directory;
+ }
+
+ function otelInput(root: string, extraEnv: Record<string, string> = {}): DevServerInput {
+ const base = input(root, runtime());
+ return {
+ ...base,
+ env: { ...base.env, OTEL_EXPORTER_OTLP_ENDPOINT: "http://127.0.0.1:4318", ...extraEnv },
+ };
+ }
+
+ test("prepends the sitecustomize directory to PYTHONPATH when instrumentation is installed", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, probeCalls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls[0]?.slice(0, 4)).toEqual(["uv", "run", "python", "-c"]);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(directory);
+ });
+
+ test("preserves an existing PYTHONPATH", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root, { PYTHONPATH: "/existing" })));
+
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(`${directory}${delimiter}/existing`);
+ });
+
+ test("does not probe without an OTEL endpoint or for Node entrypoints", async () => {
+ const root = await projectRoot(true);
+ const { probeCalls, runner } = harness();
+
+ await collect(runner.run(input(root, runtime())));
+ await collect(runner.run({ ...otelInput(root), runtime: runtime({ entrypoint: "index.js" }) }));
+
+ expect(probeCalls).toEqual([]);
+ });
+
+ test.each([
+ ["probe failure", { fail: true }],
+ ["missing sitecustomize.py", { dir: "/nonexistent" }],
+ ] as const)("warns and starts untraced on %s", async (_case, probe) => {
+ const root = await projectRoot();
+ const { calls, probeCalls, runner } = harness([], probe);
+
+ const events = await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls).toHaveLength(1);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBeUndefined();
+ expect(events).toContainEqual({
+ type: "status",
+ message: expect.stringContaining("traces will not be collected"),
+ });
+ });
+});

src/core/dev/codezip.ts

@@ -1,19 +1,28 @@
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
-import { streamProcess, type ProcessStreamer, type StreamProcessOptions } from "../../io";
+import {
+ runProcess,
+ streamProcess,
+ type ProcessRunner,
+ type ProcessStreamer,
+ type StreamProcessOptions,
+} from "../../io";
 import { isDirectory, isFile, resolvePathWithinProject } from "./path";
 
 type CodeZipDevRunnerConfig = {
  streamProcess?: ProcessStreamer;
+ runProcess?: ProcessRunner;
 };
 
 export class CodeZipDevRunner implements DevRunner {
  private readonly streamProcess: ProcessStreamer;
+ private readonly runProcess: ProcessRunner;
 
  constructor(config: CodeZipDevRunnerConfig = {}) {
  this.streamProcess = config.streamProcess ?? streamProcess;
+ this.runProcess = config.runProcess ?? runProcess;
  }
 
  public async *run(input: DevServerInput): AsyncGenerator<DevEvent, void> {
@@ -41,8 +50,48 @@ export class CodeZipDevRunner implements DevRunner {
 
  yield { type: "status", message: "Starting development server" };
  const serverProcess = commandForRuntime(entrypoint!, directory, input);
+ if (entrypoint!.endsWith(".py") && input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) {
+ const sitecustomizeDir = await this.findOtelSitecustomizeDir(directory);
+ if (sitecustomizeDir) {
+ const existing = serverProcess.options.env?.PYTHONPATH;
+ serverProcess.options.env = {
+ ...serverProcess.options.env,
+ PYTHONPATH: existing ? `${sitecustomizeDir}${delimiter}${existing}` : sitecustomizeDir,
+ };
+ } else {
+ yield {
+ type: "status",
+ message:
+ "OTEL auto-instrumentation is not installed in the agent environment; traces will not be collected. Add aws-opentelemetry-distro to the agent's dependencies to enable them.",
+ };
+ }
+ }
  yield* this.streamProcess(serverProcess.command, serverProcess.options);
  }
+
+ /**
+ * Locate the auto-instrumentation sitecustomize.py directory inside the agent's
+ * uv environment. Prepending it to PYTHONPATH instruments every Python process —
+ * an `opentelemetry-instrument` wrapper would only instrument uvicorn's reloader
+ * parent, leaving the re-spawned worker processes untraced.
+ */
+ private async findOtelSitecustomizeDir(directory: string): Promise<string | undefined> {
+ const output: string[] = [];
+ const probe =
+ "import opentelemetry.instrumentation.auto_instrumentation as m; import os; print(os.path.dirname(m.__file__))";
+ try {
+ await this.runProcess(["uv", "run", "python", "-c", probe], {
+ cwd: directory,
+ onOutput: (chunk) => output.push(chunk),
+ });
+ } catch {
+ return undefined;
+ }
+ const sitecustomizeDir = output.join("").trim().split("\n").at(-1)?.trim();
+ if (!sitecustomizeDir || !existsSync(join(sitecustomizeDir, "sitecustomize.py")))
+ return undefined;
+ return sitecustomizeDir;
+ }
 }
 
 function commandForRuntime(

.gitignore

@@ -35,3 +35,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .DS_Store
 
 .agentreview
+src/assets/agent-inspector/

package.json

@@ -56,8 +56,10 @@
  "@aws-sdk/client-bedrock-agentcore-control": "^3.1102.0",
  "@aws-sdk/client-cloudwatch-logs": "^3.1092.0",
  "@aws-sdk/client-iam": "^3.1080.0",
+ "@aws/agent-inspector": "0.6.1",
  "@opentelemetry/api": "^1.9.1",
  "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+ "@opentelemetry/otlp-transformer": "0.213.0",
  "@opentelemetry/resources": "^2.10.0",
  "@opentelemetry/sdk-metrics": "^2.10.0",
  "@smithy/core": "3.29.3",
@@ -75,5 +77,8 @@
  "winston": "^3.19.0",
  "winston-daily-rotate-file": "^5.0.0",
  "zod": "^4.4.3"
+ },
+ "overrides": {
+ "@opentelemetry/core": "^2.10.0"
  }
 }

scripts/build.ts

@@ -21,6 +21,29 @@ function discoverAssets(): string[] {
  return files.sort().map((relativePath) => join(ASSETS_DIR, relativePath));
 }
 
+/**
+ * Stage the prebuilt Agent Inspector SPA into the asset tree (gitignored) so
+ * both distribution paths ship it through the ordinary asset machinery:
+ * `bundle` mirrors it into dist/assets/, `compile` embeds it in the binary.
+ * Every file gains a neutral `.asset` suffix — compile passes assets as
+ * Bun.build entrypoints, and a bare .html entrypoint would be bundled through
+ * Bun's HTML-imports pipeline instead of embedded verbatim. InspectorAssets
+ * strips the suffix when reading.
+ */
+async function stageInspectorAssets(): Promise<void> {
+ const source = join(REPO_ROOT, "node_modules", "@aws", "agent-inspector", "dist-assets");
+ if (!(await Bun.file(join(source, "index.html")).exists())) {
+ throw new Error("@aws/agent-inspector is not installed — run `bun install` before building.");
+ }
+ const target = join(ASSETS_DIR, "agent-inspector");
+ await $`rm -rf ${target}`;
+ await $`mkdir -p ${target}`;
+ const files = [...new Bun.Glob("**/*").scanSync({ cwd: source, onlyFiles: true })];
+ for (const file of files) {
+ await $`cp ${join(source, file)} ${join(target, `${file}.asset`)}`;
+ }
+}
+
 /** Force asset files through the file loader so template .ts/.js are embedded as bytes, not compiled. */
 function assetLoaderPlugin(): Bun.BunPlugin {
  return {
@@ -49,6 +72,7 @@ async function assertAssetsAreText(assets: string[]): Promise<void> {
 // Bun.build rejects with an AggregateError on failure (throw defaults to true),
 // so build errors propagate to runWithExitCode like any other.
 async function bundle(): Promise<void> {
+ await stageInspectorAssets();
  await Bun.build({
  entrypoints: [ENTRYPOINT],
  outdir: DIST,
@@ -64,6 +88,7 @@ async function bundle(): Promise<void> {
 }
 
 async function compile(target: string): Promise<void> {
+ await stageInspectorAssets();
  const assets = discoverAssets();
  await assertAssetsAreText(assets);
 

src/assets/templates/shared/env.local.template

@@ -1,7 +1,11 @@
 # Environment variables for local development.
 # `agentcore project dev` loads this file into your agent's process. Values here
 # override injected values except PORT, FASTMCP_PORT, and LOCAL_DEV, which the
-# CLI owns. This file is gitignored — keep secrets out of version control.
+# CLI owns. While trace collection is on (the default), the CLI also owns the
+# OTEL_* and AGENT_OBSERVABILITY_ENABLED variables so traces reach its local
+# collector — pass --no-traces (or set instrumentation.enableOtel to false in
+# agentcore.json) to disable collection and set your own.
+# This file is gitignored — keep secrets out of version control.
 #
 # Example:
 # MY_API_KEY=...

src/core/dev/codezip.test.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { delimiter, join, relative } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { ProjectRuntime } from "../../projectSchemas/runtime";
 import type { DevEvent, DevServerInput } from "../../handlers/project/dev/types";
-import type { ProcessEvent, ProcessStreamer, StreamProcessOptions } from "../../io";
+import type { ProcessEvent, ProcessRunner, ProcessStreamer, StreamProcessOptions } from "../../io";
 import { CodeZipDevRunner } from "./codezip";
 
 type ProcessCall = {
@@ -54,15 +54,22 @@ async function projectRoot(withNodeModules = false): Promise<string> {
  return root;
 }
 
-function harness(output: ProcessEvent[] = []) {
+function harness(output: ProcessEvent[] = [], probe: { dir?: string; fail?: boolean } = {}) {
  const calls: ProcessCall[] = [];
+ const probeCalls: string[][] = [];
  const fakeStreamProcess: ProcessStreamer = async function* (command, options) {
  calls.push({ command, options });
  yield* output;
  };
+ const fakeRunProcess: ProcessRunner = async (command, options) => {
+ probeCalls.push(command);
+ if (probe.fail) throw new Error("probe failed");
+ options.onOutput?.(`${probe.dir ?? ""}\n`);
+ };
  return {
  calls,
- runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess }),
+ probeCalls,
+ runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess, runProcess: fakeRunProcess }),
  };
 }
 
@@ -193,3 +200,69 @@ describe("CodeZipDevRunner", () => {
  ]);
  });
 });
+
+describe("CodeZipDevRunner OTEL instrumentation", () => {
+ async function sitecustomizeDir(): Promise<string> {
+ const directory = await mkdtemp(join(tmpdir(), "otel-site-"));
+ tempDirectories.push(directory);
+ await writeFile(join(directory, "sitecustomize.py"), "");
+ return directory;
+ }
+
+ function otelInput(root: string, extraEnv: Record<string, string> = {}): DevServerInput {
+ const base = input(root, runtime());
+ return {
+ ...base,
+ env: { ...base.env, OTEL_EXPORTER_OTLP_ENDPOINT: "http://127.0.0.1:4318", ...extraEnv },
+ };
+ }
+
+ test("prepends the sitecustomize directory to PYTHONPATH when instrumentation is installed", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, probeCalls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls[0]?.slice(0, 4)).toEqual(["uv", "run", "python", "-c"]);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(directory);
+ });
+
+ test("preserves an existing PYTHONPATH", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root, { PYTHONPATH: "/existing" })));
+
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(`${directory}${delimiter}/existing`);
+ });
+
+ test("does not probe without an OTEL endpoint or for Node entrypoints", async () => {
+ const root = await projectRoot(true);
+ const { probeCalls, runner } = harness();
+
+ await collect(runner.run(input(root, runtime())));
+ await collect(runner.run({ ...otelInput(root), runtime: runtime({ entrypoint: "index.js" }) }));
+
+ expect(probeCalls).toEqual([]);
+ });
+
+ test.each([
+ ["probe failure", { fail: true }],
+ ["missing sitecustomize.py", { dir: "/nonexistent" }],
+ ] as const)("warns and starts untraced on %s", async (_case, probe) => {
+ const root = await projectRoot();
+ const { calls, probeCalls, runner } = harness([], probe);
+
+ const events = await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls).toHaveLength(1);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBeUndefined();
+ expect(events).toContainEqual({
+ type: "status",
+ message: expect.stringContaining("traces will not be collected"),
+ });
+ });
+});

src/core/dev/codezip.ts

@@ -1,19 +1,28 @@
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
-import { streamProcess, type ProcessStreamer, type StreamProcessOptions } from "../../io";
+import {
+ runProcess,
+ streamProcess,
+ type ProcessRunner,
+ type ProcessStreamer,
+ type StreamProcessOptions,
+} from "../../io";
 import { isDirectory, isFile, resolvePathWithinProject } from "./path";
 
 type CodeZipDevRunnerConfig = {
  streamProcess?: ProcessStreamer;
+ runProcess?: ProcessRunner;
 };
 
 export class CodeZipDevRunner implements DevRunner {
  private readonly streamProcess: ProcessStreamer;
+ private readonly runProcess: ProcessRunner;
 
  constructor(config: CodeZipDevRunnerConfig = {}) {
  this.streamProcess = config.streamProcess ?? streamProcess;
+ this.runProcess = config.runProcess ?? runProcess;
  }
 
  public async *run(input: DevServerInput): AsyncGenerator<DevEvent, void> {
@@ -41,8 +50,48 @@ export class CodeZipDevRunner implements DevRunner {
 
  yield { type: "status", message: "Starting development server" };
  const serverProcess = commandForRuntime(entrypoint!, directory, input);
+ if (entrypoint!.endsWith(".py") && input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) {
+ const sitecustomizeDir = await this.findOtelSitecustomizeDir(directory);
+ if (sitecustomizeDir) {
+ const existing = serverProcess.options.env?.PYTHONPATH;
+ serverProcess.options.env = {
+ ...serverProcess.options.env,
+ PYTHONPATH: existing ? `${sitecustomizeDir}${delimiter}${existing}` : sitecustomizeDir,
+ };
+ } else {
+ yield {
+ type: "status",
+ message:
+ "OTEL auto-instrumentation is not installed in the agent environment; traces will not be collected. Add aws-opentelemetry-distro to the agent's dependencies to enable them.",
+ };
+ }
+ }
  yield* this.streamProcess(serverProcess.command, serverProcess.options);
  }
+
+ /**
+ * Locate the auto-instrumentation sitecustomize.py directory inside the agent's
+ * uv environment. Prepending it to PYTHONPATH instruments every Python process —
+ * an `opentelemetry-instrument` wrapper would only instrument uvicorn's reloader
+ * parent, leaving the re-spawned worker processes untraced.
+ */
+ private async findOtelSitecustomizeDir(directory: string): Promise<string | undefined> {
+ const output: string[] = [];
+ const probe =
+ "import opentelemetry.instrumentation.auto_instrumentation as m; import os; print(os.path.dirname(m.__file__))";
+ try {
+ await this.runProcess(["uv", "run", "python", "-c", probe], {
+ cwd: directory,
+ onOutput: (chunk) => output.push(chunk),
+ });
+ } catch {
+ return undefined;
+ }
+ const sitecustomizeDir = output.join("").trim().split("\n").at(-1)?.trim();
+ if (!sitecustomizeDir || !existsSync(join(sitecustomizeDir, "sitecustomize.py")))
+ return undefined;
+ return sitecustomizeDir;
+ }
 }
 
 function commandForRuntime(

.gitignore

@@ -35,3 +35,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .DS_Store
 
 .agentreview
+src/assets/agent-inspector/

package.json

@@ -56,8 +56,10 @@
  "@aws-sdk/client-bedrock-agentcore-control": "^3.1102.0",
  "@aws-sdk/client-cloudwatch-logs": "^3.1092.0",
  "@aws-sdk/client-iam": "^3.1080.0",
+ "@aws/agent-inspector": "0.6.1",
  "@opentelemetry/api": "^1.9.1",
  "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+ "@opentelemetry/otlp-transformer": "0.213.0",
  "@opentelemetry/resources": "^2.10.0",
  "@opentelemetry/sdk-metrics": "^2.10.0",
  "@smithy/core": "3.29.3",
@@ -75,5 +77,8 @@
  "winston": "^3.19.0",
  "winston-daily-rotate-file": "^5.0.0",
  "zod": "^4.4.3"
+ },
+ "overrides": {
+ "@opentelemetry/core": "^2.10.0"
  }
 }

scripts/build.ts

@@ -21,6 +21,29 @@ function discoverAssets(): string[] {
  return files.sort().map((relativePath) => join(ASSETS_DIR, relativePath));
 }
 
+/**
+ * Stage the prebuilt Agent Inspector SPA into the asset tree (gitignored) so
+ * both distribution paths ship it through the ordinary asset machinery:
+ * `bundle` mirrors it into dist/assets/, `compile` embeds it in the binary.
+ * Every file gains a neutral `.asset` suffix — compile passes assets as
+ * Bun.build entrypoints, and a bare .html entrypoint would be bundled through
+ * Bun's HTML-imports pipeline instead of embedded verbatim. InspectorAssets
+ * strips the suffix when reading.
+ */
+async function stageInspectorAssets(): Promise<void> {
+ const source = join(REPO_ROOT, "node_modules", "@aws", "agent-inspector", "dist-assets");
+ if (!(await Bun.file(join(source, "index.html")).exists())) {
+ throw new Error("@aws/agent-inspector is not installed — run `bun install` before building.");
+ }
+ const target = join(ASSETS_DIR, "agent-inspector");
+ await $`rm -rf ${target}`;
+ await $`mkdir -p ${target}`;
+ const files = [...new Bun.Glob("**/*").scanSync({ cwd: source, onlyFiles: true })];
+ for (const file of files) {
+ await $`cp ${join(source, file)} ${join(target, `${file}.asset`)}`;
+ }
+}
+
 /** Force asset files through the file loader so template .ts/.js are embedded as bytes, not compiled. */
 function assetLoaderPlugin(): Bun.BunPlugin {
  return {
@@ -49,6 +72,7 @@ async function assertAssetsAreText(assets: string[]): Promise<void> {
 // Bun.build rejects with an AggregateError on failure (throw defaults to true),
 // so build errors propagate to runWithExitCode like any other.
 async function bundle(): Promise<void> {
+ await stageInspectorAssets();
  await Bun.build({
  entrypoints: [ENTRYPOINT],
  outdir: DIST,
@@ -64,6 +88,7 @@ async function bundle(): Promise<void> {
 }
 
 async function compile(target: string): Promise<void> {
+ await stageInspectorAssets();
  const assets = discoverAssets();
  await assertAssetsAreText(assets);
 

src/assets/templates/shared/env.local.template

@@ -1,7 +1,11 @@
 # Environment variables for local development.
 # `agentcore project dev` loads this file into your agent's process. Values here
 # override injected values except PORT, FASTMCP_PORT, and LOCAL_DEV, which the
-# CLI owns. This file is gitignored — keep secrets out of version control.
+# CLI owns. While trace collection is on (the default), the CLI also owns the
+# OTEL_* and AGENT_OBSERVABILITY_ENABLED variables so traces reach its local
+# collector — pass --no-traces (or set instrumentation.enableOtel to false in
+# agentcore.json) to disable collection and set your own.
+# This file is gitignored — keep secrets out of version control.
 #
 # Example:
 # MY_API_KEY=...

src/core/dev/codezip.test.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { delimiter, join, relative } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { ProjectRuntime } from "../../projectSchemas/runtime";
 import type { DevEvent, DevServerInput } from "../../handlers/project/dev/types";
-import type { ProcessEvent, ProcessStreamer, StreamProcessOptions } from "../../io";
+import type { ProcessEvent, ProcessRunner, ProcessStreamer, StreamProcessOptions } from "../../io";
 import { CodeZipDevRunner } from "./codezip";
 
 type ProcessCall = {
@@ -54,15 +54,22 @@ async function projectRoot(withNodeModules = false): Promise<string> {
  return root;
 }
 
-function harness(output: ProcessEvent[] = []) {
+function harness(output: ProcessEvent[] = [], probe: { dir?: string; fail?: boolean } = {}) {
  const calls: ProcessCall[] = [];
+ const probeCalls: string[][] = [];
  const fakeStreamProcess: ProcessStreamer = async function* (command, options) {
  calls.push({ command, options });
  yield* output;
  };
+ const fakeRunProcess: ProcessRunner = async (command, options) => {
+ probeCalls.push(command);
+ if (probe.fail) throw new Error("probe failed");
+ options.onOutput?.(`${probe.dir ?? ""}\n`);
+ };
  return {
  calls,
- runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess }),
+ probeCalls,
+ runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess, runProcess: fakeRunProcess }),
  };
 }
 
@@ -193,3 +200,69 @@ describe("CodeZipDevRunner", () => {
  ]);
  });
 });
+
+describe("CodeZipDevRunner OTEL instrumentation", () => {
+ async function sitecustomizeDir(): Promise<string> {
+ const directory = await mkdtemp(join(tmpdir(), "otel-site-"));
+ tempDirectories.push(directory);
+ await writeFile(join(directory, "sitecustomize.py"), "");
+ return directory;
+ }
+
+ function otelInput(root: string, extraEnv: Record<string, string> = {}): DevServerInput {
+ const base = input(root, runtime());
+ return {
+ ...base,
+ env: { ...base.env, OTEL_EXPORTER_OTLP_ENDPOINT: "http://127.0.0.1:4318", ...extraEnv },
+ };
+ }
+
+ test("prepends the sitecustomize directory to PYTHONPATH when instrumentation is installed", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, probeCalls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls[0]?.slice(0, 4)).toEqual(["uv", "run", "python", "-c"]);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(directory);
+ });
+
+ test("preserves an existing PYTHONPATH", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root, { PYTHONPATH: "/existing" })));
+
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(`${directory}${delimiter}/existing`);
+ });
+
+ test("does not probe without an OTEL endpoint or for Node entrypoints", async () => {
+ const root = await projectRoot(true);
+ const { probeCalls, runner } = harness();
+
+ await collect(runner.run(input(root, runtime())));
+ await collect(runner.run({ ...otelInput(root), runtime: runtime({ entrypoint: "index.js" }) }));
+
+ expect(probeCalls).toEqual([]);
+ });
+
+ test.each([
+ ["probe failure", { fail: true }],
+ ["missing sitecustomize.py", { dir: "/nonexistent" }],
+ ] as const)("warns and starts untraced on %s", async (_case, probe) => {
+ const root = await projectRoot();
+ const { calls, probeCalls, runner } = harness([], probe);
+
+ const events = await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls).toHaveLength(1);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBeUndefined();
+ expect(events).toContainEqual({
+ type: "status",
+ message: expect.stringContaining("traces will not be collected"),
+ });
+ });
+});

src/core/dev/codezip.ts

@@ -1,19 +1,28 @@
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
-import { streamProcess, type ProcessStreamer, type StreamProcessOptions } from "../../io";
+import {
+ runProcess,
+ streamProcess,
+ type ProcessRunner,
+ type ProcessStreamer,
+ type StreamProcessOptions,
+} from "../../io";
 import { isDirectory, isFile, resolvePathWithinProject } from "./path";
 
 type CodeZipDevRunnerConfig = {
  streamProcess?: ProcessStreamer;
+ runProcess?: ProcessRunner;
 };
 
 export class CodeZipDevRunner implements DevRunner {
  private readonly streamProcess: ProcessStreamer;
+ private readonly runProcess: ProcessRunner;
 
  constructor(config: CodeZipDevRunnerConfig = {}) {
  this.streamProcess = config.streamProcess ?? streamProcess;
+ this.runProcess = config.runProcess ?? runProcess;
  }
 
  public async *run(input: DevServerInput): AsyncGenerator<DevEvent, void> {
@@ -41,8 +50,48 @@ export class CodeZipDevRunner implements DevRunner {
 
  yield { type: "status", message: "Starting development server" };
  const serverProcess = commandForRuntime(entrypoint!, directory, input);
+ if (entrypoint!.endsWith(".py") && input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) {
+ const sitecustomizeDir = await this.findOtelSitecustomizeDir(directory);
+ if (sitecustomizeDir) {
+ const existing = serverProcess.options.env?.PYTHONPATH;
+ serverProcess.options.env = {
+ ...serverProcess.options.env,
+ PYTHONPATH: existing ? `${sitecustomizeDir}${delimiter}${existing}` : sitecustomizeDir,
+ };
+ } else {
+ yield {
+ type: "status",
+ message:
+ "OTEL auto-instrumentation is not installed in the agent environment; traces will not be collected. Add aws-opentelemetry-distro to the agent's dependencies to enable them.",
+ };
+ }
+ }
  yield* this.streamProcess(serverProcess.command, serverProcess.options);
  }
+
+ /**
+ * Locate the auto-instrumentation sitecustomize.py directory inside the agent's
+ * uv environment. Prepending it to PYTHONPATH instruments every Python process —
+ * an `opentelemetry-instrument` wrapper would only instrument uvicorn's reloader
+ * parent, leaving the re-spawned worker processes untraced.
+ */
+ private async findOtelSitecustomizeDir(directory: string): Promise<string | undefined> {
+ const output: string[] = [];
+ const probe =
+ "import opentelemetry.instrumentation.auto_instrumentation as m; import os; print(os.path.dirname(m.__file__))";
+ try {
+ await this.runProcess(["uv", "run", "python", "-c", probe], {
+ cwd: directory,
+ onOutput: (chunk) => output.push(chunk),
+ });
+ } catch {
+ return undefined;
+ }
+ const sitecustomizeDir = output.join("").trim().split("\n").at(-1)?.trim();
+ if (!sitecustomizeDir || !existsSync(join(sitecustomizeDir, "sitecustomize.py")))
+ return undefined;
+ return sitecustomizeDir;
+ }
 }
 
 function commandForRuntime(

.gitignore

@@ -35,3 +35,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .DS_Store
 
 .agentreview
+src/assets/agent-inspector/

package.json

@@ -56,8 +56,10 @@
  "@aws-sdk/client-bedrock-agentcore-control": "^3.1102.0",
  "@aws-sdk/client-cloudwatch-logs": "^3.1092.0",
  "@aws-sdk/client-iam": "^3.1080.0",
+ "@aws/agent-inspector": "0.6.1",
  "@opentelemetry/api": "^1.9.1",
  "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+ "@opentelemetry/otlp-transformer": "0.213.0",
  "@opentelemetry/resources": "^2.10.0",
  "@opentelemetry/sdk-metrics": "^2.10.0",
  "@smithy/core": "3.29.3",
@@ -75,5 +77,8 @@
  "winston": "^3.19.0",
  "winston-daily-rotate-file": "^5.0.0",
  "zod": "^4.4.3"
+ },
+ "overrides": {
+ "@opentelemetry/core": "^2.10.0"
  }
 }

scripts/build.ts

@@ -21,6 +21,29 @@ function discoverAssets(): string[] {
  return files.sort().map((relativePath) => join(ASSETS_DIR, relativePath));
 }
 
+/**
+ * Stage the prebuilt Agent Inspector SPA into the asset tree (gitignored) so
+ * both distribution paths ship it through the ordinary asset machinery:
+ * `bundle` mirrors it into dist/assets/, `compile` embeds it in the binary.
+ * Every file gains a neutral `.asset` suffix — compile passes assets as
+ * Bun.build entrypoints, and a bare .html entrypoint would be bundled through
+ * Bun's HTML-imports pipeline instead of embedded verbatim. InspectorAssets
+ * strips the suffix when reading.
+ */
+async function stageInspectorAssets(): Promise<void> {
+ const source = join(REPO_ROOT, "node_modules", "@aws", "agent-inspector", "dist-assets");
+ if (!(await Bun.file(join(source, "index.html")).exists())) {
+ throw new Error("@aws/agent-inspector is not installed — run `bun install` before building.");
+ }
+ const target = join(ASSETS_DIR, "agent-inspector");
+ await $`rm -rf ${target}`;
+ await $`mkdir -p ${target}`;
+ const files = [...new Bun.Glob("**/*").scanSync({ cwd: source, onlyFiles: true })];
+ for (const file of files) {
+ await $`cp ${join(source, file)} ${join(target, `${file}.asset`)}`;
+ }
+}
+
 /** Force asset files through the file loader so template .ts/.js are embedded as bytes, not compiled. */
 function assetLoaderPlugin(): Bun.BunPlugin {
  return {
@@ -49,6 +72,7 @@ async function assertAssetsAreText(assets: string[]): Promise<void> {
 // Bun.build rejects with an AggregateError on failure (throw defaults to true),
 // so build errors propagate to runWithExitCode like any other.
 async function bundle(): Promise<void> {
+ await stageInspectorAssets();
  await Bun.build({
  entrypoints: [ENTRYPOINT],
  outdir: DIST,
@@ -64,6 +88,7 @@ async function bundle(): Promise<void> {
 }
 
 async function compile(target: string): Promise<void> {
+ await stageInspectorAssets();
  const assets = discoverAssets();
  await assertAssetsAreText(assets);
 

src/assets/templates/shared/env.local.template

@@ -1,7 +1,11 @@
 # Environment variables for local development.
 # `agentcore project dev` loads this file into your agent's process. Values here
 # override injected values except PORT, FASTMCP_PORT, and LOCAL_DEV, which the
-# CLI owns. This file is gitignored — keep secrets out of version control.
+# CLI owns. While trace collection is on (the default), the CLI also owns the
+# OTEL_* and AGENT_OBSERVABILITY_ENABLED variables so traces reach its local
+# collector — pass --no-traces (or set instrumentation.enableOtel to false in
+# agentcore.json) to disable collection and set your own.
+# This file is gitignored — keep secrets out of version control.
 #
 # Example:
 # MY_API_KEY=...

src/core/dev/codezip.test.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { delimiter, join, relative } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { ProjectRuntime } from "../../projectSchemas/runtime";
 import type { DevEvent, DevServerInput } from "../../handlers/project/dev/types";
-import type { ProcessEvent, ProcessStreamer, StreamProcessOptions } from "../../io";
+import type { ProcessEvent, ProcessRunner, ProcessStreamer, StreamProcessOptions } from "../../io";
 import { CodeZipDevRunner } from "./codezip";
 
 type ProcessCall = {
@@ -54,15 +54,22 @@ async function projectRoot(withNodeModules = false): Promise<string> {
  return root;
 }
 
-function harness(output: ProcessEvent[] = []) {
+function harness(output: ProcessEvent[] = [], probe: { dir?: string; fail?: boolean } = {}) {
  const calls: ProcessCall[] = [];
+ const probeCalls: string[][] = [];
  const fakeStreamProcess: ProcessStreamer = async function* (command, options) {
  calls.push({ command, options });
  yield* output;
  };
+ const fakeRunProcess: ProcessRunner = async (command, options) => {
+ probeCalls.push(command);
+ if (probe.fail) throw new Error("probe failed");
+ options.onOutput?.(`${probe.dir ?? ""}\n`);
+ };
  return {
  calls,
- runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess }),
+ probeCalls,
+ runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess, runProcess: fakeRunProcess }),
  };
 }
 
@@ -193,3 +200,69 @@ describe("CodeZipDevRunner", () => {
  ]);
  });
 });
+
+describe("CodeZipDevRunner OTEL instrumentation", () => {
+ async function sitecustomizeDir(): Promise<string> {
+ const directory = await mkdtemp(join(tmpdir(), "otel-site-"));
+ tempDirectories.push(directory);
+ await writeFile(join(directory, "sitecustomize.py"), "");
+ return directory;
+ }
+
+ function otelInput(root: string, extraEnv: Record<string, string> = {}): DevServerInput {
+ const base = input(root, runtime());
+ return {
+ ...base,
+ env: { ...base.env, OTEL_EXPORTER_OTLP_ENDPOINT: "http://127.0.0.1:4318", ...extraEnv },
+ };
+ }
+
+ test("prepends the sitecustomize directory to PYTHONPATH when instrumentation is installed", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, probeCalls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls[0]?.slice(0, 4)).toEqual(["uv", "run", "python", "-c"]);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(directory);
+ });
+
+ test("preserves an existing PYTHONPATH", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root, { PYTHONPATH: "/existing" })));
+
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(`${directory}${delimiter}/existing`);
+ });
+
+ test("does not probe without an OTEL endpoint or for Node entrypoints", async () => {
+ const root = await projectRoot(true);
+ const { probeCalls, runner } = harness();
+
+ await collect(runner.run(input(root, runtime())));
+ await collect(runner.run({ ...otelInput(root), runtime: runtime({ entrypoint: "index.js" }) }));
+
+ expect(probeCalls).toEqual([]);
+ });
+
+ test.each([
+ ["probe failure", { fail: true }],
+ ["missing sitecustomize.py", { dir: "/nonexistent" }],
+ ] as const)("warns and starts untraced on %s", async (_case, probe) => {
+ const root = await projectRoot();
+ const { calls, probeCalls, runner } = harness([], probe);
+
+ const events = await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls).toHaveLength(1);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBeUndefined();
+ expect(events).toContainEqual({
+ type: "status",
+ message: expect.stringContaining("traces will not be collected"),
+ });
+ });
+});

src/core/dev/codezip.ts

@@ -1,19 +1,28 @@
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
-import { streamProcess, type ProcessStreamer, type StreamProcessOptions } from "../../io";
+import {
+ runProcess,
+ streamProcess,
+ type ProcessRunner,
+ type ProcessStreamer,
+ type StreamProcessOptions,
+} from "../../io";
 import { isDirectory, isFile, resolvePathWithinProject } from "./path";
 
 type CodeZipDevRunnerConfig = {
  streamProcess?: ProcessStreamer;
+ runProcess?: ProcessRunner;
 };
 
 export class CodeZipDevRunner implements DevRunner {
  private readonly streamProcess: ProcessStreamer;
+ private readonly runProcess: ProcessRunner;
 
  constructor(config: CodeZipDevRunnerConfig = {}) {
  this.streamProcess = config.streamProcess ?? streamProcess;
+ this.runProcess = config.runProcess ?? runProcess;
  }
 
  public async *run(input: DevServerInput): AsyncGenerator<DevEvent, void> {
@@ -41,8 +50,48 @@ export class CodeZipDevRunner implements DevRunner {
 
  yield { type: "status", message: "Starting development server" };
  const serverProcess = commandForRuntime(entrypoint!, directory, input);
+ if (entrypoint!.endsWith(".py") && input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) {
+ const sitecustomizeDir = await this.findOtelSitecustomizeDir(directory);
+ if (sitecustomizeDir) {
+ const existing = serverProcess.options.env?.PYTHONPATH;
+ serverProcess.options.env = {
+ ...serverProcess.options.env,
+ PYTHONPATH: existing ? `${sitecustomizeDir}${delimiter}${existing}` : sitecustomizeDir,
+ };
+ } else {
+ yield {
+ type: "status",
+ message:
+ "OTEL auto-instrumentation is not installed in the agent environment; traces will not be collected. Add aws-opentelemetry-distro to the agent's dependencies to enable them.",
+ };
+ }
+ }
  yield* this.streamProcess(serverProcess.command, serverProcess.options);
  }
+
+ /**
+ * Locate the auto-instrumentation sitecustomize.py directory inside the agent's
+ * uv environment. Prepending it to PYTHONPATH instruments every Python process —
+ * an `opentelemetry-instrument` wrapper would only instrument uvicorn's reloader
+ * parent, leaving the re-spawned worker processes untraced.
+ */
+ private async findOtelSitecustomizeDir(directory: string): Promise<string | undefined> {
+ const output: string[] = [];
+ const probe =
+ "import opentelemetry.instrumentation.auto_instrumentation as m; import os; print(os.path.dirname(m.__file__))";
+ try {
+ await this.runProcess(["uv", "run", "python", "-c", probe], {
+ cwd: directory,
+ onOutput: (chunk) => output.push(chunk),
+ });
+ } catch {
+ return undefined;
+ }
+ const sitecustomizeDir = output.join("").trim().split("\n").at(-1)?.trim();
+ if (!sitecustomizeDir || !existsSync(join(sitecustomizeDir, "sitecustomize.py")))
+ return undefined;
+ return sitecustomizeDir;
+ }
 }
 
 function commandForRuntime(

.gitignore

@@ -35,3 +35,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .DS_Store
 
 .agentreview
+src/assets/agent-inspector/

package.json

@@ -56,8 +56,10 @@
  "@aws-sdk/client-bedrock-agentcore-control": "^3.1102.0",
  "@aws-sdk/client-cloudwatch-logs": "^3.1092.0",
  "@aws-sdk/client-iam": "^3.1080.0",
+ "@aws/agent-inspector": "0.6.1",
  "@opentelemetry/api": "^1.9.1",
  "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+ "@opentelemetry/otlp-transformer": "0.213.0",
  "@opentelemetry/resources": "^2.10.0",
  "@opentelemetry/sdk-metrics": "^2.10.0",
  "@smithy/core": "3.29.3",
@@ -75,5 +77,8 @@
  "winston": "^3.19.0",
  "winston-daily-rotate-file": "^5.0.0",
  "zod": "^4.4.3"
+ },
+ "overrides": {
+ "@opentelemetry/core": "^2.10.0"
  }
 }

scripts/build.ts

@@ -21,6 +21,29 @@ function discoverAssets(): string[] {
  return files.sort().map((relativePath) => join(ASSETS_DIR, relativePath));
 }
 
+/**
+ * Stage the prebuilt Agent Inspector SPA into the asset tree (gitignored) so
+ * both distribution paths ship it through the ordinary asset machinery:
+ * `bundle` mirrors it into dist/assets/, `compile` embeds it in the binary.
+ * Every file gains a neutral `.asset` suffix — compile passes assets as
+ * Bun.build entrypoints, and a bare .html entrypoint would be bundled through
+ * Bun's HTML-imports pipeline instead of embedded verbatim. InspectorAssets
+ * strips the suffix when reading.
+ */
+async function stageInspectorAssets(): Promise<void> {
+ const source = join(REPO_ROOT, "node_modules", "@aws", "agent-inspector", "dist-assets");
+ if (!(await Bun.file(join(source, "index.html")).exists())) {
+ throw new Error("@aws/agent-inspector is not installed — run `bun install` before building.");
+ }
+ const target = join(ASSETS_DIR, "agent-inspector");
+ await $`rm -rf ${target}`;
+ await $`mkdir -p ${target}`;
+ const files = [...new Bun.Glob("**/*").scanSync({ cwd: source, onlyFiles: true })];
+ for (const file of files) {
+ await $`cp ${join(source, file)} ${join(target, `${file}.asset`)}`;
+ }
+}
+
 /** Force asset files through the file loader so template .ts/.js are embedded as bytes, not compiled. */
 function assetLoaderPlugin(): Bun.BunPlugin {
  return {
@@ -49,6 +72,7 @@ async function assertAssetsAreText(assets: string[]): Promise<void> {
 // Bun.build rejects with an AggregateError on failure (throw defaults to true),
 // so build errors propagate to runWithExitCode like any other.
 async function bundle(): Promise<void> {
+ await stageInspectorAssets();
  await Bun.build({
  entrypoints: [ENTRYPOINT],
  outdir: DIST,
@@ -64,6 +88,7 @@ async function bundle(): Promise<void> {
 }
 
 async function compile(target: string): Promise<void> {
+ await stageInspectorAssets();
  const assets = discoverAssets();
  await assertAssetsAreText(assets);
 

src/assets/templates/shared/env.local.template

@@ -1,7 +1,11 @@
 # Environment variables for local development.
 # `agentcore project dev` loads this file into your agent's process. Values here
 # override injected values except PORT, FASTMCP_PORT, and LOCAL_DEV, which the
-# CLI owns. This file is gitignored — keep secrets out of version control.
+# CLI owns. While trace collection is on (the default), the CLI also owns the
+# OTEL_* and AGENT_OBSERVABILITY_ENABLED variables so traces reach its local
+# collector — pass --no-traces (or set instrumentation.enableOtel to false in
+# agentcore.json) to disable collection and set your own.
+# This file is gitignored — keep secrets out of version control.
 #
 # Example:
 # MY_API_KEY=...

src/core/dev/codezip.test.ts

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { delimiter, join, relative } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { ProjectRuntime } from "../../projectSchemas/runtime";
 import type { DevEvent, DevServerInput } from "../../handlers/project/dev/types";
-import type { ProcessEvent, ProcessStreamer, StreamProcessOptions } from "../../io";
+import type { ProcessEvent, ProcessRunner, ProcessStreamer, StreamProcessOptions } from "../../io";
 import { CodeZipDevRunner } from "./codezip";
 
 type ProcessCall = {
@@ -54,15 +54,22 @@ async function projectRoot(withNodeModules = false): Promise<string> {
  return root;
 }
 
-function harness(output: ProcessEvent[] = []) {
+function harness(output: ProcessEvent[] = [], probe: { dir?: string; fail?: boolean } = {}) {
  const calls: ProcessCall[] = [];
+ const probeCalls: string[][] = [];
  const fakeStreamProcess: ProcessStreamer = async function* (command, options) {
  calls.push({ command, options });
  yield* output;
  };
+ const fakeRunProcess: ProcessRunner = async (command, options) => {
+ probeCalls.push(command);
+ if (probe.fail) throw new Error("probe failed");
+ options.onOutput?.(`${probe.dir ?? ""}\n`);
+ };
  return {
  calls,
- runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess }),
+ probeCalls,
+ runner: new CodeZipDevRunner({ streamProcess: fakeStreamProcess, runProcess: fakeRunProcess }),
  };
 }
 
@@ -193,3 +200,69 @@ describe("CodeZipDevRunner", () => {
  ]);
  });
 });
+
+describe("CodeZipDevRunner OTEL instrumentation", () => {
+ async function sitecustomizeDir(): Promise<string> {
+ const directory = await mkdtemp(join(tmpdir(), "otel-site-"));
+ tempDirectories.push(directory);
+ await writeFile(join(directory, "sitecustomize.py"), "");
+ return directory;
+ }
+
+ function otelInput(root: string, extraEnv: Record<string, string> = {}): DevServerInput {
+ const base = input(root, runtime());
+ return {
+ ...base,
+ env: { ...base.env, OTEL_EXPORTER_OTLP_ENDPOINT: "http://127.0.0.1:4318", ...extraEnv },
+ };
+ }
+
+ test("prepends the sitecustomize directory to PYTHONPATH when instrumentation is installed", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, probeCalls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls[0]?.slice(0, 4)).toEqual(["uv", "run", "python", "-c"]);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(directory);
+ });
+
+ test("preserves an existing PYTHONPATH", async () => {
+ const root = await projectRoot();
+ const directory = await sitecustomizeDir();
+ const { calls, runner } = harness([], { dir: directory });
+
+ await collect(runner.run(otelInput(root, { PYTHONPATH: "/existing" })));
+
+ expect(calls[0]?.options.env?.PYTHONPATH).toBe(`${directory}${delimiter}/existing`);
+ });
+
+ test("does not probe without an OTEL endpoint or for Node entrypoints", async () => {
+ const root = await projectRoot(true);
+ const { probeCalls, runner } = harness();
+
+ await collect(runner.run(input(root, runtime())));
+ await collect(runner.run({ ...otelInput(root), runtime: runtime({ entrypoint: "index.js" }) }));
+
+ expect(probeCalls).toEqual([]);
+ });
+
+ test.each([
+ ["probe failure", { fail: true }],
+ ["missing sitecustomize.py", { dir: "/nonexistent" }],
+ ] as const)("warns and starts untraced on %s", async (_case, probe) => {
+ const root = await projectRoot();
+ const { calls, probeCalls, runner } = harness([], probe);
+
+ const events = await collect(runner.run(otelInput(root)));
+
+ expect(probeCalls).toHaveLength(1);
+ expect(calls).toHaveLength(1);
+ expect(calls[0]?.options.env?.PYTHONPATH).toBeUndefined();
+ expect(events).toContainEqual({
+ type: "status",
+ message: expect.stringContaining("traces will not be collected"),
+ });
+ });
+});

src/core/dev/codezip.ts

@@ -1,19 +1,28 @@
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
 import { InputValidationError } from "../../errors";
 import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
-import { streamProcess, type ProcessStreamer, type StreamProcessOptions } from "../../io";
+import {
+ runProcess,
+ streamProcess,
+ type ProcessRunner,
+ type ProcessStreamer,
+ type StreamProcessOptions,
+} from "../../io";
 import { isDirectory, isFile, resolvePathWithinProject } from "./path";
 
 type CodeZipDevRunnerConfig = {
  streamProcess?: ProcessStreamer;
+ runProcess?: ProcessRunner;
 };
 
 export class CodeZipDevRunner implements DevRunner {
  private readonly streamProcess: ProcessStreamer;
+ private readonly runProcess: ProcessRunner;
 
  constructor(config: CodeZipDevRunnerConfig = {}) {
  this.streamProcess = config.streamProcess ?? streamProcess;
+ this.runProcess = config.runProcess ?? runProcess;
  }
 
  public async *run(input: DevServerInput): AsyncGenerator<DevEvent, void> {
@@ -41,8 +50,48 @@ export class CodeZipDevRunner implements DevRunner {
 
  yield { type: "status", message: "Starting development server" };
  const serverProcess = commandForRuntime(entrypoint!, directory, input);
+ if (entrypoint!.endsWith(".py") && input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) {
+ const sitecustomizeDir = await this.findOtelSitecustomizeDir(directory);
+ if (sitecustomizeDir) {
+ const existing = serverProcess.options.env?.PYTHONPATH;
+ serverProcess.options.env = {
+ ...serverProcess.options.env,
+ PYTHONPATH: existing ? `${sitecustomizeDir}${delimiter}${existing}` : sitecustomizeDir,
+ };
+ } else {
+ yield {
+ type: "status",
+ message:
+ "OTEL auto-instrumentation is not installed in the agent environment; traces will not be collected. Add aws-opentelemetry-distro to the agent's dependencies to enable them.",
+ };
+ }
+ }
  yield* this.streamProcess(serverProcess.command, serverProcess.options);
  }
+
+ /**
+ * Locate the auto-instrumentation sitecustomize.py directory inside the agent's
+ * uv environment. Prepending it to PYTHONPATH instruments every Python process —
+ * an `opentelemetry-instrument` wrapper would only instrument uvicorn's reloader
+ * parent, leaving the re-spawned worker processes untraced.
+ */
+ private async findOtelSitecustomizeDir(directory: string): Promise<string | undefined> {
+ const output: string[] = [];
+ const probe =
+ "import opentelemetry.instrumentation.auto_instrumentation as m; import os; print(os.path.dirname(m.__file__))";
+ try {
+ await this.runProcess(["uv", "run", "python", "-c", probe], {
+ cwd: directory,
+ onOutput: (chunk) => output.push(chunk),
+ });
+ } catch {
+ return undefined;
+ }
+ const sitecustomizeDir = output.join("").trim().split("\n").at(-1)?.trim();
+ if (!sitecustomizeDir || !existsSync(join(sitecustomizeDir, "sitecustomize.py")))
+ return undefined;
+ return sitecustomizeDir;
+ }
 }
 
 function commandForRuntime(