Agent Analytics taxonomy

Agent Analytics uses a managed event taxonomy. Every event name and property is prefixed with [Agent] so agent data stays clearly separated from your product events while living in the same project. Because they share the project and the same user ID, you can chart, segment, and build cohorts across agent and product behavior.

This page is the reference for every event and property Agent Analytics produces. Events come from two producers:

• Your SDK instrumentation emits events in real time as your agent runs: User Message, AI Response, Tool Call, Span, Embedding, Session End, Session Enrichment, and Score.
• Amplitude's enrichment pipeline emits events after a session closes: Session Record and Evaluator Result. Amplitude never emits Score events; Scores always come from your application.

Data hierarchy

Agent Analytics models each agent interaction as a hierarchy:

An agent is a dimension on every event: Every event carries [Agent] Agent ID property, and in multi-agent systems child agents carry a parent reference. A single session can involve multiple agents: the session-level rollups record [Agent] Root Agent Name (the agent that started the session) and [Agent] Agent Chain Depth (how deep the delegation chain went). To compare agents, group any chart by [Agent] Agent ID. To analyze multi-agent sessions, filter Session Records with chain depth greater than 1.

Agent sessions are not analytics sessions: [Agent] Session ID identifies a unit of agent work and is set by your instrumentation (use the thread, ticket, call, or run ID your app already has). Amplitude's standard session ID identifies an app or web visit and powers Session Replay. One analytics session can contain several agent sessions. Refer to the setup page for how to link the two for Session Replay.

Event inventory

Deprecated: [Agent] Topic Classification no longer fires. Topic and classification outputs now land on [Agent] Evaluator Result (classification type) and in [Agent] Topic Summary on the Session Record. If you built charts on Topic Classification, migrate them to Evaluator Result.

Signals: where quality lands

Amplitude runs a fixed set of quality signals on every closed session. Signal results land as properties on the [Agent] Session Record event, one record per session, each signal with its own result, rationale, and (where applicable) evidence property. Signals do not produce separate events.

Notes on signal semantics:

• The six LLM-based signals run as a single batched judge call per closed session (data quality is code-based, no LLM). Each LLM result carries a label, a rationale, and a supporting evidence quote. The judge is instructed to be conservative: signals are directional indicators, not ground truth.
• Task Completed and Response Quality are booleans, not numeric scores. To trend them, chart the share of sessions where the value is true. Task Completed credits recovery when early errors are followed by success and ignores tone; Response Quality judges the text (accurate, clear, well-structured) independent of task outcome.
• Negative feedback and user friction are related but distinct: negative feedback detects explicit dissatisfaction in what the user wrote; user friction detects behavioral patterns such as retry storms and clarification loops even when the user never complains.
• Override rule: if your application sends an [Agent] Score event with [Agent] Score Name = user-feedback for a session, that explicit feedback overrides the detected Negative Feedback signal for that session. Use this when you have a real thumbs control in your product.
• Signals run in every privacy mode, but their value depends on what content is available. In metadata_only, signals that read conversation text have little to work with; expect low-information results. Refer to the setup page's privacy matrix.

Classification values:

• [Agent] User Intent: Information Request, Analysis & Synthesis, Task Execution, Content Creation, Advice & Recommendation, Off-Topic / Social. Classified by the dominant intent across the session, not the greeting.
• [Agent] Session Safety: Normal (default), Off Topic, Prompt Injection, Abuse, Probing, Unsafe Output (agent produced harmful content), Data Leak (agent exposed PII, credentials, or internal info).

Common properties

These appear on all or most SDK events:

Event property reference

[Agent] User Message

[Agent] AI Response

[Agent] Tool Call

[Agent] Span and [Agent] Embedding

Spans carry [Agent] Span Name, [Agent] Latency Ms, [Agent] Input State, [Agent] Output State, [Agent] Is Error, optional parent span nesting, and any properties you attach. Embeddings carry model, provider, token, and cost properties like AI Response. Note that Embedding events do not participate in the session pipeline: they don't reset the idle clock and their costs are not included in Session Cost USD.

[Agent] Session End

Refer to How sessions close for the lifecycle and timeout rules.

