Metadata-Version: 2.4
Name: amplitude-ai
Version: 1.11.0
Summary: Agent analytics for Amplitude
Project-URL: Homepage, https://amplitude.com
Project-URL: Documentation, https://docs.amplitude.com
Author-email: Amplitude <sdk@amplitude.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,amplitude,analytics,anthropic,llm,observability,openai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: amplitude-analytics>=1.0.0
Requires-Dist: genai-prices>=0.0.53
Provides-Extra: all
Requires-Dist: anthropic<1.0.0,>=0.75.0; extra == 'all'
Requires-Dist: boto3<2.0.0,>=1.40.0; extra == 'all'
Requires-Dist: crewai>=0.80.0; extra == 'all'
Requires-Dist: fastmcp>=2.14.0; extra == 'all'
Requires-Dist: google-genai<2.0.0,>=1.0.0; extra == 'all'
Requires-Dist: langchain-core>=0.1.0; extra == 'all'
Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
Requires-Dist: mistralai<2.0.0,>=1.0.0; extra == 'all'
Requires-Dist: openai-agents>=0.0.3; extra == 'all'
Requires-Dist: openai<3.0.0,>=2.0.0; extra == 'all'
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'all'
Requires-Dist: starlette>=0.41.0; extra == 'all'
Requires-Dist: tiktoken>=0.12.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic<1.0.0,>=0.75.0; extra == 'anthropic'
Provides-Extra: azure
Requires-Dist: openai<3.0.0,>=2.0.0; extra == 'azure'
Provides-Extra: bedrock
Requires-Dist: boto3<2.0.0,>=1.40.0; extra == 'bedrock'
Provides-Extra: crewai
Requires-Dist: crewai>=0.80.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25.0; extra == 'docs'
Provides-Extra: fastapi
Requires-Dist: starlette>=0.41.0; extra == 'fastapi'
Provides-Extra: gemini
Requires-Dist: google-genai<2.0.0,>=1.0.0; extra == 'gemini'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.14.0; extra == 'mcp'
Provides-Extra: mistral
Requires-Dist: mistralai<2.0.0,>=1.0.0; extra == 'mistral'
Provides-Extra: openai
Requires-Dist: openai<3.0.0,>=2.0.0; extra == 'openai'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.0.3; extra == 'openai-agents'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otel'
Provides-Extra: tokens
Requires-Dist: tiktoken>=0.12.0; extra == 'tokens'
Description-Content-Type: text/markdown

<a id="amplitude-ai"></a>
# amplitude-ai

