# amplitude/amplitude-ai-node architecture

> Architecture diagram of the GitHub repository amplitude/amplitude-ai-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amplitude/amplitude-ai-node
- Repository: https://github.com/amplitude/amplitude-ai-node

## Overview

#### 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`

Main entry points: [`src/core/tracking.ts`](https://github.com/amplitude/amplitude-ai-node/blob/main/src/core/tracking.ts) (Tracking core), [`src/session.ts`](https://github.com/amplitude/amplitude-ai-node/blob/main/src/session.ts) (Session runner), [`src/providers/base.ts`](https://github.com/amplitude/amplitude-ai-node/blob/main/src/providers/base.ts) (Provider adapter base), [`bin/amplitude-ai.mjs`](https://github.com/amplitude/amplitude-ai-node/blob/main/bin/amplitude-ai.mjs) (CLI executables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["SDK Runtime"]
  node_public_api["Package API<br/>TypeScript entrypoint<br/>[index.ts]"]
  node_client["AmplitudeAI client<br/>SDK client<br/>[client.ts]"]
  node_bound_agent["Bound agent<br/>agent abstraction<br/>[bound-agent.ts]"]
  node_session["Session runner<br/>execution context<br/>[session.ts]"]
  node_context["Session context<br/>async context state<br/>[context.ts]"]
  node_propagation["Context propagation<br/>async propagation<br/>[propagation.ts]"]
  node_tracking["Tracking core<br/>event pipeline<br/>[tracking.ts]"]
  node_privacy["Privacy policy<br/>content policy<br/>[privacy.ts]"]
  node_enrichments["Event enrichments<br/>enrichment pipeline<br/>[enrichments.ts]"]
  node_config["SDK configuration<br/>[config.ts]"]
  node_amplitude_node{{"Amplitude Node Analytics<br/>delivery peer dependency"}}
end

subgraph group_instrumentation["Instrumentation"]
  node_provider_base["Provider adapter base<br/>instrumentation base<br/>[base.ts]"]
  node_openai_adapter["OpenAI adapter<br/>provider adapter<br/>[openai.ts]"]
  node_anthropic_adapter["Anthropic adapter<br/>provider adapter<br/>[anthropic.ts]"]
  node_wrappers["Client wrappers<br/>instrumentation API<br/>[wrappers.ts]"]
  node_patching["Prototype patching<br/>zero-code instrumentation<br/>[patching.ts]"]
end

subgraph group_integrations["Integrations"]
  node_otel_processor["OpenTelemetry bridge<br/>span processor<br/>[processor.ts]"]
  node_otel_mapper["OTel semantic mapper<br/>attribute mapper<br/>[mapper.ts]"]
  node_langchain["LangChain adapter<br/>framework adapter<br/>[langchain.ts]"]
  node_middleware["Request middleware<br/>Express middleware<br/>[middleware.ts]"]
end

subgraph group_operations["Operations"]
  node_register["Preload registration<br/>process-start hook<br/>[register.ts]"]
  node_cli["CLI executables<br/>Node CLI<br/>[amplitude-ai.mjs]"]
  node_mcp_server["MCP server<br/>[server.ts]"]
end

node_public_api -->|"creates"| node_client
node_client -->|"binds"| node_bound_agent
node_bound_agent -->|"runs in"| node_session
node_session -->|"establishes"| node_context
node_context -->|"propagates via"| node_propagation
node_session -->|"emits events"| node_tracking
node_tracking -->|"applies content policy"| node_privacy
node_tracking -->|"enriches"| node_enrichments
node_config -.->|"configures"| node_tracking
node_privacy -->|"approved events"| node_amplitude_node
node_provider_base -->|"tracks provider activity"| node_tracking
node_openai_adapter -->|"implements"| node_provider_base
node_anthropic_adapter -->|"implements"| node_provider_base
node_wrappers -->|"uses"| node_provider_base
node_patching -->|"routes calls to"| node_provider_base
node_otel_processor -->|"maps spans with"| node_otel_mapper
node_otel_mapper -->|"exports events to"| node_tracking
node_langchain -->|"creates context for"| node_session
node_middleware -->|"establishes request scope"| node_session
node_register -->|"activates"| node_patching
node_cli -->|"preloads"| node_register
node_cli -->|"starts"| node_mcp_server

click node_public_api "https://github.com/amplitude/amplitude-ai-node/blob/main/src/index.ts"
click node_client "https://github.com/amplitude/amplitude-ai-node/blob/main/src/client.ts"
click node_bound_agent "https://github.com/amplitude/amplitude-ai-node/blob/main/src/bound-agent.ts"
click node_session "https://github.com/amplitude/amplitude-ai-node/blob/main/src/session.ts"
click node_context "https://github.com/amplitude/amplitude-ai-node/blob/main/src/context.ts"
click node_propagation "https://github.com/amplitude/amplitude-ai-node/blob/main/src/propagation.ts"
click node_tracking "https://github.com/amplitude/amplitude-ai-node/blob/main/src/core/tracking.ts"
click node_privacy "https://github.com/amplitude/amplitude-ai-node/blob/main/src/core/privacy.ts"
click node_enrichments "https://github.com/amplitude/amplitude-ai-node/blob/main/src/core/enrichments.ts"
click node_config "https://github.com/amplitude/amplitude-ai-node/blob/main/src/config.ts"
click node_provider_base "https://github.com/amplitude/amplitude-ai-node/blob/main/src/providers/base.ts"
click node_openai_adapter "https://github.com/amplitude/amplitude-ai-node/blob/main/src/providers/openai.ts"
click node_anthropic_adapter "https://github.com/amplitude/amplitude-ai-node/blob/main/src/providers/anthropic.ts"
click node_wrappers "https://github.com/amplitude/amplitude-ai-node/blob/main/src/wrappers.ts"
click node_patching "https://github.com/amplitude/amplitude-ai-node/blob/main/src/patching.ts"
click node_otel_processor "https://github.com/amplitude/amplitude-ai-node/blob/main/src/otel/processor.ts"
click node_otel_mapper "https://github.com/amplitude/amplitude-ai-node/blob/main/src/otel/mapper.ts"
click node_langchain "https://github.com/amplitude/amplitude-ai-node/blob/main/src/integrations/langchain.ts"
click node_middleware "https://github.com/amplitude/amplitude-ai-node/blob/main/src/middleware.ts"
click node_register "https://github.com/amplitude/amplitude-ai-node/blob/main/src/register.ts"
click node_cli "https://github.com/amplitude/amplitude-ai-node/blob/main/bin/amplitude-ai.mjs"
click node_mcp_server "https://github.com/amplitude/amplitude-ai-node/blob/main/src/mcp/server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_client,node_bound_agent,node_session,node_context,node_propagation,node_tracking,node_privacy,node_enrichments,node_config,node_amplitude_node toneBlue
class node_provider_base,node_openai_adapter,node_anthropic_adapter,node_wrappers,node_patching toneAmber
class node_otel_processor,node_otel_mapper,node_langchain,node_middleware toneMint
class node_register,node_cli,node_mcp_server toneRose
```

## Components

### SDK Runtime

- [Package API](https://github.com/amplitude/amplitude-ai-node/blob/main/src/index.ts): TypeScript entrypoint · Central public SDK exports. · `src/index.ts`
- [AmplitudeAI client](https://github.com/amplitude/amplitude-ai-node/blob/main/src/client.ts): SDK client · `src/client.ts`
- [Bound agent](https://github.com/amplitude/amplitude-ai-node/blob/main/src/bound-agent.ts): agent abstraction · `src/bound-agent.ts`
- [Session runner](https://github.com/amplitude/amplitude-ai-node/blob/main/src/session.ts): execution context · Runs work and emits terminal lifecycle events. · `src/session.ts`
- [Session context](https://github.com/amplitude/amplitude-ai-node/blob/main/src/context.ts): async context state · Carries identity, trace, turn, hierarchy, tenant, and privacy metadata. · `src/context.ts`
- [Context propagation](https://github.com/amplitude/amplitude-ai-node/blob/main/src/propagation.ts): async propagation · `src/propagation.ts`
- [Tracking core](https://github.com/amplitude/amplitude-ai-node/blob/main/src/core/tracking.ts): event pipeline · Builds canonical [Agent] events and keeps ordinary tracking non-throwing. · `src/core/tracking.ts`
- [Privacy policy](https://github.com/amplitude/amplitude-ai-node/blob/main/src/core/privacy.ts): content policy · Applies full-content redaction, metadata-only, or customer enrichment modes. · `src/core/privacy.ts`
- [Event enrichments](https://github.com/amplitude/amplitude-ai-node/blob/main/src/core/enrichments.ts): enrichment pipeline · Calculates enrichment and cost-related properties. · `src/core/enrichments.ts`
- [SDK configuration](https://github.com/amplitude/amplitude-ai-node/blob/main/src/config.ts): configuration · `src/config.ts`
- **Amplitude Node Analytics**: delivery peer dependency · Underlying event delivery client.

### Instrumentation

- [Provider adapter base](https://github.com/amplitude/amplitude-ai-node/blob/main/src/providers/base.ts): instrumentation base · Shared provider tracking callbacks. · `src/providers/base.ts`
- [OpenAI adapter](https://github.com/amplitude/amplitude-ai-node/blob/main/src/providers/openai.ts): provider adapter · Also represents native adapters for Anthropic, Azure, Gemini, Mistral, and Bedrock. · `src/providers/openai.ts`
- [Anthropic adapter](https://github.com/amplitude/amplitude-ai-node/blob/main/src/providers/anthropic.ts): provider adapter · `src/providers/anthropic.ts`
- [Client wrappers](https://github.com/amplitude/amplitude-ai-node/blob/main/src/wrappers.ts): instrumentation API · wrap() instruments existing provider clients. · `src/wrappers.ts`
- [Prototype patching](https://github.com/amplitude/amplitude-ai-node/blob/main/src/patching.ts): zero-code instrumentation · Patches legacy or existing provider call sites. · `src/patching.ts`

### Integrations

- [OpenTelemetry bridge](https://github.com/amplitude/amplitude-ai-node/blob/main/src/otel/processor.ts): span processor · Filters GenAI spans and exports mapped events. · `src/otel/processor.ts`
- [OTel semantic mapper](https://github.com/amplitude/amplitude-ai-node/blob/main/src/otel/mapper.ts): attribute mapper · `src/otel/mapper.ts`
- [LangChain adapter](https://github.com/amplitude/amplitude-ai-node/blob/main/src/integrations/langchain.ts): framework adapter · Translates framework callbacks into sessions and events. · `src/integrations/langchain.ts`
- [Request middleware](https://github.com/amplitude/amplitude-ai-node/blob/main/src/middleware.ts): Express middleware · Establishes request identity and session context. · `src/middleware.ts`

### Operations

- [Preload registration](https://github.com/amplitude/amplitude-ai-node/blob/main/src/register.ts): process-start hook · Enables provider patching during process startup. · `src/register.ts`
- [CLI executables](https://github.com/amplitude/amplitude-ai-node/blob/main/bin/amplitude-ai.mjs): Node CLI · Onboarding, instrumentation preload, diagnostics, status, catalog, and MCP entry points. · `bin/amplitude-ai.mjs`
- [MCP server](https://github.com/amplitude/amplitude-ai-node/blob/main/src/mcp/server.ts): stdio MCP server · `src/mcp/server.ts`

## Connections

- Package API → AmplitudeAI client: creates
- AmplitudeAI client → Bound agent: binds
- Bound agent → Session runner: runs in
- Session runner → Session context: establishes
- Session context → Context propagation: propagates via
- Session runner → Tracking core: emits events
- Tracking core → Privacy policy: applies content policy
- Tracking core → Event enrichments: enriches
- SDK configuration → Tracking core: configures
- Privacy policy → Amplitude Node Analytics: approved events
- Provider adapter base → Tracking core: tracks provider activity
- OpenAI adapter → Provider adapter base: implements
- Anthropic adapter → Provider adapter base: implements
- Client wrappers → Provider adapter base: uses
- Prototype patching → Provider adapter base: routes calls to
- OpenTelemetry bridge → OTel semantic mapper: maps spans with
- OTel semantic mapper → Tracking core: exports events to
- LangChain adapter → Session runner: creates context for
- Request middleware → Session runner: establishes request scope
- Preload registration → Prototype patching: activates
- CLI executables → Preload registration: preloads
- CLI executables → MCP server: starts