amplitude/amplitude-ai-node

Purpose and Public Surface

@amplitude/ai is a Node.js/TypeScript SDK that turns AI-agent activity into Amplitude analytics events: user/AI messages, tool calls, spans, scores, embeddings, session lifecycle, and enrichments. Its package API is centralized in src/index.ts; primary client and agent abstractions are src/client.ts, src/bound-agent.ts, and src/session.ts.

Primary Execution Model

Applications create AmplitudeAI, bind an agent, then execute work within session.run(). Session context carries user, session, trace, turn, agent hierarchy, tenant, and privacy metadata via async context propagation. Events emitted manually or by wrappers inherit this active context; session completion emits the terminal event and may flush in serverless environments.

• src/client.ts

• src/session.ts

• src/context.ts

• src/propagation.ts

Event Construction, Privacy, and Delivery

The tracking core constructs the canonical [Agent] event schema, applies validation and content/privacy policy, calculates enrichments/cost-related properties, then sends through the underlying Amplitude Node Analytics client. Content modes form a key boundary: full content with redaction, metadata-only, or customer-provided enrichment. Tracking is intended to be non-throwing outside optional strict validation.

• src/core/tracking.ts

• src/core/privacy.ts

• src/core/enrichments.ts

• src/config.ts

LLM Provider Instrumentation

Native provider adapters wrap or reconstruct OpenAI, Anthropic, Azure OpenAI, Gemini/Google GenAI, Mistral, and AWS Bedrock clients. They extract request/response content, usage, tool calls, streaming lifecycle/TTFB, errors, and provider-specific cache/reasoning metadata, then invoke shared tracking callbacks. wrap() and zero-code prototype patching offer alternatives for existing clients and legacy call sites.

• src/providers/base.ts

• src/providers/openai.ts

• src/providers/anthropic.ts

• src/wrappers.ts

• src/patching.ts

Integrations and Observability Boundaries

Framework adapters translate external callback or trace formats into the same session/event model. The OpenTelemetry bridge filters GenAI spans, maps semantic attributes, and exports Amplitude events; other adapters target LangChain, LlamaIndex, OpenAI Agents, Claude Agent SDK, and Anthropic tool/managed-agent workflows. Express-compatible middleware establishes request-scoped identity and session context.

• src/otel/processor.ts

• src/otel/mapper.ts

• src/integrations/langchain.ts

• src/middleware.ts

Operational Entry Points and Infrastructure

The distributable runtime is Node.js, with @amplitude/analytics-node as the delivery peer dependency and optional provider SDKs loaded as needed. CLI executables support onboarding, auto-instrumentation preload, diagnostics, status, catalog generation, and an stdio MCP server. The preload registration path enables process-start provider patching; live pricing may fetch updated model pricing externally.

• bin/amplitude-ai.mjs

• bin/amplitude-ai-instrument.mjs

• bin/amplitude-ai-mcp.mjs

• src/register.ts

• src/mcp/server.ts