How to add agent analytics to your app with Claude Code

Use Claude Code to instrument a Node.js report assistant with the Amplitude AI SDK. Record one synthetic task with metadata-only telemetry, flush it before exit, and check the processed session in Amplitude.

  • Claude Code
  • Node.js
  • AI SDK 0.24.2
  • 30 min

Chris Tam · Last updated 9 November 2026

I use Claude Code to instrument the Node.js assistant already in my repository. Amplitude agent analytics shows the assistant's requests, responses and usage together as a task.

In this tutorial, you'll give Claude Code an implementation prompt, inspect the provider wrapper, run a synthetic report summary, and verify the resulting session. I instrument the assistant inside the app, not the coding tool's own conversation.

A Node.js report-summary job with a synthetic user, a unique task ID, automatic provider instrumentation, metadata-only telemetry and a flush after the job closes. The model provider still receives the question and report needed to answer it.

Prerequisites

  • Claude Code installed and signed in, and a local repository with a Node.js runtime. Check the permissions and usage available to your coding-tool account.
  • A development Amplitude project with agent analytics access, its client ingestion API key from Settings > Projects > your project > General, and its US or EU data center.
  • Node.js 22.12 or later, Corepack and pnpm 10.33.2. The reference pins @amplitude/ai 0.24.2, @amplitude/analytics-node 1.5.81 and openai 6.49.0.
  • Your own OpenAI API key and a chat-completions model available to that account. A live model call can incur provider charges. The local tests use controlled replies and require neither key.

Sign up for Amplitude and compare plans for your project's allowances. Use synthetic data and a separate development project.

1. Identify the task and its runtime

I start Claude Code from the repository containing the model call. The isolated reference runs one Node job in the terminal. In an existing app, preserve the authenticated backend, consent, model client and framework.

Terminal
claude --permission-mode plan
Inspection prompt
Inspect this repository's runtime, model client, assistant request path, authentication, consent, analytics and CLAUDE.md, including relevant nested instructions. Identify the genuine start and finish of one assistant task. Propose the files and tests before editing. Keep provider credentials on the Node backend and preserve the package manager and application lifecycle.

The AI SDK instrumentation guide supplies the Node integration. For browser or edge instrumentation, use its documented standard-SDK path rather than importing the Node-only SDK there.

MCP. An optional Amplitude MCP connection can provide the project's existing event taxonomy. Review the account permissions before connecting. This account connection is separate from the app's ingestion API key.

2. Give the agent the implementation prompt

I ask Claude Code to plan the integration first. The command above starts in Plan mode. Review the proposal, then approve implementation through the normal permission flow.

Implementation prompt
Planning only: inspect and read the sources, then show the proposed files and tests. Do not modify files yet; stop and wait for my approval to implement.

Instrument this repository's Node report-summary assistant using @amplitude/ai. Read https://amplitude.com/docs/amplitude-ai/agent-analytics/instrument-ai-sdk and https://amplitude.com/docs/sdks/agent-analytics/sdk, plus the official provider guide at https://github.com/amplitude/Amplitude-AI-Node/blob/main/amplitude-ai.md. Report the sources. Read the full English source of each cited Amplitude page; its Markdown endpoint is https://amplitude.com/docs/api/content/ followed by the path after /docs/. Follow relevant official SDK links and use complete source text rather than a search or fetch summary to resolve signatures. Read the complete reference at https://github.com/amplitude/ampli-examples/tree/ffac5f46bc32da3e3da20474708d974c70cd0eaa/node/replit-agent-analytics and its sibling source files. Use the complete files in this tutorial as the isolated reference; preserve the existing framework and backend when merging.

Use the existing analytics/model client where present. For this standalone reference, initialize @amplitude/analytics-node once with the project ingestion key and correct serverZone, then pass that instance to AmplitudeAI. Use AIConfig with contentMode metadata_only, redactPii true and debug false. Wrap the OpenAI client through @amplitude/ai. The wrapper automatically tracks the input and response: do not also call trackUserMessage or manually emit AI Response for that call. Capture real usage from the provider; do not invent tokens, cost, tools or success.

