Node AI SDK release notes

npmv0.24.2149.6 kB gzip

Release notes for @amplitude/ai. For the full engineering changelog, go to the Amplitude-AI-Node CHANGELOG on GitHub. For the Python SDK, refer to Python AI SDK release notes.

0.25.0

Released November 2, 2026.

Features

Add the experiments option on ai.agent(), agent.child(), agent.session(), and single agent or session track* calls. It records A/B test or feature flag assignment as [{ key, variant, provider?, unit? }], and every event carries [Agent] Experiments (key:variant strings) plus [Agent] Experiment Key, Variant, Unit, and Provider when exactly one experiment applies, so any chart splits by arm. Call entries override session entries, which override agent entries, by key; child agents and runAs() inherit them; provider wrappers, tool(), and OTel-mapped spans inside a session carry them. unit is agent_session (default), turn, or span; at most 10 apply to an event; invalid entries are dropped with a debug log. context: { experiment_variant } keeps working.
Add helpers for the flag tool you already use: experimentsFromAmplitude(variants, { keys }) maps an Amplitude Experiment fetchV2() or evaluateV2() result; AmplitudeAIHook from @amplitude/ai/openfeature records flags an OpenFeature provider evaluates inside a session, with flags, unit, and variantOf options; session.addExperiments() records an assignment learned after the session started, shared across runAs() delegation. None of them sends an exposure event. experimentFromEvaluation() is the mapping behind the hook.
Warehouse templates read optional experiment_key and experiment_variant columns, one experiment per row with unit agent_session.
The forwarder core sends NormalizedConversation.experiments with the same rules as the SDK.
MCP server: scan_project reports experiment_packages and flag_call_sites; instrument_file adds a TODO where a file reads a flag; validate_file flags the legacy experiment_variant context form and helpers called without keys or flags; generate_verify_test checks that session experiments reach every event; MockAmplitudeAI.summary() reports an Experiments fill line. AGENTS.md and amplitude-ai.md route flag reads to experiments.

Refer to Record experiment variants in Agent Analytics and Run an agent experiment.

0.24.2

Released November 2, 2026.

Features

amplitude-ai-register-catalog now registers descriptions for the version properties Amplitude's enrichment sets: [Agent] Signal Versions on [Agent] Session Record, [Agent] Evaluator ID and [Agent] Evaluator Version on [Agent] Evaluator Result, and [Agent] Taxonomy Version for the org-wide evaluation configuration.

0.24.1

Released October 26, 2026.

Fixes

Preserve numeric values and valid JSON escaping in serialized JSON objects and arrays within structured content channels. Built-in redaction scans decoded string values and keys, masks numeric values under recognized phone, card, and SSN fields, and preserves other numeric tokens verbatim. Distinct original keys that collapse to one redacted key cause the serialized document to fail closed.

0.24.0

Released October 2026.

Features

Add optional $agent_artifact TypeScript type for inline message attachments, improving type inference without changing runtime capture or validating the artifact schema.
Preserve multi-agent lineage through agent delegation so the full agent chain is recorded when one agent delegates to another.
Set [Agent] Source on spans you create with an explicit user role, consistent with how provider-originated user messages are tracked.

Fixes

Restore artifact capture for tool and span input and output and for AI and user message attachments after a regression.
Harden artifact privacy: reject unsupported MathML snapshots, close CSS quote leakage, and bound static-artifact text visibility so content does not appear outside the active content mode. Raw HTML artifact snapshots are owned by the producer; existing content capture settings, best-effort string redaction, and size limits apply.
Record only the new user turn in LangChain conversations instead of re-recording all prior turns, preventing duplicate [Agent] User Message events.
Fix the OTLP replay script to reject --metadata-only before forwarding when the envelope is a raw resourceSpans payload, rather than silently including content the flag cannot remove.

0.23.0

Released October 2026. Public guide URLs now track main, so a later SDK release doesn't require new links. This release adds the AWS Strands guide, the privacy contract for HTTP, OpenTelemetry, Batch, S3, and warehouse imports, and states that [Agent] Session End is optional and recommended.

0.22.0

Released October 2026.

Features

Add review mode (reviewMode: true). The SDK records each post-redaction event and prints a sanitized pre-transport upload preview without sending it to Amplitude. Read the previews with getReviewTraffic(). For zero-code instrumentation, set AMPLITUDE_AI_REVIEW=true. Prompt and message content is left intact; the envelope API key is [REDACTED]. AMPLITUDE_AI_DEBUG does not enable review mode.

typescript

const ai = new AmplitudeAI({
  apiKey: process.env.AMPLITUDE_AI_API_KEY!,
  config: new AIConfig({ reviewMode: true }),
});

// Exercise a representative session, then:
await ai.flush();
console.log(ai.getReviewTraffic());

0.21.0

Released October 2026. This release hardens privacy handling, provider wrappers, the MCP server, the CLI tools, and the release pipeline. Amplitude recommends that all users upgrade: npm install @amplitude/ai@^0.21.0.

Behavior changes

