How to add agent analytics to a Claude agent with tool use

pnpm add @amplitude/ai @amplitude/analytics-node @anthropic-ai/sdk
pnpm add -D tsx typescript @types/node

# .env
AMPLITUDE_AI_API_KEY=your-amplitude-project-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key

// src/lib/amplitude.ts
import Anthropic from '@anthropic-ai/sdk';
import { AIConfig, AmplitudeAI } from '@amplitude/ai';

const apiKey = process.env.AMPLITUDE_AI_API_KEY;

if (!apiKey) {
  throw new Error('AMPLITUDE_AI_API_KEY is not set');
}

export const ai = new AmplitudeAI({
  apiKey,
  config: new AIConfig({
    contentMode: 'full', // prompt and response text, with PII redaction
    redactPii: true,
    debug: process.env.NODE_ENV !== 'production',
  }),
});

export const supportAgent = ai.agent('support-agent', {
  description: 'Answers order and help-center questions with tools',
});

// Wait for a promise-returning client or the analytics return object's promise.
export async function flushAgentEvents(): Promise<void> {
  const pending = ai.flush();
  if (pending && typeof pending === 'object' && 'promise' in pending) {
    await pending.promise;
  } else {
    await pending;
  }
}

export const MODEL = 'claude-sonnet-5-5';

// The plain Anthropic client, not the wrapper from @amplitude/ai.
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

type LoopRequest = Omit<Anthropic.MessageCreateParamsNonStreaming, 'max_tokens'> & {
  max_tokens?: number;
};

// AmplitudeToolLoop calls client.messages.create for you. This client adds
// max_tokens, which the Messages API requires on every request.
export const claude = {
  messages: {
    create: (params: LoopRequest) =>
      anthropic.messages.create({ ...params, max_tokens: params.max_tokens ?? 4096 }),
  },
};

// src/tools.ts
import type Anthropic from '@anthropic-ai/sdk';

export const tools = [
  {
    name: 'get_order_status',
    description:
      'Looks up the shipping status of one order by its order number. Use it when the user asks where an order is, when it ships, or whether it arrived. Returns the status, carrier, and estimated delivery date. It does not return payment or refund details.',
    input_schema: {
      type: 'object',
      properties: {
        order_id: { type: 'string', description: 'The order number, for example 1042.' },
      },
      required: ['order_id'],
    },
  },
  {
    name: 'search_help_docs',
    description:
      'Searches the help center for articles about returns, refunds, shipping, and account settings. Use it for policy questions the order record cannot answer. Returns up to three matching articles with a title and body.',
    input_schema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'A short search phrase, for example "return window".' },
      },
      required: ['query'],
    },
  },
] satisfies Anthropic.Tool[];

async function getOrderStatus(orderId: string) {
  // Replace with a call to your order service.
  return { order_id: orderId, status: 'shipped', carrier: 'UPS', estimated_delivery: '2026-10-18' };
}

async function searchHelpDocs(query: string) {
  // Replace with your search: a vector store, a database, or an internal API.
  return [{ title: 'Return an item', body: 'Start a return from Orders within 30 days of delivery.' }];
}