Create a named replit-report-assistant agent. Generate one unique task ID per report-summary job; keep the same confirmed user ID throughout it. Print that exact task ID after the job finishes so I can find the processed session. Keep the intentional CLI answer output separate from diagnostics; disable provider debug logging and keep private content out of telemetry and diagnostic logs. Use session.run for this single scoped job, and await ai.flush after it closes, including failure. This CLI reference ends a task after one answer; do not use its per-run UUID policy for every request in an ongoing conversation. In a real conversation, retain its task ID across turns and close it only at the actual end.

Read all configuration from the environment. Keep OPENAI_API_KEY in the backend environment or ignored .env.local, never VITE_ variables, CLAUDE.md, committed files, logs or browser bundles. Guard missing keys, model, user and invalid region before initializing or making requests. Use synthetic demo identity only in the isolated example; derive production identity from confirmed authentication. Respect consent before sending telemetry. Keep message text out of Amplitude telemetry and logs. The model provider still needs the prompt. Preserve existing routes, authentication, consent and enabled products.

Run local tests with a controlled provider transport and an in-memory analytics sink; no keys, paid inference or event uploads. Check one user message and response per call, metadata privacy, isolated concurrent tasks, task closure, awaited flush, failure, and the blank configuration guard. Report local results separately from coding-agent generation and processed Amplitude checks. If sources conflict, record both statements and pause that claim until resolved by current SDK evidence or its owner.

3. Review the generated changes

I inspect the backend before running it. The SDK wrapper must sit around the model client the app actually calls, and the task must close after the answer completes.

Implementation prompt
Show every changed and new file and the existing integrations preserved. Trace confirmed user identity, task lifetime, model request, metadata-only configuration and awaited flush. Confirm no duplicate manual User Message or AI Response surrounds the wrapped call. Run the existing checks and report which outcomes remain unverified.

Keep server credentials out of frontend environment variables. For an existing client with custom transport, the SDK supports wrapping that client through its client option. Avoid assuming arbitrary provider options are forwarded by the wrapper.

4. Add the complete reference files

These files make a standalone Node job. In an existing app, merge the instrumentation at the existing server call boundary rather than replacing the app. The Node SDK reference supplies the regional analytics client; the AI SDK reference supplies the wrapper and session scope.

package.json
{
  "name": "amplitude-replit-agent-analytics",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "packageManager": "pnpm@10.33.2+sha512.a90faf6feeab71ad6c6e57f94e0fe1a12f5dcc22cd754db40ae9593eb6a3e0b6b12e3540218bb37ae083404b1f2ce6db2a4121e979829b4aff94b99f49da1cf8",
  "engines": {
    "node": ">=22.12.0",
    "pnpm": ">=10.21.0"
  },
  "scripts": {
    "start": "node --env-file-if-exists=.env.local run.js",
    "check": "node --check run.js && node --check report-agent.js",
    "test": "node --test report-agent.test.js"
  },
  "dependencies": {
    "@amplitude/ai": "0.24.2",
    "@amplitude/analytics-node": "1.5.81",
    "openai": "6.49.0"
  }
}
pnpm-workspace.yaml
minimumReleaseAge: 10080
trustPolicy: no-downgrade
.gitignore
node_modules/
.env.local
.env
.env.example
AMPLITUDE_AI_API_KEY=
AMPLITUDE_SERVER_ZONE=US
OPENAI_API_KEY=
OPENAI_MODEL=
DEMO_USER_ID=build-replit-agent-demo
report-agent.js
export function createReportAgent({ ai, openai }) {
  const agent = ai.agent("replit-report-assistant", { description: "Explains a synthetic usage report" });
  return async function explainReport({ taskId, userId, question, model }) {
    if (!taskId || !userId || !question || !model) throw new Error("Task configuration is missing");
    try {
      return await agent.session({ userId, sessionId: taskId }).run(async () => {
        // The provider wrapper records the user message and AI response. Do not also track them manually.
        const result = await openai.chat.completions.create({
          model,
          messages: [
            { role: "system", content: "Explain this synthetic seven-day report: 12 exports and 8 active accounts. Be brief. Do not claim to access real customer records." },
            { role: "user", content: question },
          ],
        });
        const text = result.choices?.[0]?.message?.content;
        if (typeof text !== "string" || !text.trim()) throw new Error("The assistant returned no text");
        return text;
      });
    } finally {
      const pending = ai.flush();
      await (pending?.promise ?? pending);
    }
  };
}
run.js
import { randomUUID } from "node:crypto";
import * as amplitude from "@amplitude/analytics-node";
import { AmplitudeAI, AIConfig, OpenAI } from "@amplitude/ai";
import { createReportAgent } from "./report-agent.js";

