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

Released November 2, 2026.

Features

• Add the experiments= option on ai.agent(), agent.child(), agent.session(), and any track_* 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: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 run_as() inherit them; provider wrappers, @tool, and OTel-mapped events 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: experiments_from_amplitude(variants, keys=) maps an Amplitude Experiment fetch_v2(), evaluate_v2(), or all() result; amplitude_ai.openfeature.AmplitudeAIHook records flags an OpenFeature provider evaluates inside a session, with flags=, unit=, and variant_of= options; session.add_experiments() and the module-level add_experiments() record an assignment learned after the session started, shared across run_as() delegation. None of them sends an exposure event. experiment_from_evaluation() is the mapping behind the hook.
• 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.

Fixes

• Gemini cache TTL extensions no longer fail with "previous must describe the same cache resource" when Vertex spells the model path or create_time differently between the caches.create and caches.update responses.

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

• @tool inherits the active privacy config. Without one from the decorator, the AmplitudeAI client, or ToolCallTracker.set_amplitude(), it sends metadata only and logs a warning once. To capture tool input and output, pass privacy_config=.
• If a custom_redaction_fn raises, the SDK drops the affected content. If a custom_redaction_patterns entry is invalid, the SDK logs an error and withholds message content until you fix it.
• wrap() reuses the client you pass, so it keeps your base_url, http_client, headers, and timeouts. Client options you pass to wrap() apply through with_options().
• validate=True no longer raises inside wrapped provider calls.
• enable_otel() maps only spans with gen_ai.* or amplitude.* attributes by default. To also map other spans, such as HTTP and database spans, as [Agent] Span events, pass otel_span_filter="all".
• 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 instrument_file tool accepts only import statements in bootstrap_import. MCP tool inputs over 1 million characters are rejected.
• Dependency ranges have upper bounds, for example fastmcp<5 and starlette<2.
• Custom x-trace-id values 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-call amplitude_user_id takes 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.
• @observe resolves privacy settings in the same order as @tool, so the active session's content mode applies.
• AIConfig.propagate_context takes 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-call amplitude_user_id or the wrap(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 call unpatch().
• Requests to a localhost upload or catalog endpoint skip HTTP_PROXY and HTTPS_PROXY.
• The MCP instrument_file tool runs in linear time on files with many route handlers.
• Processes started by amplitude-ai-instrument keep AMPLITUDE_AI_API_KEY in their environment. Start untrusted subprocesses with an environment that leaves it out.

1.17.0

Released October 7, 2026.

Behavior changes

• AIConfig.redact_pii now defaults to True. Before this release, AmplitudeAI built without an explicit redact_pii sent message content unredacted, while PrivacyConfig, 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, pass AIConfig(redact_pii=False).

Fixes

• The PyPI page no longer links to a private repository, and its Documentation link points at the AI SDK reference.
• The bundled agent guide uses the correct FastAPI middleware import, amplitude_ai.middleware.AmplitudeAIMiddleware, with its required amplitude_ai= and user_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 Rationale and [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, or customer_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_only and customer_enriched modes.

1.14.0

Released September 19, 2026.

Breaking changes

• amplitude-ai-register-catalog no longer accepts a secret key as an argument, because other local users can read arguments with ps. Set AMPLITUDE_API_KEY and AMPLITUDE_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 USD instead of recording $0.