[![PyPI version](https://img.shields.io/pypi/v/amplitude-ai)](https://pypi.org/project/amplitude-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Agent analytics for [Amplitude](https://amplitude.com). Track every LLM call, user message, tool call, and quality signal as events in your Amplitude project — then build funnels, cohorts, and retention charts across AI and product behavior alongside your existing product events.

<a id="-documentation"></a>
## 📘 Documentation

The canonical SDK reference lives in Amplitude Docs:

**[amplitude.com/docs/sdks/agent-analytics/sdk](https://amplitude.com/docs/sdks/agent-analytics/sdk)**

That page covers installation, the full event taxonomy, sessions, tools, spans, scores, multi-agent delegation, streaming, edge runtimes, provider-specific notes (OpenAI, AzureOpenAI, Anthropic, Gemini, Bedrock, Mistral, Anthropic Managed Agents), cost and prompt-cache handling, privacy modes, content shaping, verification with `MockAmplitudeAI`, and the complete API.

<a id="install"></a>
## Install

```bash
pip install amplitude-ai
```

<a id="quick-start"></a>
## Quick start

```python
import os
from amplitude_ai import AmplitudeAI
from amplitude_ai.providers.openai import OpenAI

ai = AmplitudeAI(api_key=os.environ["AMPLITUDE_AI_API_KEY"])
openai = OpenAI(amplitude=ai, api_key=os.environ["OPENAI_API_KEY"])
agent = ai.agent("my-agent")

async def handle_chat(user_id: str, session_id: str, messages: list):
    session = agent.session(user_id=user_id, session_id=session_id)
    with session.run() as s:
        s.track_user_message(messages[-1]["content"])
        response = await openai.chat.completions.create(model="gpt-4o", messages=messages)
        return response.choices[0].message.content
    ai.flush()
```

Emits `[Agent] User Message`, `[Agent] AI Response`, and `[Agent] Session End` — tied to `user_id` and `session_id`. Auto-captures model, tokens, cost, and latency on the AI Response. Read the [SDK reference](https://amplitude.com/docs/sdks/agent-analytics/sdk) for the rest.

<a id="provider-wrappers"></a>
## Provider wrappers

Each wrapper records request, response, tokens, latency, and cost automatically:

```python
from amplitude_ai.providers import openai, anthropic, azure_openai, gemini, bedrock, mistral
```

See [Auto-instrument provider calls](https://amplitude.com/docs/sdks/agent-analytics/sdk#auto-instrument-provider-calls) for the full table and per-provider notes (Anthropic Managed Agents).

**Provider wrappers + delegation:** Inside `session.run_as()` / `session.arun_as()`, provider wrappers suppress auto `[Agent] User Message` emission so that internal `role: "user"` prompts in delegation calls don't create spurious user turns.

<a id="fan-out-llm-parallel-child-calls"></a>
## Fan-out LLM (parallel child calls)

When a single user action triggers multiple parallel LLM calls, use `arun_as()` to delegate:

```python
async with orchestrator.session(session_id=sid) as s:
    s.new_trace()
    s.track_user_message("Generate plan from quiz results", context=state)

    async def run_child(child):
        async with s.arun_as(child) as _cs:
            return await client.chat.completions.create(model="gpt-4o", messages=[...])

    a, b = await asyncio.gather(run_child(scorer), run_child(matcher))
    s.track_ai_message(content=assemble(a, b), model="gpt-4o", provider="openai")
```

This ensures one trace, one user turn, one AI response — regardless of how many internal LLM calls are dispatched. See [Step 3g-b in the instrumentation guide](https://github.com/amplitude/Amplitude/blob/master/langley/amplitude_ai/amplitude-ai.md) for details.

<a id="auto-instrument-with-an-ai-coding-agent"></a>
## Auto-instrument with an AI coding agent

```bash
amplitude-ai
```

Paste the printed prompt into Cursor, Claude Code, GitHub Copilot, or Codex. The agent reads the in-repo instrumentation guide ([`amplitude-ai.md`](https://github.com/amplitude/Amplitude/blob/master/langley/amplitude_ai/amplitude-ai.md)), scans your project, discovers your LLM call sites, and instruments everything — provider wrappers, sessions, multi-agent delegation, tools, scoring, and a verification test.

<a id="privacy"></a>
## Privacy

Three content modes control what reaches Amplitude:

- `full` (default) — content captured, PII redacted by default.
- `metadata_only` — token counts, latency, model, cost. No content.
- `customer_enriched` — no content; you provide structured summaries via `track_session_enrichment()`.

Full details and per-provider redaction recipes at [Choose a privacy mode](https://amplitude.com/docs/sdks/agent-analytics/sdk#choose-a-privacy-mode).

<a id="otel-span-first-mode"></a>
## OTEL Span-First Mode

Route all instrumentation through OpenTelemetry spans. The SDK's `AmplitudeEventSpanProcessor` maps GenAI semantic convention spans into `[Agent]` events. Provider wrappers and decorators continue to work — de-duplication prevents double-counting.

```python
ai = AmplitudeAI(api_key=os.environ["AMPLITUDE_AI_API_KEY"])
ai.enable_otel(default_user_id="fallback-uid")
```

Requires optional deps: `pip install opentelemetry-api opentelemetry-sdk`

Use `@observe(type="tool"|"agent"|"llm"|"span")` to create typed OTEL spans that map to the corresponding `[Agent]` event types. Use `ai.using_attributes()` to propagate context to spans within a block.

<a id="local-verification"></a>
## Local Verification

`MockAmplitudeAI.summary()` prints a fill-rate report showing which of the key Agent Analytics fields (identity, session, model, provider, latency, tokens, cost) are populated across your captured events:

```python
from amplitude_ai.testing import MockAmplitudeAI

mock = MockAmplitudeAI()
agent = mock.agent("test-agent")
with agent.session(user_id="u1", session_id="s1") as s:
    s.track_user_message("hello")
    s.track_ai_message("response", "gpt-4o-mini", "openai", 150)

print(mock.summary())
```

<a id="event-property-reference"></a>
## Event Property Reference

<!-- BEGIN EVENT PROPERTY REFERENCE -->

<a id="common-properties-present-on-all-sdk-events"></a>
### Common Properties (present on all SDK events)

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Session ID` | string | Yes | Unique session identifier. All events in one conversation share the same session ID. |
| `[Agent] Trace ID` | string | No | Groups events into a single "Turn" in the trace viewer. All events in one user-to-AI-response exchange share the same trace ID. Each distinct trace ID becomes a collapsible turn card. Events without a trace ID fall back to the session ID and collapse into Turn 1. |
| `[Agent] Turn ID` | number | No | Monotonically increasing counter for event ordering within a session. |
| `[Agent] Agent ID` | string | No | Identifies which AI agent handled the interaction (e.g., 'support-bot', 'houston'). |
| `[Agent] Parent Agent ID` | string | No | For multi-agent orchestration: the agent that delegated to this agent. |
| `[Agent] Customer Org ID` | string | No | Organization ID for multi-tenant platforms. Enables account-level group analytics. |
| `[Agent] Agent Version` | string | No | Agent code version (e.g., 'v4.2'). Enables version-over-version quality comparison. |
| `[Agent] Agent Description` | string | No | Human-readable description of the agent's purpose (e.g., 'Handles user chat requests via OpenAI GPT-4o'). Enables observability-driven agent registry from event streams. |
| `[Agent] Context` | string | No | Serialized JSON dict of arbitrary segmentation dimensions (experiment_variant, surface, feature_flag, prompt_revision, etc.). |
| `[Agent] Env` | string | No | Deployment environment: 'production', 'staging', or 'dev'. |
| `[Agent] SDK Version` | string | Yes | Version of the amplitude-ai SDK that produced this event. |
| `[Agent] Runtime` | string | Yes | SDK runtime: 'python' or 'node'. |
| `[Agent] Tags` | string | No | Serialized JSON dict of session-level tags for segmentation (e.g., experiment, surface, feature_flag). |
| `[Agent] Git SHA` | string | No | Git commit SHA of the deployed agent code. Auto-captured from environment or git CLI. |
| `[Agent] Git Ref` | string | No | Git branch or tag name (e.g., 'main', 'v1.2.3'). Auto-captured from environment or git CLI. |
| `[Agent] Git Repo` | string | No | Git repository URL. Auto-captured from environment or git CLI. |

<a id="user-message-properties"></a>
### User Message Properties

Event-specific properties for `[Agent] User Message` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Message ID` | string | Yes | Unique identifier for this message event (UUID). Used to link scores and tool calls back to specific messages. |
| `[Agent] Component Type` | string | Yes | Type of component that produced this event: 'user_input', 'llm', 'tool', 'embedding'. |
| `[Agent] Locale` | string | No | User locale (e.g., 'en-US'). |
| `[Amplitude] Session Replay ID` | string | No | Links to Amplitude Session Replay (format: device_id/session_id). Enables one-click navigation from AI session to browser replay. |
| `[Agent] Is Regeneration` | boolean | No | Whether the user requested the AI regenerate a previous response. |
| `[Agent] Is Edit` | boolean | No | Whether the user edited a previous message and resubmitted. |
| `[Agent] Edited Message ID` | string | No | The message_id of the original message that was edited (links the edit to the original). |
| `[Agent] Has Attachments` | boolean | No | Whether this message includes file attachments (uploads, images, etc.). |
| `[Agent] Attachment Types` | string[] | No | Distinct attachment types (e.g., 'pdf', 'image', 'csv'). Serialized JSON array. |
| `[Agent] Attachment Count` | number | No | Number of file attachments included with this message. |
| `[Agent] Total Attachment Size Bytes` | number | No | Total size of all attachments in bytes. |
| `[Agent] Attachments` | string | No | Serialized JSON array of attachment metadata (type, name, size_bytes, mime_type). Only metadata, never file content. |
| `[Agent] Message Labels` | string | No | Serialized JSON array of MessageLabel objects (key-value pairs with optional confidence). Used for routing tags, classifier output, business context. |
| `[Agent] Message Source` | string | No | Origin of the user message: 'user' for real end-user input, 'agent' for inter-agent delegation (parent agent sending instructions to a child agent). Automatically set by provider wrappers based on parent_agent_id context. |

<a id="ai-response-properties"></a>
### AI Response Properties

Event-specific properties for `[Agent] AI Response` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Message ID` | string | Yes | Unique identifier for this message event (UUID). Used to link scores and tool calls back to specific messages. |
| `[Agent] Component Type` | string | Yes | Type of component that produced this event: 'user_input', 'llm', 'tool', 'embedding'. |
| `[Agent] Model Name` | string | Yes | LLM model identifier (e.g., 'gpt-4o', 'claude-sonnet-4-20250514'). |
| `[Agent] Provider` | string | Yes | LLM provider name (e.g., 'openai', 'anthropic', 'google', 'mistral', 'bedrock'). |
| `[Agent] Latency Ms` | number | Yes | Total wall-clock latency in milliseconds for this operation. |
| `[Agent] Is Error` | boolean | Yes | Whether this event represents an error condition. |
| `[Agent] Error Message` | string | No | Error message text when Is Error is true. |
| `[Agent] Error Type` | string | No | Exception class name when Is Error is true (e.g., 'ValidationError', 'TimeoutError'). Distinct from Error Message so downstream tooling can group failures by type without parsing the message. |
| `[Agent] Stack Trace` | string | No | Stack trace captured on error when capture_stack_trace=True in AIConfig. Privacy-gated. |
| `[Agent] Error Source` | string | No | Origin of the error: 'provider' (LLM API), 'tool' (tool execution), 'framework' (SDK/pipeline), or 'user' (validation). |
| `[Agent] Locale` | string | No | User locale (e.g., 'en-US'). |
| `[Agent] Span Kind` | string | No | Classification of the span type for OTEL bridge compatibility. |
| `[Amplitude] Session Replay ID` | string | No | Links to Amplitude Session Replay (format: device_id/session_id). Enables one-click navigation from AI session to browser replay. |
| `[Agent] TTFB Ms` | number | No | Time to first byte/token in milliseconds. Measures perceived responsiveness for streaming. |
| `[Agent] Input Tokens` | number | No | Number of input/prompt tokens consumed by this LLM call. |
| `[Agent] Output Tokens` | number | No | Number of output/completion tokens generated by this LLM call. |
| `[Agent] Total Tokens` | number | No | Total tokens consumed (input + output). |
| `[Agent] Reasoning Tokens` | number | No | Tokens consumed by reasoning/thinking (o1, o3, extended thinking models). |
| `[Agent] Cache Read Tokens` | number | No | Input tokens served from the provider's prompt cache (cheaper rate). Used for cache-aware cost calculation. |
| `[Agent] Cache Creation Tokens` | number | No | Input tokens that created new prompt cache entries. |
| `[Agent] Cost USD` | number | No | Estimated cost in USD for this LLM call. Cache-aware when cache token counts are provided. |
| `[Agent] Finish Reason` | string | No | Why the model stopped generating: 'stop', 'end_turn', 'tool_use', 'length', 'content_filter', etc. |
| `[Agent] Tool Calls` | string | No | Serialized JSON array of tool call requests made by the AI in this response. |
| `[Agent] Has Reasoning` | boolean | No | Whether the AI response included reasoning/thinking content. |
| `[Agent] Reasoning Content` | string | No | The AI's reasoning/thinking content (when available and content_mode permits). |
| `[Agent] System Prompt` | string | No | The system prompt used for this LLM call (when content_mode permits). Chunked for long prompts. |
| `[Agent] System Prompt Length` | number | No | Character length of the system prompt. |
| `[Agent] Tool Definitions` | string | No | Normalized JSON array of tool definitions sent to the LLM (when content_mode permits). Each entry contains name, description, and parameters schema. |
| `[Agent] Tool Definitions Count` | number | No | Number of tool definitions in the LLM request. |
| `[Agent] Tool Definitions Hash` | string | No | Stable SHA-256 hash of the normalized tool definitions. Always present regardless of content_mode; enables toolset change detection without exposing schemas. |
| `[Agent] Temperature` | number | No | Temperature parameter used for this LLM call. |
| `[Agent] Max Output Tokens` | number | No | Maximum output tokens configured for this LLM call. |
| `[Agent] Top P` | number | No | Top-p (nucleus sampling) parameter used for this LLM call. |
| `[Agent] Is Streaming` | boolean | No | Whether this response was generated via streaming. |
| `[Agent] Prompt ID` | string | No | Identifier for the prompt template or version used. |
| `[Agent] Was Copied` | boolean | No | Whether the user copied this AI response content. An implicit positive quality signal. |
| `[Agent] Was Cached` | boolean | No | Whether this response was served from a semantic/full-response cache (distinct from token-level prompt caching). |
| `[Agent] Model Tier` | string | No | Model tier classification: 'fast' (GPT-4o-mini, Haiku, Flash), 'standard' (GPT-4o, Sonnet, Pro), or 'reasoning' (o1, o3, DeepSeek-R1). Auto-inferred from model name. |
| `[Agent] Has Attachments` | boolean | No | Whether this AI response includes generated attachments (images, charts, files). |
| `[Agent] Attachment Types` | string[] | No | Distinct attachment types in this AI response. Serialized JSON array. |
| `[Agent] Attachment Count` | number | No | Number of attachments generated by the AI in this response. |
| `[Agent] Total Attachment Size Bytes` | number | No | Total size of all AI-generated attachments in bytes. |
| `[Agent] Attachments` | string | No | Serialized JSON array of AI-generated attachment metadata. |
| `[Agent] Message Labels` | string | No | Serialized JSON array of MessageLabel objects attached to this AI response. |
| `[Agent] Message Label Map` | string | No | Serialized JSON map of label key to value for quick lookup. |

<a id="tool-call-properties"></a>
### Tool Call Properties

Event-specific properties for `[Agent] Tool Call` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Component Type` | string | Yes | Type of component that produced this event: 'user_input', 'llm', 'tool', 'embedding'. |
| `[Agent] Latency Ms` | number | Yes | Total wall-clock latency in milliseconds for this operation. |
| `[Agent] Is Error` | boolean | Yes | Whether this event represents an error condition. |
| `[Agent] Error Message` | string | No | Error message text when Is Error is true. |
| `[Agent] Error Type` | string | No | Exception class name when Is Error is true (e.g., 'ValidationError', 'TimeoutError'). Distinct from Error Message so downstream tooling can group failures by type without parsing the message. |
| `[Agent] Stack Trace` | string | No | Stack trace captured on error when capture_stack_trace=True in AIConfig. Privacy-gated. |
| `[Agent] Error Source` | string | No | Origin of the error: 'provider' (LLM API), 'tool' (tool execution), 'framework' (SDK/pipeline), or 'user' (validation). |
| `[Agent] Locale` | string | No | User locale (e.g., 'en-US'). |
| `[Agent] Span Kind` | string | No | Classification of the span type for OTEL bridge compatibility. |
| `[Amplitude] Session Replay ID` | string | No | Links to Amplitude Session Replay (format: device_id/session_id). Enables one-click navigation from AI session to browser replay. |
| `[Agent] Invocation ID` | string | Yes | Unique identifier for this tool invocation (UUID). Used to link tool calls to parent messages. |
| `[Agent] Tool Name` | string | Yes | Name of the tool/function that was invoked (e.g., 'search_docs', 'web_search'). |
| `[Agent] Tool Type` | string | No | Origin/class of the tool: 'python' (native in-process tool), 'mcp' (tool served by a connected MCP server), 'flow' (sub-agent delegation), or 'unknown'. Lets you segment native vs. MCP-connected tool usage without parsing the tool name or Context. |
| `[Agent] Tool Owner` | string | No | Who owns the tool: 'amplitude' (Amplitude-built/operated — native tools, sub-agents, and Amplitude's own MCP servers) or 'customer' (a server the customer connected, e.g. their own MCP server via the gateway). Segments Amplitude-internal vs. customer-connected tool usage as a first-class property, without overloading [Agent] Tool Type. |
| `[Agent] Tool Success` | boolean | Yes | Whether the tool call completed successfully. |
| `[Agent] Tool Input` | string | No | Serialized JSON of the tool's input arguments. Only sent when content_mode='full'. |
| `[Agent] Tool Output` | string | No | Serialized JSON of the tool's output/return value. Only sent when content_mode='full'. |
| `[Agent] Parent Message ID` | string | No | The message_id of the user message that triggered this tool call. Links the tool call into the event graph. |

<a id="embedding-properties"></a>
### Embedding Properties

Event-specific properties for `[Agent] Embedding` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Component Type` | string | Yes | Type of component that produced this event: 'user_input', 'llm', 'tool', 'embedding'. |
| `[Agent] Model Name` | string | Yes | LLM model identifier (e.g., 'gpt-4o', 'claude-sonnet-4-20250514'). |
| `[Agent] Provider` | string | Yes | LLM provider name (e.g., 'openai', 'anthropic', 'google', 'mistral', 'bedrock'). |
| `[Agent] Latency Ms` | number | Yes | Total wall-clock latency in milliseconds for this operation. |
| `[Agent] Span ID` | string | Yes | Unique identifier for this embedding operation (UUID). |
| `[Agent] Input Tokens` | number | No | Number of input tokens processed by the embedding model. |
| `[Agent] Embedding Dimensions` | number | No | Dimensionality of the output embedding vector. |
| `[Agent] Cost USD` | number | No | Estimated cost in USD for this embedding operation. |

<a id="span-properties"></a>
### Span Properties

Event-specific properties for `[Agent] Span` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Latency Ms` | number | Yes | Total wall-clock latency in milliseconds for this operation. |
| `[Agent] Is Error` | boolean | Yes | Whether this event represents an error condition. |
| `[Agent] Error Message` | string | No | Error message text when Is Error is true. |
| `[Agent] Error Type` | string | No | Exception class name when Is Error is true (e.g., 'ValidationError', 'TimeoutError'). Distinct from Error Message so downstream tooling can group failures by type without parsing the message. |
| `[Agent] Stack Trace` | string | No | Stack trace captured on error when capture_stack_trace=True in AIConfig. Privacy-gated. |
| `[Agent] Error Source` | string | No | Origin of the error: 'provider' (LLM API), 'tool' (tool execution), 'framework' (SDK/pipeline), or 'user' (validation). |
| `[Agent] Span ID` | string | Yes | Unique identifier for this span (UUID). |
| `[Agent] Span Name` | string | Yes | Name of the operation (e.g., 'rag_pipeline', 'vector_search', 'rerank'). |
| `[Agent] Parent Span ID` | string | No | Span ID of the parent span for nested pipeline steps. |
| `[Agent] Input State` | string | No | Serialized JSON of the span's input state. Only sent when content_mode='full'. |
| `[Agent] Output State` | string | No | Serialized JSON of the span's output state. Only sent when content_mode='full'. |

<a id="session-end-properties"></a>
### Session End Properties

Event-specific properties for `[Agent] Session End` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Enrichments` | string | No | Serialized JSON of SessionEnrichments (topic classifications, rubric scores, outcome, flags). Attached when enrichments are provided at session close. |
| `[Agent] Abandonment Turn` | number | No | Turn ID of the last user message that received an AI response before the user left. Low values (e.g., 1) strongly signal first-response dissatisfaction. |
| `[Agent] Session Idle Timeout Minutes` | number | No | Custom idle timeout for this session (default 30 min). Tells the server how long to wait before auto-closing. |

<a id="session-enrichment-properties"></a>
### Session Enrichment Properties

Event-specific properties for `[Agent] Session Enrichment` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Enrichments` | string | Yes | Serialized JSON of SessionEnrichments: topic_classifications, rubrics, overall_outcome, quality_score, sentiment_score, boolean flags, agent chain metadata, and message labels. |

<a id="score-properties"></a>
### Score Properties

Event-specific properties for `[Agent] Score` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Score Name` | string | Yes | Name of the score (e.g., 'user-feedback', 'task_completion', 'accuracy', 'groundedness'). |
| `[Agent] Score Value` | number | Yes | Numeric score value. Binary (0/1), continuous (0.0-1.0), or rating scale (1-5). |
| `[Agent] Target ID` | string | Yes | The message_id or session_id being scored. |
| `[Agent] Target Type` | string | Yes | What is being scored: 'message' or 'session'. |
| `[Agent] Evaluation Source` | string | Yes | Source of the evaluation: 'user' (end-user feedback), 'ai' (automated/server pipeline), or 'reviewer' (human expert). |
| `[Agent] Comment` | string | No | Optional text explanation for the score (respects content_mode). |
| `[Agent] Taxonomy Version` | string | No | Which taxonomy config version produced this enrichment (from ai_category_config.config_version_id). |
| `[Agent] Evaluated At` | number | No | Epoch milliseconds when this enrichment/evaluation was computed. |
| `[Agent] Evaluator Model` | string | No | LLM model identifier used to produce this evaluator output. |
| `[Agent] Score Label` | string | No | Direction-neutral magnitude label derived from score value. Default 5-tier: very_high (>=0.8), high (>=0.6), moderate (>=0.4), low (>=0.2), very_low (>=0.0). Server-side only. |

<a id="server-side-session-record-properties"></a>
### Server-Side: Session Record Properties

`[Agent] Session Record` is emitted automatically by the server-side enrichment pipeline — do not send this event from your code.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Session ID` | string | Yes | Unique session identifier. All events in one conversation share the same session ID. |
| `[Agent] Agent ID` | string | Yes | Identifies which AI agent handled the interaction (e.g., 'support-bot', 'houston'). |
| `[Agent] Org ID` | string | Yes | The Amplitude organization ID owning the project where this event is tracked. |
| `[Agent] Customer Org ID` | string | No | Organization ID for multi-tenant platforms. Enables account-level group analytics. |
| `[Agent] Evaluation Source` | string | Yes | Source of the evaluation: 'user' (end-user feedback), 'ai' (automated/server pipeline), or 'reviewer' (human expert). |
| `[Agent] Taxonomy Version` | string | Yes | Which taxonomy config version produced this enrichment (from ai_category_config.config_version_id). |
| `[Agent] Evaluated At` | number | Yes | Epoch milliseconds when this enrichment/evaluation was computed. |
| `[Agent] Turn Count` | number | Yes | Number of conversation turns in this session. |
| `[Agent] Session Total Tokens` | number | No | Total LLM tokens consumed across all turns in this session. |
| `[Agent] Session Avg Latency Ms` | number | No | Average AI response latency in milliseconds across the session. |
| `[Agent] Request Complexity` | string | No | Complexity classification of the user's request: 'simple', 'moderate', 'complex', or 'ambiguous'. |
| `[Agent] Has Task Failure` | boolean | Yes | Whether the agent failed to complete the user's request. |
| `[Agent] Has Negative Feedback` | boolean | Yes | Whether the user expressed dissatisfaction during the session. |
| `[Agent] Has Technical Failure` | boolean | Yes | Whether technical errors occurred (tool timeouts, API failures, etc.). |
| `[Agent] Has Data Quality Issues` | boolean | Yes | Whether the AI output had data quality problems (wrong data, hallucinations, etc.). |
| `[Agent] Models Used` | string[] | No | LLM models used in this session. JSON array of strings. |
| `[Agent] Root Agent Name` | string | No | Entry-point agent in multi-agent flows. |
| `[Agent] Agent Chain Depth` | number | No | Number of agents in the delegation chain. |
| `[Agent] Task Failure Type` | string | No | Specific failure type when has_task_failure is true (e.g., 'wrong_answer', 'unable_to_complete'). |
| `[Agent] Technical Error Count` | number | No | Count of technical errors that occurred during the session. |
| `[Agent] Error Categories` | string[] | No | Categorized error types (e.g., 'chart_not_found', 'timeout'). JSON array of strings. |
| `[Agent] User Friction` | string[] | No | Detected user friction patterns (e.g., 'retry_storm', 'clarification_loop', 'early_abandonment'). JSON array of strings. |
| `[Agent] Session Cost USD` | number | No | Total LLM cost in USD for this AI session (aggregated from per-message costs). |
| `[Agent] Close Reason` | string | No | Why this session record fired: 'explicit_close' (the agent called session.close()) or 'timeout' (idle/max-duration/upload). Distinguishes a terminal record from a point-in-time snapshot. |
| `[Agent] Quality Score` | number | No | Overall quality score (0.0-1.0) computed by the enrichment pipeline for this session. |
| `[Agent] Sentiment Score` | number | No | User sentiment score (0.0-1.0) inferred from the conversation by the enrichment pipeline. |
| `[Agent] Task Failure Reason` | string | No | Explanation of why the task failed when has_task_failure is true (e.g., 'chart data source unavailable'). |
| `[Agent] Agent Chain` | string[] | No | Serialized JSON array of agent IDs representing the delegation chain in multi-agent flows. |
| `[Agent] Project ID` | string | No | Amplitude project ID that owns the AI session being evaluated. |
| `[Agent] Has User Feedback` | boolean | Yes | Whether the session received explicit user feedback (thumbs up/down, rating). |
| `[Agent] User Score` | number | No | Aggregate user feedback score for the session (0.0-1.0). Present only when has_user_feedback is true. |
| `[Agent] Agent Version` | string | No | Agent code version (e.g., 'v4.2'). Enables version-over-version quality comparison. |
| `[Agent] Agent Description` | string | No | Human-readable description of the agent's purpose (e.g., 'Handles user chat requests via OpenAI GPT-4o'). Enables observability-driven agent registry from event streams. |
| `[Agent] Context` | string | No | Serialized JSON dict of arbitrary segmentation dimensions (experiment_variant, surface, feature_flag, prompt_revision, etc.). |
| `[Agent] Task Completed` | string | No | OOTB detector result: 'True' if agent completed user's request, 'False' otherwise. |
| `[Agent] Task Completed Rationale` | string | No | Brief rationale for the task completion determination. |
| `[Agent] Task Completed Evidence` | string | No | Supporting evidence for the task completion determination. |
| `[Agent] Response Quality` | string | No | OOTB detector result: 'True' if response was accurate/clear/helpful, 'False' otherwise. |
| `[Agent] Response Quality Rationale` | string | No | Brief rationale for the response quality determination. |
| `[Agent] Response Quality Evidence` | string | No | Supporting evidence for the response quality determination. |
| `[Agent] Session Outcome` | string | No | OOTB classifier result for how the session ended (e.g., 'Response Provided', 'Unable to Complete', 'Escalated'). |
| `[Agent] Session Outcome Rationale` | string | No | Brief rationale for the session outcome classification. |
| `[Agent] Session Safety` | string | No | OOTB classifier result for session safety (e.g., 'Normal', 'Off Topic', 'Prompt Injection', 'Abuse'). |
| `[Agent] Session Safety Rationale` | string | No | Brief rationale for the session safety classification. |
| `[Agent] User Intent` | string | No | OOTB classifier result for user's primary intent (e.g., 'Information Request', 'Task Execution', 'Content Creation'). |
| `[Agent] User Intent Rationale` | string | No | Brief rationale for the user intent classification. |
| `[Agent] Has User Friction` | boolean | No | OOTB detector result: whether conversation exhibited user friction (retry storms, clarification loops, etc.). |
| `[Agent] User Friction Rationale` | string | No | Brief rationale for user friction detection. |
| `[Agent] Detected User Friction` | string[] | No | Specific user friction patterns detected (e.g., 'retry_storm', 'tool_cascade_fail'). JSON array. |
| `[Agent] Detected Data Quality Issues` | string[] | No | Specific data quality issues detected. JSON array. |

<a id="server-side-topic-classification-properties"></a>
### Server-Side: Topic Classification Properties

`[Agent] Topic Classification` is emitted automatically by the server-side enrichment pipeline — do not send this event from your code.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Session ID` | string | Yes | Unique session identifier. All events in one conversation share the same session ID. |
| `[Agent] Agent ID` | string | Yes | Identifies which AI agent handled the interaction (e.g., 'support-bot', 'houston'). |
| `[Agent] Org ID` | string | Yes | The Amplitude organization ID owning the project where this event is tracked. |
| `[Agent] Evaluation Source` | string | Yes | Source of the evaluation: 'user' (end-user feedback), 'ai' (automated/server pipeline), or 'reviewer' (human expert). |
| `[Agent] Taxonomy Version` | string | Yes | Which taxonomy config version produced this enrichment (from ai_category_config.config_version_id). |
| `[Agent] Evaluated At` | number | Yes | Epoch milliseconds when this enrichment/evaluation was computed. |
| `[Agent] Topic` | string | Yes | Which topic model this classification is for (e.g., 'product_area', 'query_intent', 'error_domain'). |
| `[Agent] Selection Mode` | string | Yes | Whether this topic model uses 'single' (MECE) or 'multiple' (multi-label) selection. |
| `[Agent] Primary Label` | string | No | Primary classification value (e.g., 'charts', 'billing_issues'). |
| `[Agent] Secondary Label` | string[] | No | Secondary classifications for multi-label topics. JSON array of strings. |
| `[Agent] Subcategories` | string[] | No | Subcategories for finer classification within the primary topic (e.g., 'TREND_ANALYSIS', 'WRONG_EVENT'). JSON array of strings. |
| `[Agent] Evaluator Model` | string | No | LLM model identifier used to produce this evaluator output. |

<a id="agent-evaluator-result-properties"></a>
### [Agent] Evaluator Result Properties

Event-specific properties for `[Agent] Evaluator Result` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Org ID` | string | Yes | The Amplitude organization ID owning the project where this event is tracked. |
| `[Agent] Evaluation Source` | string | Yes | Source of the evaluation: 'user' (end-user feedback), 'ai' (automated/server pipeline), or 'reviewer' (human expert). |
| `[Agent] Evaluator Version` | string | Yes | Config version ID that produced this result. |
| `[Agent] Evaluated At` | number | Yes | Epoch milliseconds when this enrichment/evaluation was computed. |
| `[Agent] Evaluator Name` | string | Yes | Human-readable evaluator name (primary group-by for users). |
| `[Agent] Evaluator Output Type` | string | Yes | Discriminator for the evaluator kind: 'classification', 'score', or 'binary'. |
| `[Agent] Selection Mode` | string | No | Whether this evaluator uses 'single' or 'multiple' selection. Classification only. |
| `[Agent] Primary Label` | string | No | Primary classification label. Classification only. |
| `[Agent] Secondary Label` | string[] | No | Secondary labels for multi-label evaluators. Classification only. |
| `[Agent] Subcategories` | string[] | No | Finer classification within the primary label. Classification only. |
| `[Agent] Binary Label` | boolean | No | Whether the condition was detected. Binary only. |
| `[Agent] Binary Value` | number | No | Numeric mirror of Binary Label (1=True, 0=False) for uniform charting. Binary only. |
| `[Agent] Score Value` | number | No | Numeric score assigned by the evaluator. Score only. |
| `[Agent] Score Label` | string | No | Human-readable tier (e.g., 'good', 'poor'). Score only. |
| `[Agent] Target ID` | string | No | ID of the scored entity (session_id). Score only. |
| `[Agent] Target Type` | string | No | Type of scored entity (e.g., 'session'). Score only. |
| `[Agent] Improvement Opportunities` | string | No | Suggestions for how the agent could improve. Score only. |
| `[Agent] Rationale` | string | No | LLM-generated explanation for the result. |
| `[Agent] Evidence` | string | No | Supporting evidence (quotes, observations) for the result. |
| `[Agent] Evaluator Model` | string | No | LLM model identifier used to produce this evaluator output. |
| `[Agent] Evaluator Enrichment Cost USD` | number | No | Cost in USD of running this specific evaluator's LLM inference. Customer-attributable enrichment cost for this evaluator; distinct from the session's own LLM cost ([Agent] Session Cost USD). |
| `[Agent] Turn Count` | number | No | Session dimension: number of conversation turns in this session. |
| `[Agent] Session Total Tokens` | number | No | Session dimension: total LLM tokens consumed across all turns in this session. |
| `[Agent] Session Avg Latency Ms` | number | No | Session dimension: average AI response latency in milliseconds across the session. |
| `[Agent] Session Cost USD` | number | No | Session dimension: total LLM cost in USD for this AI session. |
| `[Agent] Has Technical Failure` | boolean | No | Session dimension: whether technical errors occurred during the session. |
| `[Agent] Has Negative Feedback` | boolean | No | Session dimension: whether the user expressed dissatisfaction during the session. |
| `[Agent] Has Data Quality Issues` | boolean | No | Session dimension: whether the AI output had data quality problems. |
| `[Agent] Has User Feedback` | boolean | No | Session dimension: whether the session received explicit user feedback. |
| `[Agent] Technical Error Count` | number | No | Session dimension: count of technical errors during the session. |
| `[Agent] Models Used` | string[] | No | Session dimension: LLM models used in this session. JSON array of strings. |
| `[Agent] Project ID` | string | No | Session dimension: Amplitude project ID that owns the AI session. |
| `[Agent] Root Agent Name` | string | No | Session dimension: entry-point agent in multi-agent flows. |
| `[Agent] Agent Chain Depth` | number | No | Session dimension: number of agents in the delegation chain. |
| `[Agent] User Score` | number | No | Session dimension: aggregate user feedback score for the session (0.0-1.0). |
| `[Agent] Close Reason` | string | No | Session dimension: why the session record fired ('explicit_close' or 'timeout'). |
| `[Agent] Topic Summary` | string | No | Session dimension: concise one-sentence factual summary of what the user was trying to accomplish. Produced by the OOTB batched eval pass-1 at zero marginal cost. |

<a id="agent-cluster-assignment-properties"></a>
### [Agent] Cluster Assignment Properties

Event-specific properties for `[Agent] Cluster Assignment` (in addition to common properties above).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `[Agent] Cluster Label` | string | No | Human-readable label summarizing the topic of the assigned cluster. |
| `[Agent] Cluster ID` | string | No | Internal numeric cluster identifier within the clustering run. |
| `[Agent] Stable Cluster ID` | string | No | Cross-run stable identifier for this topic. Persists across re-clustering runs via centroid similarity matching (Hungarian algorithm). |
| `[Agent] Distance to Centroid` | number | No | Cosine distance from the session embedding to the cluster centroid. Lower is more central. |
| `[Agent] Is Noise` | boolean | No | True if HDBSCAN classified this session as noise (not belonging to any cluster). |
| `[Agent] Clustering Run ID` | string | No | ID of the clustering run that produced this assignment. |
<!-- END EVENT PROPERTY REFERENCE -->

<a id="license"></a>
## License

[MIT](https://github.com/amplitude/Amplitude/blob/master/langley/amplitude_ai/LICENSE)

---

> **About this README.** The long-form SDK reference previously hosted here moved to the [canonical docs page](https://amplitude.com/docs/sdks/agent-analytics/sdk) so npm, PyPI, and the in-product docs surface stay aligned. The full instrumentation guide consumed by AI coding agents is preserved at [`amplitude-ai.md`](https://github.com/amplitude/Amplitude/blob/master/langley/amplitude_ai/amplitude-ai.md) in this repo.