const apiKey = process.env.AMPLITUDE_AI_API_KEY?.trim();
const providerKey = process.env.OPENAI_API_KEY?.trim();
const model = process.env.OPENAI_MODEL?.trim();
const userId = process.env.DEMO_USER_ID?.trim();
const zone = (process.env.AMPLITUDE_SERVER_ZONE || "US").trim();
if (!apiKey || !providerKey || !model || !userId || !["US", "EU"].includes(zone)) {
  console.error("Add the demo configuration and select US or EU. No model request was made.");
  process.exitCode = 1;
} else {
  amplitude.init(apiKey, { serverZone: zone });
  const ai = new AmplitudeAI({ amplitude, config: new AIConfig({ contentMode: "metadata_only", redactPii: true, debug: false }) });
  const openai = new OpenAI({ apiKey: providerKey, amplitude: ai });
  const explainReport = createReportAgent({ ai, openai });
  const taskId = randomUUID();
  try {
    const answer = await explainReport({ taskId, userId, model, question: "Summarize the report and suggest one question to investigate." });
    console.log(answer);
    console.log(`Finished synthetic task ${taskId}. Check the processed session separately.`);
  } catch {
    console.error("The assistant failed. Check provider access and configuration; no reply was confirmed.");
    process.exitCode = 1;
  }
}
report-agent.test.js
import test from "node:test";
import assert from "node:assert/strict";
import { AIConfig, OpenAI } from "@amplitude/ai";
import { MockAmplitudeAI } from "@amplitude/ai/testing";
import OpenAIClient from "openai";
import { createReportAgent } from "./report-agent.js";