// AmplitudeToolLoop calls this once for each tool_use block in Claude's response.
export async function executeTool(name: string, input: Record<string, unknown>): Promise<string> {
  switch (name) {
    case 'get_order_status':
      return JSON.stringify(await getOrderStatus(String(input.order_id)));
    case 'search_help_docs':
      return JSON.stringify(await searchHelpDocs(String(input.query)));
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
}

// src/agent.ts
import type Anthropic from '@anthropic-ai/sdk';
import { AmplitudeToolLoop } from '@amplitude/ai';
import { ai, claude, MODEL, supportAgent } from './lib/amplitude.js';
import { executeTool, tools } from './tools.js';

const SYSTEM_PROMPT =
  'You are the support agent for an online store. Use the tools to look up orders and help articles. Answer in two or three sentences.';

export interface SupportTask {
  taskId: string; // a ticket, thread, or run ID your app already has
  prompt: string;
  userId?: string; // the same user ID your product events carry; omit when signed out
  deviceId?: string;
}

export async function runSupportAgent({ taskId, prompt, userId, deviceId }: SupportTask) {
  return supportAgent
    .session({ userId, deviceId, sessionId: taskId })
    .run(async () => {
      const loop = new AmplitudeToolLoop({ amplitudeAI: ai, userId, sessionId: taskId });

      const responses = await loop.run({
        client: claude,
        model: MODEL,
        system: SYSTEM_PROMPT,
        messages: [{ role: 'user', content: prompt }],
        tools,
        toolExecutor: executeTool,
      });

      // run() resolves with every raw Claude response; the last one holds the answer.
      const last = responses[responses.length - 1] as unknown as Anthropic.Message | undefined;
      if (!last || last.stop_reason === 'tool_use') {
        throw new Error(`Agent stopped before answering task ${taskId}`);
      }

      return last.content
        .filter((block): block is Anthropic.TextBlock => block.type === 'text')
        .map((block) => block.text)
        .join('');
    });
}

// src/lib/claude-usage.ts
import type Anthropic from '@anthropic-ai/sdk';

// Only needed for Claude calls you track yourself with s.trackAiMessage().
export function claudeTokenCounts(usage: Anthropic.Usage) {
  const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
  const cacheCreationTokens = usage.cache_creation_input_tokens ?? 0;
  return {
    inputTokens: usage.input_tokens + cacheReadTokens + cacheCreationTokens,
    outputTokens: usage.output_tokens,
    cacheReadTokens,
    cacheCreationTokens,
  };
}

// src/index.ts
import { randomUUID } from 'node:crypto';
import { ai, flushAgentEvents } from './lib/amplitude.js';
import { runSupportAgent } from './agent.js';

const prompt = process.argv[2] ?? 'Where is order 1042, and can I still return it?';

try {
  const answer = await runSupportAgent({
    taskId: randomUUID(),
    prompt,
    userId: 'user-42', // use your signed-in user's ID
  });
  console.log(answer);
} finally {
  await flushAgentEvents();
}

pnpm exec tsx --env-file=.env src/index.ts "Where is order 1042, and can I still return it?"

// -- .env --
// AMPLITUDE_AI_API_KEY=your-amplitude-project-api-key
// ANTHROPIC_API_KEY=your-anthropic-api-key

// -- src/lib/amplitude.ts --
import Anthropic from '@anthropic-ai/sdk';
import { AIConfig, AmplitudeAI } from '@amplitude/ai';

const apiKey = process.env.AMPLITUDE_AI_API_KEY;

if (!apiKey) {
  throw new Error('AMPLITUDE_AI_API_KEY is not set');
}

export const ai = new AmplitudeAI({
  apiKey,
  config: new AIConfig({
    contentMode: 'full',
    redactPii: true,
    debug: process.env.NODE_ENV !== 'production',
  }),
});

export const supportAgent = ai.agent('support-agent', {
  description: 'Answers order and help-center questions with tools',
});

// Wait for a promise-returning client or the analytics return object's promise.
export async function flushAgentEvents(): Promise<void> {
  const pending = ai.flush();
  if (pending && typeof pending === 'object' && 'promise' in pending) {
    await pending.promise;
  } else {
    await pending;
  }
}

export const MODEL = 'claude-sonnet-5-5';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

type LoopRequest = Omit<Anthropic.MessageCreateParamsNonStreaming, 'max_tokens'> & {
  max_tokens?: number;
};

export const claude = {
  messages: {
    create: (params: LoopRequest) =>
      anthropic.messages.create({ ...params, max_tokens: params.max_tokens ?? 4096 }),
  },
};

// -- src/tools.ts --
import type Anthropic from '@anthropic-ai/sdk';

export const tools = [
  {
    name: 'get_order_status',
    description:
      'Looks up the shipping status of one order by its order number. Use it when the user asks where an order is, when it ships, or whether it arrived. Returns the status, carrier, and estimated delivery date. It does not return payment or refund details.',
    input_schema: {
      type: 'object',
      properties: {
        order_id: { type: 'string', description: 'The order number, for example 1042.' },
      },
      required: ['order_id'],
    },
  },
  {
    name: 'search_help_docs',
    description:
      'Searches the help center for articles about returns, refunds, shipping, and account settings. Use it for policy questions the order record cannot answer. Returns up to three matching articles with a title and body.',
    input_schema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'A short search phrase, for example "return window".' },
      },
      required: ['query'],
    },
  },
] satisfies Anthropic.Tool[];