tool() inherits the active content mode. Without a privacy config from the decorator, the session's AmplitudeAI client, or ToolCallTracker.setAmplitude(), it sends metadata only. To capture tool input and output, pass privacyConfig.
If a customRedactionFn throws, the SDK drops the affected content. Invalid customRedactionPatterns throw ConfigurationError when you build the config.
wrap() instruments the OpenAI, Azure OpenAI, or Anthropic client you pass in place, so it keeps your baseURL, fetch, headers, and timeouts. Request options such as signal, timeout, and headers pass through to the provider.
pushContext(ctx, fn) sets the context only while fn runs. Calling pushContext(ctx) without a callback still works but is deprecated and logs a warning once, because on an HTTP server the context can carry over to later requests on the same connection. Use pushContext(ctx, fn), runWithContext(), or session.run() instead.
amplitude-ai-instrument instruments only the process it launches. To instrument child Node processes too, set AMPLITUDE_AI_INSTRUMENT_CHILDREN=true.
The MCP scan_project tool reads only the client's MCP roots, or the server's working directory. To allow other directories, list them in AMPLITUDE_AI_MCP_ROOTS.
The MCP server uses your installed @modelcontextprotocol/sdk and zod instead of bundled copies, and tells you what to install if they're missing.
Peer dependency ranges have upper bounds: @amplitude/analytics-node, @opentelemetry/api, and tiktoken below 2, and @opentelemetry/sdk-trace-base below 3.
Docs and bundled guides run commands from the scoped package, npx -y -p @amplitude/ai <command>, and run integration scripts from the installed package, for example node node_modules/@amplitude/ai/docs/integrations/check-agent-events.mjs. Guide URLs point at a release tag instead of main.
With patch(), OpenAI and Anthropic calls return the SDK's own types: create() returns an APIPromise, so .withResponse() and .asResponse() work, and streams are the SDK Stream, so .tee() and .toReadableStream() work.
Patched provider calls inside a session go to the AmplitudeAI instance that owns the session, even when a different instance called patch().

Fixes

Tracking errors no longer affect the wrapped provider call.
Each AmplitudeAI instance keeps its own client and context propagation, and integrations resolve identity per run. Propagated context travels in request headers only, and IDs that aren't valid HTTP header values are left out instead of failing the request.
Debug logs omit message content, and warnings omit user IDs. Attachments and message labels go through redaction.
OpenTelemetry span mapping fixes.
Offline evaluation uploads require HTTPS and use a timeout. Flushes have a bounded timeout.
The package no longer bundles optional dependencies, so it ships about half as many files.
ai.flush({ timeoutMs }) stops waiting after the timeout and resolves without an error. ai.flush() with no options is unchanged.
A span that both enableOtel() and AmplitudeAgentExporter see is recorded once.
amplitude-ai-instrument forwards stop signals to the app it launched and exits with the app's exit code. It treats node_modules/.bin/<launcher>, such as tsx or nodemon, like the launcher itself.
amplitude-ai-doctor reports a malformed package.json as a failed check instead of crashing.
The MCP server masks more key formats in code snippets and limits the size of every tool argument.

0.20.1

Released October 7, 2026.

Fixes

@google/genai is now an optional peer dependency, like @google/generative-ai. The GoogleGenAI wrapper already required it.
The bundled README and agent guides now describe built-in signals as properties on [Agent] Session Record and custom evaluators as [Agent] Evaluator Result events. They also no longer list deprecated events.
The provider matrix now shows cache token stats for Gemini, Azure OpenAI, and Bedrock. Only Mistral doesn't report them.
The bundled amplitude-ai.md guide uses the correct trackToolCall options, input and output.

0.20.0

Released October 6, 2026. This release also includes the changes listed for 0.19.0, which wasn't published to npm.

Features

PROP_INGESTION_PATH and PROP_SOURCE constants for [Agent] Ingestion Path and [Agent] Source.
amplitude-ai-register-catalog now registers [Agent] Git SHA, [Agent] Git Ref, [Agent] Git Repo, and [Agent] Provider Request ID, which the SDK already sent.

Fixes

Gemini calls now record [Agent] Provider Request ID.
The SDK prices Fireworks router calls at the model the router selected, so they no longer lose [Agent] Cost USD.
amplitude-ai-register-catalog no longer registers [Agent] Enrichment Cost USD, which Amplitude no longer sends.
The SDK pins @pydantic/genai-prices to ^0.1.3, so a future major version can't silently drop cost.

0.18.0

Released September 24, 2026.

Features

Every tracked event now carries [Agent] Content Mode (full, metadata_only, or customer_enriched), so Amplitude can tell a deliberate metadata-only session from one whose instrumentation dropped the message text.
MockAmplitudeAI.summary() now fails when a user message has empty content, except in metadata_only and customer_enriched modes.

0.17.0

Released September 19, 2026.

Breaking changes

amplitude-ai-register-catalog no longer accepts credentials as arguments. It reads AMPLITUDE_API_KEY and AMPLITUDE_SECRET_KEY from the environment when the script runs. Write the script to a file with npx -y -p @amplitude/ai amplitude-ai-register-catalog > register.sh, review it, then run bash register.sh with both variables exported.

Features

Gateway recipes for OpenRouter, LiteLLM, and Requesty. Refer to Gateways.
The LangChain handler tracks [Agent] User Message for chat models.
The OpenTelemetry exporters accept privacyConfig, allowedScopes, and blockedScopes.

Fixes

When the SDK can't look up a model's price, it now omits [Agent] Cost USD instead of recording $0.

Was this helpful?