function setup({ failure=false, empty=false }={}) {
  const ai=new MockAmplitudeAI(new AIConfig({contentMode:"metadata_only",debug:false}));
  const requests=[];
  const client=new OpenAIClient({apiKey:"synthetic-not-a-real-key",maxRetries:0,fetch:async(url,options)=>{
    requests.push(JSON.parse(options.body));
    if(failure) return new Response(JSON.stringify({error:{message:"synthetic-provider-error",type:"server_error"}}),{status:500,headers:{"content-type":"application/json"}});
    return new Response(JSON.stringify({id:"chatcmpl-local-test",object:"chat.completion",created:1,model:"gpt-4o-mini",choices:[{index:0,message:{role:"assistant",content:empty?"":"synthetic reply private@example.com"},finish_reason:"stop"}],usage:{prompt_tokens:11,completion_tokens:7,total_tokens:18}}),{headers:{"content-type":"application/json"}});
  }});
  const openai=new OpenAI({client,amplitude:ai});
  return {ai,openai,requests,run:createReportAgent({ai,openai})};
}
const args={taskId:"synthetic-report-task-1",userId:"build-replit-agent-demo",question:"synthetic private question private@example.com",model:"gpt-4o-mini"};
test("wrapped provider emits one user message and one response, then closes the task",async()=>{
  const {ai,requests,run}=setup();const reply=await run(args);
  assert.match(reply,/synthetic reply/);assert.equal(requests.length,1);
  assert.equal(ai.getEvents("[Agent] User Message").length,1);
  assert.equal(ai.getEvents("[Agent] AI Response").length,1);
  assert.equal(ai.getEvents("[Agent] Session End").length,1);
  assert.equal(ai.getEvents("[Agent] Tool Call").length,0);
  assert.ok(ai.events.every(e=>e.user_id===args.userId&&e.event_properties["[Agent] Session ID"]===args.taskId));
  const p=ai.getEvents("[Agent] AI Response")[0].event_properties;
  assert.equal(p["[Agent] Input Tokens"],11);assert.equal(p["[Agent] Output Tokens"],7);assert.equal(p["[Agent] Provider"],"openai");
  assert.ok(!JSON.stringify(ai.events).includes("private@example.com"));
  for(const event of ai.events) assert.ok(!("$llm_message" in event.event_properties));
});
test("positive control: a manual user message plus the wrapper duplicates the input",async()=>{
  const {ai,openai}=setup();
  await ai.agent("duplication-positive-control").session({userId:args.userId,sessionId:"synthetic-duplicate-task"}).run(async s=>{
    s.trackUserMessage(args.question);
    await openai.chat.completions.create({model:args.model,messages:[{role:"user",content:args.question}]});
  });
  assert.equal(ai.getEvents("[Agent] User Message").length,2);
});
test("concurrent users and tasks keep identity separate",async()=>{
  const {ai,run}=setup();await Promise.all([run(args),run({...args,taskId:"synthetic-other-task",userId:"synthetic-other-user"})]);
  assert.equal(ai.getEvents("[Agent] User Message").length,2);
  for(const e of ai.events) assert.equal(e.user_id,e.event_properties["[Agent] Session ID"]===args.taskId?args.userId:"synthetic-other-user");
  assert.equal(new Set(ai.events.map(e=>e.event_properties["[Agent] Agent ID"])).size,1);
});
test("flush is awaited before returning and also after failure",async()=>{
  const ok=setup();let flushCompleted=false;ok.ai.flush=async()=>{await Promise.resolve();flushCompleted=true};
  await ok.run(args);assert.equal(flushCompleted,true);
  const bad=setup({failure:true});let flushed=false;bad.ai.flush=async()=>{flushed=true};
  await assert.rejects(bad.run(args));assert.equal(flushed,true);assert.equal(bad.ai.getEvents("[Agent] Session End").length,1);
});
test("empty reply is not reported as successful application output",async()=>{
  const {run}=setup({empty:true});await assert.rejects(run(args),/no text/);
});
test("configuration guard prevents provider requests",async()=>{
  const {run,requests}=setup();await assert.rejects(run({...args,userId:""}),/configuration/);assert.equal(requests.length,0);
});

Install dependencies and create ignored local configuration in the reference directory. Commit the generated pnpm-lock.yaml and use frozen installs for repeated checks.

Terminal
corepack enable
corepack prepare pnpm@10.33.2 --activate
pnpm install
cp .env.example .env.local
pnpm check
pnpm test

The included tests control the provider transport and use the SDK's in-memory testing client. They exercise the real wrapper without contacting OpenAI or Amplitude.

5. Configure and run one task

Fill the ignored .env.local with the development Amplitude ingestion key and your provider key. Set OPENAI_MODEL to a chat-completions model your account can use and AMPLITUDE_SERVER_ZONE to US or EU. DEMO_USER_ID is synthetic. The shared example retains its replit-report-assistant agent label and build-replit-agent-demo user ID; these are sample identifiers, not a connection to Replit. In your app, use the established agent name and confirmed application identity.

Keep credentials out of project instructions and source control. Restart the process after changing configuration, then run:

Terminal
pnpm start

Without all required values, the process stops before any model request. With configured credentials, it asks for one synthetic report summary and prints the answer plus task ID. This Node job prints to the terminal; it does not expose a browser UI. A production web assistant needs its own authenticated route and server lifecycle.

Why. Session.run closes this single job when its scope exits. Awaiting flush afterward gives the analytics client a chance to finish sending buffered events before this short-lived process exits. A completed application answer still needs a separate service-side data check.

