On this page

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.

Python AI SDK release notes

pypiv1.17.0

Release notes for amplitude-ai. For the Node SDK, refer to Node AI SDK release notes.

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.

Was this helpful?