async function getOrderStatus(orderId: string) {
  return { order_id: orderId, status: 'shipped', carrier: 'UPS', estimated_delivery: '2026-10-18' };
}

async function searchHelpDocs(query: string) {
  return [{ title: 'Return an item', body: 'Start a return from Orders within 30 days of delivery.' }];
}

export async function executeTool(name: string, input: Record<string, unknown>): Promise<string> {
  switch (name) {
    case 'get_order_status':
      return JSON.stringify(await getOrderStatus(String(input.order_id)));
    case 'search_help_docs':
      return JSON.stringify(await searchHelpDocs(String(input.query)));
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
}

// -- src/agent.ts --
import type Anthropic from '@anthropic-ai/sdk';
import { AmplitudeToolLoop } from '@amplitude/ai';
import { ai, claude, MODEL, supportAgent } from './lib/amplitude.js';
import { executeTool, tools } from './tools.js';

const SYSTEM_PROMPT =
  'You are the support agent for an online store. Use the tools to look up orders and help articles. Answer in two or three sentences.';

export interface SupportTask {
  taskId: string;
  prompt: string;
  userId?: string;
  deviceId?: string;
}

export async function runSupportAgent({ taskId, prompt, userId, deviceId }: SupportTask) {
  return supportAgent
    .session({ userId, deviceId, sessionId: taskId })
    .run(async () => {
      const loop = new AmplitudeToolLoop({ amplitudeAI: ai, userId, sessionId: taskId });

      const responses = await loop.run({
        client: claude,
        model: MODEL,
        system: SYSTEM_PROMPT,
        messages: [{ role: 'user', content: prompt }],
        tools,
        toolExecutor: executeTool,
      });

      const last = responses[responses.length - 1] as unknown as Anthropic.Message | undefined;
      if (!last || last.stop_reason === 'tool_use') {
        throw new Error(`Agent stopped before answering task ${taskId}`);
      }

      return last.content
        .filter((block): block is Anthropic.TextBlock => block.type === 'text')
        .map((block) => block.text)
        .join('');
    });
}

// -- src/lib/claude-usage.ts (optional) --
import type Anthropic from '@anthropic-ai/sdk';

export function claudeTokenCounts(usage: Anthropic.Usage) {
  const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
  const cacheCreationTokens = usage.cache_creation_input_tokens ?? 0;
  return {
    inputTokens: usage.input_tokens + cacheReadTokens + cacheCreationTokens,
    outputTokens: usage.output_tokens,
    cacheReadTokens,
    cacheCreationTokens,
  };
}

// -- src/index.ts --
import { randomUUID } from 'node:crypto';
import { ai, flushAgentEvents } from './lib/amplitude.js';
import { runSupportAgent } from './agent.js';

const prompt = process.argv[2] ?? 'Where is order 1042, and can I still return it?';

try {
  const answer = await runSupportAgent({
    taskId: randomUUID(),
    prompt,
    userId: 'user-42',
  });
  console.log(answer);
} finally {
  await flushAgentEvents();
}

Add Amplitude agent analytics to this Claude tool-use agent by following
https://amplitude.com/build/anthropic-agent-analytics exactly. Install
@amplitude/ai, @amplitude/analytics-node, and @anthropic-ai/sdk. Create
src/lib/amplitude.ts that constructs AmplitudeAI from
process.env.AMPLITUDE_AI_API_KEY, the agent with ai.agent(), and a plain
Anthropic client from @anthropic-ai/sdk, all at module scope; never call
ai.agent() per request. Give AmplitudeToolLoop a client adapter whose
messages.create sets max_tokens, and never the Anthropic wrapper from
@amplitude/ai. Open agent.session({ userId, deviceId, sessionId }) with
the task's existing ID as sessionId and run loop.run() inside run().
Pass only the current task's messages, don't call trackUserMessage
yourself, and make the tool executor return strings and throw on
failure. Use the canonical model ID. Await flushAgentEvents() before a script
exits; in a server drain active requests, await flushAgentEvents(), then exit. Never pass a placeholder
userId. Don't hardcode keys. Report every file you changed.