Python AI SDK release notes
Release notes for amplitude-ai. For the Node SDK, refer to Node AI SDK release notes. For the full engineering changelog, go to the amplitude-ai CHANGELOG on GitHub.
1.26.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_KEYSandAMPLITUDE_AI_CONTEXT_ACTIVE_KID, or withAIConfig(context_policy=ContextPolicy(signing_keys=...)). Each signature carries a key ID and an expiry, so keys can rotate. The wire format is shared with the Node SDK. - Add
session(context=...). Pass the whole result ofextract_a2a_metadata(),extract_acp_meta(), orextract_context(). 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 matchingamplitude.*OpenTelemetry attributes. - Add identity modes. A2A and ACP send no user ID by default.
identity="pairwise"withrecipient=sends a stable per-recipient pseudonym, andidentity="raw"sends the user ID and requires a signing key. - Add
inject_a2a_response_metadata(),inject_acp_result_meta(), andinject_response_headers()to return the receiver's context, andpeer_properties()andtrack_tool_call(..., peer=...)to link one call to the agent that answered it. - Add
context_properties(), which returns the session, trace, and agent IDs to put on business events such as a checkout. It never includes the user ID. - Add
mint_context(), so a gateway or backend can sign a context outside a session. - Add
AmplitudeAIMiddleware(accept_context=True), which applies the same trust rules to inbound headers and adopts only a verified context. amplitude-ai doctorchecks the agent context keys and pairwise salts, andamplitude-ai doctor --verify '<envelope>'explains why a context did or didn't verify. Neither prints a secret.- Add
[Agent] Session Triggerfor coding agent sessions:interactive,headless,ci,scheduled, orevent. Codex and Cursor events also carry[Agent] Root Agent Nameand[Agent] Agent Chain Depth. - The commit hook adds an
Agent-Triggertrailer to agent commits. The outcomes workflow sends each code outcome as an[Agent] Scorewith theoutcomeevaluation source on the session that wrote the commit, in place of theCommit Merged,Commit Reverted,Pull Request Merged,Deploy Succeeded, andDeploy Failedevents. Score names includecommit_merged,commit_reverted,deploy_succeeded,deploy_failed,ci_passed_first_run,review_rounds,hours_open, andhours_to_first_review, and every score carriesagent_trigger. Only commits with anAgent-Session-Idtrailer get scores.
Behavior changes
- A2A and ACP send no user ID by default.
include_identity=oninject_a2a_metadata()andinject_acp_meta()still works but is deprecated:Truemeansidentity="raw", which now requires a signing key. - An unsigned A2A or ACP context is linked as a peer instead of adopted.
- 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.
1.25.0
Released November 2026.
Features
- Add
CodexSDKTracker(amplitude_ai.integrations.codex_sdk), which maps Codex SDK thread events, andcodex exec --jsonoutput, to user messages, AI responses, tool calls, and per-turn tokens. - Add
amplitude-ai hook codex, a CodexStophook 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] [--dry-run] [--dir PATH] [--json]. It writes a commit trailer hook in.githooks/, the.github/workflows/agent-outcomes.ymloutcomes workflow, and the Claude Code or Codex settings, and prints the environment for goose. The API key goes only to gitignored files. Acore.hooksPaththat's already set elsewhere is reported as a conflict and left alone.amplitude-ai coding-agents doctorchecks the hooks path, the hook, the workflow, and each harness's settings. - Tool calls that create a commit carry a
commit_shaevent property, read fromgit commitoutput or from GitHub commit, push, pull request, and file tools. - Add
inject_a2a_metadata(),extract_a2a_metadata(),inject_acp_meta(), andextract_acp_meta(), so child agents in another process join the parent's session.
Refer to Coding agents and Across processes.
1.24.0
Released November 2026.
Features
voice_turn_properties()accepts stage latency and call timing:stt_ms,llm_ttft_ms,tts_ttfb_ms,turn_start_offset_ms,turn_end_offset_ms(milliseconds from call start),pre_reply_silence_ms, andoverlap_ms. 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, raisesValidationError.- Add a LiveKit Agents integration:
amplitude_ai.integrations.livekit.attach(lk_session, agent, model=..., provider=...)tracks every finished caller and agent message of anAgentSessionas a voice turn, with stage latency and call timeline offsets. - Add a Pipecat integration:
amplitude_ai.integrations.pipecat.PipecatVoiceTrackertracks one caller and one agent turn per exchange from pipeline frames. Passamplitude_observer(tracker)inPipelineTask(observers=[...]). - 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.
1.22.0
Released November 2, 2026.
Features
- Add the
experiments=option onai.agent(),agent.child(),agent.session(), and anytrack_*call on an agent or session. It records A/B test or feature flag assignment as[{"key", "variant", "provider"?, "unit"?}], and every event carries[Agent] Experiments(key:variantstrings) plus[Agent] Experiment Key,Variant,Unit, andProviderwhen exactly one experiment applies, so any chart splits by arm. Call entries override session entries, which override agent entries, by key; child agents andrun_as()inherit them; provider wrappers,@tool, and OTel-mapped events inside a session carry them.unitisagent_session(default),turn, orspan; 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:
experiments_from_amplitude(variants, keys=)maps an Amplitude Experimentfetch_v2(),evaluate_v2(), orall()result;amplitude_ai.openfeature.AmplitudeAIHookrecords flags an OpenFeature provider evaluates inside a session, withflags=,unit=, andvariant_of=options;session.add_experiments()and the module-leveladd_experiments()record an assignment learned after the session started, shared acrossrun_as()delegation. None of them sends an exposure event.experiment_from_evaluation()is the mapping behind the hook. - MCP server:
scan_projectreportsexperiment_packagesandflag_call_sites;instrument_fileadds a TODO where a file reads a flag;validate_fileflags the legacyexperiment_variantcontext form and helpers called withoutkeys=orflags=;generate_verify_testchecks that session experiments reach every event;MockAmplitudeAI.summary()reports anExperiments fillline.
Fixes
- Gemini cache TTL extensions no longer fail with "previous must describe the same cache resource" when Vertex spells the model path or
create_timedifferently between thecaches.createandcaches.updateresponses.
Refer to Record experiment variants in Agent Analytics and Run an agent experiment.
1.18.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: python3 -m pip install --upgrade "amplitude-ai>=1.18.0".
Behavior changes
@toolinherits the active privacy config. Without one from the decorator, theAmplitudeAIclient, orToolCallTracker.set_amplitude(), it sends metadata only and logs a warning once. To capture tool input and output, passprivacy_config=.- If a
custom_redaction_fnraises, the SDK drops the affected content. If acustom_redaction_patternsentry is invalid, the SDK logs an error and withholds message content until you fix it. wrap()reuses the client you pass, so it keeps yourbase_url,http_client, headers, and timeouts. Client options you pass towrap()apply throughwith_options().validate=Trueno longer raises inside wrapped provider calls.enable_otel()maps only spans withgen_ai.*oramplitude.*attributes by default. To also map other spans, such as HTTP and database spans, as[Agent] Spanevents, passotel_span_filter="all".- The MCP
scan_projecttool reads only the client's MCP roots, or the server's working directory. To allow other directories, list them inAMPLITUDE_AI_MCP_ROOTS. - The MCP
instrument_filetool accepts only import statements inbootstrap_import. MCP tool inputs over 1 million characters are rejected. - Dependency ranges have upper bounds, for example
fastmcp<5andstarlette<2. - Custom
x-trace-idvalues are limited to 64 characters, matching the Node SDK. Longer values are ignored on inbound requests and aren't sent on outbound ones. - With
enable_otel(), the per-callamplitude_user_idtakes priority over the session user for the SDK's own spans, the same as without OpenTelemetry.
Fixes
- Tracking errors no longer affect the wrapped provider call, and sync streams return the provider's stream object.
- Uploads that carry your API key go only to the configured HTTPS origin, don't follow redirects, and time out after 30 seconds.
- PII redaction covers Unicode text, emails with accented, Greek, or Cyrillic characters, and structured payloads, and applies to patched Gemini and Mistral calls and to enrichment free text. Captured content excludes media parts.
@observeresolves privacy settings in the same order as@tool, so the active session's content mode applies.AIConfig.propagate_contexttakes effect. Context IDs that aren't valid HTTP header values are left out instead of failing the request.- Error logs omit message content and user IDs, and CLI and status output mask keys.
- The MCP server starts without a banner or a PyPI update check. The CLI reads its guide only from the installed package, and bundled docs ship under
amplitude_ai/_docs/. - With
enable_otel(), provider calls outside a session use the per-callamplitude_user_idor thewrap(user_id=...)default. wrap(wrapped_client, amplitude=other)no longer inherits the inner wrapper's user and device defaults.- LangChain and OpenAI Agents handlers cap their per-run state at 10,000 entries, so runs that never finish don't grow memory.
- Calling
patch()again for a provider that's already patched logs a warning. The first settings stay in effect until you callunpatch(). - Requests to a localhost upload or catalog endpoint skip
HTTP_PROXYandHTTPS_PROXY. - The MCP
instrument_filetool runs in linear time on files with many route handlers. - Processes started by
amplitude-ai-instrumentkeepAMPLITUDE_AI_API_KEYin their environment. Start untrusted subprocesses with an environment that leaves it out.
1.17.0
Released October 7, 2026.
Behavior changes
AIConfig.redact_piinow defaults toTrue. Before this release,AmplitudeAIbuilt without an explicitredact_piisent message content unredacted, whilePrivacyConfig,patch(), the standalone provider wrappers, and the Node SDK already redacted by default. Built-in redaction scrubs emails, phone numbers, SSNs, credit card numbers, and IP addresses before events leave your process. To keep raw content, passAIConfig(redact_pii=False).
Fixes
- The PyPI page no longer links to a private repository, and its
Documentationlink points at the AI SDK reference. - The bundled agent guide uses the correct FastAPI middleware import,
amplitude_ai.middleware.AmplitudeAIMiddleware, with its requiredamplitude_ai=anduser_id_resolver=arguments. - The bundled agent guides no longer list
[Agent] Topic Classification, which Amplitude no longer sends.
1.16.0
Released October 6, 2026.
Features
- The event catalog adds
[Agent] Data Quality Rationaleand[Agent] Data Quality Evidence.
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.
1.15.0
Released September 24, 2026.
Features
- Every tracked event now carries
[Agent] Content Mode(full,metadata_only, orcustomer_enriched), so Amplitude can tell a deliberate metadata-only session from one whose instrumentation dropped the message text. - Local verification now fails when a user message has empty content, except in
metadata_onlyandcustomer_enrichedmodes.
1.14.0
Released September 19, 2026.
Breaking changes
amplitude-ai-register-catalogno longer accepts a secret key as an argument, because other local users can read arguments withps. SetAMPLITUDE_API_KEYandAMPLITUDE_SECRET_KEY, or pass--secret-key -to read the secret from stdin.--secret-key <value>now exits with an error.
Fixes
- When the SDK can't look up a model's price, it now omits
[Agent] Cost USDinstead 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.