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.

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 during the beta, 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

[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. Nonstandard names, gateway aliases (for example openrouter/auto), and fine-tuned ft: model names cannot be priced automatically. From the current SDK fix onward, the property is omitted and a warning logs once per model; releases before it recorded $0 silently. For fine-tuned or custom models, pass the cost yourself.
• Pricing freshness. Prices ship with the SDK's bundled catalog; newly released models may be unpriced until it updates. The SDK can optionally fetch live price updates hourly, and already-emitted events are never retroactively corrected.

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

How sessions close

Enrichment (Session Record and Evaluator Results) runs only after a session closes. A session closes one of two ways, recorded in [Agent] Close Reason:

1. Explicit close. Your app calls trackSessionEnd() or lets session.run() complete, marking the session eligible for enrichment. Closing is a completion marker, not a hard lock: later events with the same session ID are still accepted and stored, but enrichment runs once per session, so late turns are not reflected in the Session Record or its rollups.
2. Idle timeout. If you never close explicitly, the server closes the session after 30 minutes of inactivity by default, measured from the last agent event received. Override with the idle timeout parameter (for example 240 minutes for jobs with long natural gaps), or set it to -1 to raise the window to its 90-day maximum and rely on explicit closes. Sessions without an override are also closed after a maximum duration of 24 hours regardless of activity; that close reports as timeout too. A Session End arriving after a timeout has already closed the session does not change the recorded Close Reason.

If Session Records aren't appearing, the most common cause is a session that never closed: no Session End event and continuous activity resetting the idle timer.

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.