amplitude-ai 1.11.0

Agent analytics for Amplitude

amplitude-ai

Agent analytics for Amplitude. 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.

📘 Documentation

The canonical SDK reference lives in Amplitude Docs:

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.

Install

pip install amplitude-ai

Quick start

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 for the rest.

Provider wrappers

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

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

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

Fan-out LLM (parallel child calls)

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

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 for details.

Auto-instrument with an AI coding agent

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), scans your project, discovers your LLM call sites, and instruments everything — provider wrappers, sessions, multi-agent delegation, tools, scoring, and a verification test.

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.

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.

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.

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:

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())

Event Property Reference

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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

License

MIT

---

About this README. The long-form SDK reference previously hosted here moved to the canonical docs page 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 in this repo.