Verify it worked

  1. Run pnpm check and pnpm test with no real keys. Confirm the controlled wrapper produces one User Message, one AI Response and a Session End for the task, with message content omitted and actual fixture usage preserved.
  2. Run pnpm start with blank configuration. Confirm it makes no model request. Then configure only the intended development keys and run one synthetic task, checking provider usage and charges separately.
  3. In Amplitude, find build-replit-agent-demo and the printed task ID. Inspect [Agent] User Message, [Agent] AI Response and [Agent] Session End. Check the same user, agent and session identifiers and provider/model/usage metadata. Unknown usage or cost should remain absent rather than fabricated.
  4. Confirm prompt and response text are absent from Amplitude event properties under metadata_only. The answer printed in the terminal is application output; do not copy private answers into telemetry or debug logs.
  5. After processing, inspect the agent session. Confirm this job forms one session, closes once and contains its expected exchange. Repeat with another task ID to check separation. Event upload or local tests alone do not prove that processed grouping succeeded.

Troubleshooting

The configuration guard stops the job. Check each required environment value and use US or EU exactly. Restart the process after editing the local environment. A blank model name intentionally prevents inference.

The model request fails. Confirm provider access, key and model availability. The example reports a generic failure without printing credentials or the private prompt. Check the provider dashboard before retrying a billable request.

Each input appears twice. Keep the provider wrapper's automatic instrumentation and remove an extra manual User Message for that same input. Manual instrumentation belongs to a call that is not already captured.

The answer appears but the session is missing. Confirm the Amplitude project, region, identity, task ID, ingestion result and processing time. Keep the flush after close. For a long-running app, also handle shutdown according to the SDK lifecycle guidance.

Every turn becomes a separate session. This example deliberately runs one completed report job. A multi-turn conversation must reuse its session ID across requests and close only when the conversation actually ends.

Quality signals are absent. Metadata-only capture omits message content; content-dependent analysis needs an approved content-capture policy. Keep the privacy choice explicit rather than enabling content collection solely to populate a chart.

FAQ

Does this track Claude Code's coding conversation?

This instruments the report assistant inside your application. Claude Code creates the code; your app's model requests are what the SDK observes.

Can I put the model key in a VITE_ variable?

Keep it in the backend environment or ignored .env.local. VITE_ values are exposed in the browser bundle. The Node reference needs no public model credential.

Does metadata-only prevent the provider from seeing my question?

Metadata-only controls Amplitude telemetry. The model provider still receives the prompt and synthetic report so it can produce an answer.

Do the local tests prove that Amplitude processed the session?

They verify the SDK wrapper, event contract and lifecycle with controlled replies. Run the development-project verification steps to establish ingestion and processed grouping.

Full code reference

The complete implementation is the package manifest, workspace safeguards, configuration, Node entry point, report-agent module and tests in step 4. Keep the generated lockfile with these files. Download the exact report-agent example and lockfile. The official Amplitude AI Node repository supplies the SDK source and further examples.

Save the project instructions

Merge these rules into CLAUDE.md; preserve existing and nested instructions and keep credentials out. These instructions guide future edits; tests establish the actual runtime behavior.

CLAUDE.md
Keep agent instrumentation on the existing Node model-call boundary.
Preserve confirmed identity, consent, authentication, routes and enabled products.
Use a stable task ID across the task; close it only when the task ends.
The provider wrapper auto-tracks its user message and AI response; avoid duplicate manual events.
Use metadata_only and redactPii for this synthetic reference.
Keep provider keys in the backend environment or ignored .env.local, never VITE_ variables or source files.
Await flush after closure, including errors, and test the actual host lifecycle.
Separate local wrapper tests from provider calls, ingestion and processed session checks.
Record conflicting sources and resolve affected claims before continuing.

What this unlocks

Agent analytics connects model usage and task completion to the same identity used in product analytics. A report export can then be compared with the assistant task that preceded it, using the application's confirmed identity.

Next steps

Amplitude is the leading all-in-one analytics platform for building better products. Product and engineering teams use Amplitude to connect product analytics and web analytics with session replay, heatmaps, experimentation, feature flags, and guides and surveys in one unified workflow, with AI agents working across all of it. Learn how Amplitude is building self-improving products with Wave, helping teams turn product data into PRs.

Build the report, then check the result

Connect a development project and verify the report action before you roll out the integration.