[Agent] Score

Your application's feedback event. Amplitude never emits Scores; every Score in your project came from your code through score() or trackScore().

[Agent] Session Enrichment

Your own session-level labels: quality scores, outcomes, topics computed on your infrastructure. Sent through trackSessionEnrichment() or setEnrichments(). Works in any privacy mode; it is the primary data path in customer_enriched mode.

[Agent] Session Record

Emitted once per session after it closes. This is the workhorse event for quality analysis: one row per session carrying every signal result plus rollups. There is exactly one Session Record per session.

Session identity and rollups:

Signal results (refer to the signals table above for semantics):

[Agent] Evaluator Result

Emitted once per active custom evaluator per closed session. Custom evaluators are the ones you define and calibrate in the Amplitude UI; the built-in signals do not produce Evaluator Result events.

Evaluator identity and output:

Session dimensions, echoed onto every Evaluator Result so you can segment evaluator outcomes without joining to the Session Record: [Agent] Root Agent Name, [Agent] Agent Chain Depth, [Agent] Close Reason, [Agent] Turn Count, [Agent] Session Total Tokens, [Agent] Session Cost USD, [Agent] Session Avg Latency Ms, [Agent] Models Used, [Agent] Technical Error Count, [Agent] Topic Summary, the Has flags, and [Agent] User Score when present.

How cost is calculated

[Agent] Cost USD is computed exactly once, in the SDK, at the moment the event is tracked. Nothing downstream recomputes it: the server reads the value verbatim and sums it. Automatic pricing multiplies the event's token counts against a continuously maintained open-source model price catalog (Pydantic's genai-prices project, bundled with the SDK), so standard model identifiers matter. A cost you pass explicitly always wins over automatic pricing and is emitted as given, including zero.

What prices, and what doesn't:

• Cache-aware blending. With cache token breakdowns, uncached input, cache reads, and cache writes are each priced at their own rate; without them, cache-heavy workloads can overestimate by 2 to 5x.
• Unpriceable models. The SDK can't automatically price nonstandard names, gateway aliases (for example openrouter/auto), or fine-tuned ft: model names. It omits the property and logs a warning once per model. For fine-tuned or custom models, pass the cost yourself.
• Pricing freshness. Prices ship with the SDK's bundled catalog, and the SDK doesn't fetch updates by default. For newly released models, call enableLivePriceUpdates() (Node) or enable_live_price_updates() (Python) at startup to refresh prices hourly. If a refresh fails, the SDK continues to use its bundled catalog. Live updates don't reprice existing events. Refer to Keep pricing data current for configuration details.

If you send events directly instead of through the SDK, provide the cost yourself: [Agent] Cost USD for HTTP events or gen_ai.usage.cost for OTLP spans. Amplitude stores the value you send and doesn't reprice direct events because they may not include all inputs needed for an accurate estimate.

[Agent] Session Cost USD on the Session Record is the sum of [Agent] Cost USD across the session's [Agent] AI Response events, and it is all-or-nothing: if any event with token usage carries no cost (an unpriced model, for instance), the property is omitted from the Session Record entirely rather than reporting a partial total. Embedding events do not participate in the session pipeline, so embedding costs never contribute. The value is accumulated at ingest and fixed when the session is enriched; events arriving after that do not change it.

Judge costs are separate, structurally. [Agent] Evaluator Enrichment Cost USD appears on [Agent] Evaluator Result events for evaluators you define and can never leak into Session Cost USD. The cost of Amplitude's built-in signals is not reported anywhere; it's included in the product.

Everything is USD end to end, with no currency conversion anywhere. Treat your provider's bill as the financial source of truth; heavily cached or batch-discounted workloads may diverge. Agent Analytics cost data is the analytical view: per-agent, per-user, per-topic attribution your bill can't give you.

Managed schema

The [Agent] taxonomy is managed by Amplitude: property names, types, and registration in your data catalog are handled for you. To add your own dimensions, use [Agent] Context (a JSON property present on SDK events and echoed onto the Session Record) or emit standard product events from your tools; do not add unregistered flat properties to [Agent] events, as they may not be queryable in charts.