Node AI SDK release notes

npmv0.31.0164.0 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.31.0

Released November 2026.

Features

  • Add Copilot CLI session stamping on commits. The prepare-commit-msg hook reads COPILOT_AGENT_SESSION_ID and stamps Agent-Session-Id with Agent-Name: copilot, matching the gen_ai.conversation.id Copilot CLI telemetry reports. The hook checks Copilot before goose's AGENT_SESSION_ID, which a Copilot shell may inherit.
  • Add Gemini CLI session hook. amplitude-ai hook gemini is a BeforeTool hook that rewrites git commit commands to inject Agent-Session-Id, Agent-Name: gemini-cli, Agent-Trigger, and task trailers as --trailer arguments. Install it with coding-agents init --harness gemini, which merges it into .gemini/settings.json. Requires git 2.32 or later.
  • Add task trailers. Agent commits carry Agent-Task (from AMPLITUDE_TASK_ID, .amplitude-ai/local.env, or the first ticket key in the branch name) and Agent-Task-Type (from AMPLITUDE_TASK_TYPE, local.env, or the branch's conventional prefix). Values outside [A-Za-z0-9._:-]{1,64} are dropped.
  • Add session ID validation to the commit hook. The hook stamps a session ID only when it matches [A-Za-z0-9._:-]{1,128}, preventing a value with a newline from adding trailers.
  • Add Outcomes workflow v4 (outcomes_workflow_version: 4). Every score carries task_id and task_type from commit trailers. ci_passed_first_run now carries ci_run_id, ci_run_url, ci_workflow_name, ci_conclusion, and ci_failed_checks (up to 10 failed checks from the first push). New PR scores: ci_failed_runs and ci_rerun_attempts. A Copilot-Session trailer counts as the session ID when no Agent-Session-Id is present. Buzz worker commits take their user from the last Co-authored-by that isn't a coding agent. init upgrades an untouched 0.30.0 workflow and hook in place.
  • Add coding-agents init --require-trailers. Installs agent-trailers.yml, a GitHub Actions workflow that warns about agent commits without a session trailer and fails only when the repository variable AMPLITUDE_REQUIRE_AGENT_TRAILERS is true.
  • Add coding-agents doctor checks for gemini_session_hook (installed and not disabled), git_version (2.32 or later, required with Gemini CLI), goose_version (1.44.0 or later, when goose is on the PATH), and stamped_commits (which harnesses stamped the last 20 commits).
  • Add Buzz worker session linking. Worker tool calls now carry the worker's goose session in [Agent] Context as harness_session_id, so outcome scores join the thread.

Behavior changes

  • goose commit stamping requires goose 1.44.0 or later. Earlier versions passed an inherited AGENT_SESSION_ID and continue to work, but goose 1.44.0 is required for the native session hook.

0.30.0

Released November 16, 2026.

Breaking changes

  • The agent-outcomes.yml workflow v3 (outcomes_workflow_version: 3) replaces the Commit Merged, Commit Reverted, Pull Request Merged, Deploy Succeeded, and Deploy Failed events with [Agent] Score events on the session that wrote each commit. The event time is the commit's author date, inside the session; outcome_time records when the outcome happened. Commits with no author date are not scored. A deployed or reverted squash or merge commit stands for its PR's commits; each is scored individually. Only commits with an Agent-Session-Id trailer receive scores — Gemini CLI commits, cloud-agent commits attributed only by author or Co-authored-by, commits made through the API, and human commits send nothing, and the reviews and CI lookups are skipped for a PR without one.
  • The following properties are removed: agent_authored, agent_attribution, attributed_agent, agent_names, agent_session_ids, attributed_agents, and agent_triggers.
  • amplitude-ai coding-agents init upgrades an untouched v1, 0.28.0, or 0.29.0 workflow in place.

Refer to Coding agents.

0.29.0

Released November 9, 2026.

Features

  • Add signed agent context v1. Agents that call each other over A2A, the Agent Client Protocol, or HTTP sign the context they send with HMAC-SHA256. Configure keys with AMPLITUDE_AI_CONTEXT_KEYS and AMPLITUDE_AI_CONTEXT_ACTIVE_KID, or with config: new AIConfig({ contextPolicy: new ContextPolicy({ signingKeys }) }). Each signature carries a key ID and an expiry, so keys can rotate. The wire format is shared with the Python SDK.
  • Add session({ context }). Pass the whole result of extractA2aMetadata(), extractAcpMeta(), or extractContext(). A context whose signature verifies continues the caller's session, user, parent agent, and trace ID. Any other context starts its own session and records the caller as [Agent] Peer Agent ID, [Agent] Peer Session ID, and [Agent] Peer Trace ID. Every event of the session carries [Agent] Context Trust, [Agent] Context Verify Result, [Agent] Actor Type, and [Agent] Identity Type, with matching amplitude.* OpenTelemetry attributes.
  • Add identity modes. A2A and ACP send no user ID by default. identity: 'pairwise' with a recipient sends a stable per-recipient pseudonym, and identity: 'raw' sends the user ID and requires a signing key.
  • Add injectA2aResponseMetadata(), injectAcpResultMeta(), and injectResponseHeaders() to return the receiver's context, and peerProperties() and the peer option on trackToolCall() to link one call to the agent that answered it.
  • Add contextProperties(), which returns the session, trace, and agent IDs to put on business events such as a checkout. It never includes the user ID.
  • Add mintContext(), so a backend can sign a context for a browser or mobile client that can't hold a key.
  • Add setContextPolicy() and getContextPolicy(). The contextPolicy in AIConfig also applies outside a session.
  • Add acceptContext: true on createAmplitudeAIMiddleware(), which applies the same trust rules to inbound headers and never adopts unsigned ones. extractContext() and the middleware accept a Fetch API Headers object.
  • amplitude-ai doctor checks the agent context keys and pairwise salts, and amplitude-ai doctor --verify '<envelope>' explains why a context did or didn't verify. Neither prints a secret.
  • Add [Agent] Session Trigger for coding agent sessions: interactive, headless, ci, scheduled, or event. Codex and Cursor events also carry [Agent] Root Agent Name and [Agent] Agent Chain Depth.
  • The commit hook adds an Agent-Trigger trailer to agent commits. The outcomes workflow sends each code outcome as an [Agent] Score with the outcome evaluation source on the session that wrote the commit, in place of the Commit Merged, Commit Reverted, Pull Request Merged, Deploy Succeeded, and Deploy Failed events. Score names include commit_merged, commit_reverted, deploy_succeeded, deploy_failed, ci_passed_first_run, review_rounds, hours_open, and hours_to_first_review, and every score carries agent_trigger. Only commits with an Agent-Session-Id trailer get scores. amplitude-ai coding-agents init updates an unedited 0.28.0 hook and workflow in place.

Behavior changes

  • extractA2aMetadata() and extractAcpMeta() return the caller's IDs only for a verified context. Otherwise they return the peer IDs.
  • The A2A extension URI is now https://amplitude.com/docs/amplitude-ai/agent-analytics/agent-context-v1.
  • Unsigned HTTP context is deprecated. A receiver without signing keys still adopts unsigned x-amplitude-* headers in this release, with a one-time warning. A receiver with keys, or with an invalid key configuration, treats them as untrusted.

Refer to Across processes, Amplitude agent context v1, and Coding agents.

0.28.0

Released November 2026.

Features

  • Add CodexSDKTracker (@amplitude/ai/integrations/codex-sdk), which maps Codex SDK thread events, and codex exec --json output, to user messages, AI responses, tool calls, and per-turn tokens.
  • Add amplitude-ai hook codex, a Codex Stop hook that forwards Codex CLI sessions from Codex's own session transcript. Resent turns don't count twice.
  • Add amplitude-ai coding-agents init [--harness claude-code|codex|goose] [--privacy full|metadata] [--region us|eu] [--api-key-stdin | --api-key-env NAME] [--force] [--dry-run] [--dir PATH] [--json]. It writes a commit trailer hook in .githooks/, the .github/workflows/agent-outcomes.yml outcomes workflow, and the Claude Code or Codex settings, and prints the environment for goose. The API key goes only to gitignored files. A core.hooksPath that's already set elsewhere is reported as a conflict unless you pass --force. amplitude-ai coding-agents doctor [--dir PATH] [--json] checks the hooks path, the hook, the workflow, and each harness's settings.
  • Tool calls that create a commit carry a commit_sha event property, read from git commit output or from GitHub commit, push, pull request, and file tools.
  • Add A2A Message.metadata and ACP _meta propagation helpers, so child agents in another process join the parent's session.
  • Add the Buzz forwarder and the ADK BigQuery Agent Analytics warehouse template, plus integration guides for Claude Code, Codex, goose, and Buzz.

Refer to Coding agents and Across processes.

0.27.0

Released November 2026.

Features

  • voiceTurnProperties() accepts stage latency and call timing: sttMs, llmTtftMs, ttsTtfbMs, turnStartOffsetMs, turnEndOffsetMs (milliseconds from call start), preReplySilenceMs, and overlapMs. They set [Agent] Voice STT Ms, [Agent] Voice LLM TTFT Ms, [Agent] Voice TTS TTFB Ms, [Agent] Voice Turn Start Offset Ms, [Agent] Voice Turn End Offset Ms, [Agent] Voice Pre Reply Silence Ms, and [Agent] Voice Overlap Ms. A negative value, or an end offset before the start offset, throws ValidationError.
  • Add NovaSonicTurnMapper, which maps Amazon Nova Sonic bidirectional stream events to voice turns. It was previously in the Python SDK only.
  • The event catalog describes the new voice turn properties and the voice session rollups and flags that Amplitude's enrichment sets on [Agent] Session Record.

Refer to Instrument voice agents.

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?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

On this page