Node AI SDK release notes

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.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.