On this page

Agent Analytics taxonomy

Early Access

This feature is in Early Access. During this time, aspects of the functionality may still be developed, and this documentation may not always be up to date. If you have any questions, contact Amplitude Support.

This page is the reference for the data Agent Analytics produces: every [Agent] event, the properties on the enrichment events, and the default signals. To read these results in the UI, go to Analyze agent results. To emit the events from your code, go to the Agent Analytics SDK.

The taxonomy is configurable and still evolving during Open Beta. Treat the lists below as the default shape, and confirm the live set against your own event stream.

Data hierarchy

Agent Analytics models each agent interaction as a hierarchy:

  • Session: One job a user hands the agent, from start to finish. Amplitude identifies a session with the [Agent] Session ID property. The agent session differs from Amplitude's standard-analytics session ($session_id), which is the user's app or web visit.
  • Turn: A single back-and-forth exchange within a session: a user message, the agent's tool calls, and the AI response.
  • Span: A sub-turn step, such as a tool call, vector search, rerank, or guardrail.

Every user message, AI response, and tool call lands as an independent Amplitude event, so you can use agent data in funnels, cohorts, and retention charts without decomposing a trace first.

Event inventory

Agent Analytics produces these events. Your SDK instrumentation produces the first seven — either through direct SDK calls or through OTEL spans when enable_otel() / enableOtel() is active (the SDK maps spans to events automatically). The server enrichment pipeline produces the rest after a session closes.

EventProducerSDK method
[Agent] User MessageSDKtrack_user_message()
[Agent] AI ResponseSDKtrack_ai_message()
[Agent] Tool CallSDKtrack_tool_call()
[Agent] EmbeddingSDKtrack_embedding()
[Agent] SpanSDKtrack_span()
[Agent] Session EndSDKtrack_session_end()
[Agent] Session EnrichmentSDKtrack_session_enrichment()
[Agent] Session RecordServer enrichment pipelineInternal
[Agent] Evaluator ResultServer enrichment pipelineInternal
[Agent] ScoreSDK, or server for feedbackscore()

SDK events

Your instrumentation produces these events as the agent runs. The [Agent] AI Response event carries the per-response model, provider, token, latency, and cost properties.

  • [Agent] User Message: a message the user sends to the agent.
  • [Agent] AI Response: the agent's response, with model, provider, tokens, latency, and cost.
  • [Agent] Tool Call: a function or tool the agent invokes.
  • [Agent] Embedding: an embedding or vector-search step.
  • [Agent] Span: any other pipeline step, such as a rerank or guardrail.
  • [Agent] Session End: marks the end of a session.
  • [Agent] Session Enrichment: your own session labels, sent in customer_enriched privacy mode.

All SDK event properties are prefixed with [Agent], except [Amplitude] Session Replay ID. The tables below list the properties the SDK emits, grouped by event. Optional properties are populated when the relevant data is available and the privacy mode permits it.

Common properties

These properties can appear on any SDK event.

PropertyTypeRequiredDescription
[Agent] Session IDstringYesSession identifier. Every event in one agent session shares it.
[Agent] Component TypestringYesComponent that produced the event: user_input, llm, tool, or embedding.
[Agent] SDK VersionstringYesVersion of the SDK that produced the event.
[Agent] RuntimestringYesSDK runtime: node or python.
[Agent] Trace IDstringNoGroups events into one turn in the trace viewer. Events without it fall back to the session ID.
[Agent] Turn IDnumberNoMonotonically increasing counter that orders events within a session.
[Agent] Agent IDstringNoWhich agent handled the interaction (for example, support-bot).
[Agent] Parent Agent IDstringNoIn multi-agent delegation, the agent that delegated to this one.
[Agent] Customer Org IDstringNoTenant organization ID for multi-tenant platforms. Enables account-level group analytics.
[Agent] Agent VersionstringNoAgent code version. Enables version-over-version quality comparison.
[Agent] Agent DescriptionstringNoHuman-readable description of the agent's purpose.
[Agent] ContextstringNoSerialized JSON of your segmentation dimensions. Refer to Add segmentation with context.
[Agent] EnvstringNoDeployment environment: production, staging, or dev.
[Agent] Message SourcestringNouser for end-user input, or agent for inter-agent delegation. Provider wrappers set it automatically.
[Agent] LocalestringNoUser locale, such as en-US.
[Amplitude] Session Replay IDstringNoLinks to Session Replay, in device_id/session_id form.

Deployment and OTEL metadata

These optional properties can appear on any SDK event when configured.

PropertyTypeDescription
[Agent] Git SHAstringCommit SHA of the deployed build. Use for correlating agent behavior with specific deploys.
[Agent] Git RefstringBranch or tag name (for example, main or v2.1.0).
[Agent] Git RepostringRepository identifier (for example, org/repo).
[Agent] Tagsstring[]Custom string tags for ad-hoc grouping (for example, ["beta", "internal"]).
[Agent] Span KindstringOTEL span routing hint when OTEL is enabled. Maps the span to an event type (tool, llm, agent, span).

[Agent] User Message properties

In addition to the common properties.

PropertyTypeRequiredDescription
[Agent] Message IDstringYesUnique ID for this message. Links scores and tool calls back to the message.
[Agent] Is RegenerationbooleanNoWhether the user asked the AI to regenerate a previous response. A negative quality signal.
[Agent] Is EditbooleanNoWhether the user edited a previous message and resubmitted.
[Agent] Edited Message IDstringNoThe Message ID of the original message that was edited.
[Agent] Has AttachmentsbooleanNoWhether the message includes file attachments.
[Agent] Attachment Typesstring[]NoDistinct attachment types (for example, pdf, image).
[Agent] Attachment CountnumberNoNumber of attachments on the message.
[Agent] Total Attachment Size BytesnumberNoTotal size of all attachments, in bytes.
[Agent] AttachmentsstringNoSerialized JSON of attachment metadata (type, name, size). Metadata only, never file content.
[Agent] Message LabelsstringNoSerialized JSON of label objects. Used for routing tags, classifier output, or business context.
[Agent] Message SourcestringNouser for real end-user input, or agent for a parent agent's instructions to a child.

[Agent] AI Response properties

In addition to the common properties.

PropertyTypeRequiredDescription
[Agent] Message IDstringYesUnique ID for this response.
[Agent] Model NamestringYesModel identifier (for example, gpt-4o, claude-sonnet-4-20250514).
[Agent] ProviderstringYesProvider name (for example, openai, anthropic, google, mistral, bedrock).
[Agent] Latency MsnumberYesTotal wall-clock latency for the call, in milliseconds.
[Agent] Is ErrorbooleanYesWhether the response represents an error.
[Agent] Error MessagestringNoError text when Is Error is true.
[Agent] Error TypestringNoException class name when Is Error is true. Lets tooling group failures by type.
[Agent] TTFB MsnumberNoTime to first token, in milliseconds. Measures perceived responsiveness for streaming.
[Agent] Input TokensnumberNoPrompt tokens consumed. Cache-inclusive (refer to Manage cost and tokens).
[Agent] Output TokensnumberNoCompletion tokens generated.
[Agent] Total TokensnumberNoInput plus output tokens.
[Agent] Reasoning TokensnumberNoTokens spent on reasoning or thinking (o1, o3, extended-thinking models).
[Agent] Cache Read TokensnumberNoInput tokens served from the provider's prompt cache, at a cheaper rate.
[Agent] Cache Creation TokensnumberNoInput tokens that created new prompt-cache entries.
[Agent] Cost USDnumberNoEstimated cost in USD. Cache-aware when cache token counts are provided.
[Agent] Finish ReasonstringNoWhy the model stopped: stop, end_turn, tool_use, length, content_filter, and so on.
[Agent] Is StreamingbooleanNoWhether the response streamed.
[Agent] Model TierstringNoAuto-inferred tier: fast, standard, or reasoning.
[Agent] Was CachedbooleanNoWhether the response was served from a semantic or full-response cache.
[Agent] Was CopiedbooleanNoWhether the user copied the response. An implicit positive quality signal.
[Agent] Has ReasoningbooleanNoWhether the response included reasoning content.
[Agent] Reasoning ContentstringNoThe reasoning content, when available and the privacy mode permits.
[Agent] System PromptstringNoThe system prompt used, when the privacy mode permits.
[Agent] System Prompt LengthnumberNoCharacter length of the system prompt.
[Agent] Tool CallsstringNoSerialized JSON of tool-call requests the AI made in this response.
[Agent] Tool DefinitionsstringNoNormalized JSON of the tool definitions sent to the LLM, when the privacy mode permits.
[Agent] Tool Definitions CountnumberNoNumber of tool definitions in the request.
[Agent] Tool Definitions HashstringNoStable hash of the tool definitions. Always present; enables toolset-change detection without exposing schemas.
[Agent] TemperaturenumberNoTemperature parameter used for the call.
[Agent] Max Output TokensnumberNoMaximum output tokens configured for the call.
[Agent] Top PnumberNoTop-p (nucleus sampling) parameter used for the call.
[Agent] Prompt IDstringNoIdentifier for the prompt template or version used.
[Agent] Message LabelsstringNoSerialized JSON of label objects attached to the response.

[Agent] Tool Call properties

In addition to the common properties.

PropertyTypeRequiredDescription
[Agent] Invocation IDstringYesUnique ID for this tool invocation. Links tool calls to parent messages.
[Agent] Tool NamestringYesName of the tool that was invoked (for example, search_docs).
[Agent] Tool SuccessbooleanYesWhether the tool call completed successfully.
[Agent] Latency MsnumberYesTotal wall-clock latency for the call, in milliseconds.
[Agent] Is ErrorbooleanYesWhether the call represents an error.
[Agent] Tool TypestringNoOrigin of the tool: python (native in-process), mcp (served by a connected MCP server), flow (sub-agent delegation), or unknown.
[Agent] Tool OwnerstringNoWho owns the tool: amplitude (Amplitude-built or operated) or customer (a server the customer connected).
[Agent] Tool InputstringNoSerialized JSON of the tool's input arguments. Sent only in full privacy mode.
[Agent] Tool OutputstringNoSerialized JSON of the tool's return value. Sent only in full privacy mode.
[Agent] Parent Message IDstringNoThe Message ID of the user message that triggered the tool call.

[Agent] Embedding properties

In addition to the common properties.

PropertyTypeRequiredDescription
[Agent] Span IDstringYesUnique ID for the embedding operation.
[Agent] Model NamestringYesEmbedding model identifier.
[Agent] ProviderstringYesProvider name.
[Agent] Latency MsnumberYesWall-clock latency for the operation, in milliseconds.
[Agent] Input TokensnumberNoInput tokens processed by the embedding model.
[Agent] Embedding DimensionsnumberNoDimensionality of the output vector.
[Agent] Cost USDnumberNoEstimated cost in USD. Auto-calculated from input tokens; pass a value to override.

[Agent] Span properties

In addition to the common properties.

PropertyTypeRequiredDescription
[Agent] Span IDstringYesUnique ID for the span.
[Agent] Span NamestringYesName of the operation (for example, rag_pipeline, vector_search).
[Agent] Latency MsnumberYesWall-clock latency for the span, in milliseconds.
[Agent] Is ErrorbooleanYesWhether the span represents an error.
[Agent] Parent Span IDstringNoSpan ID of the parent span, for nested pipeline steps.
[Agent] Input StatestringNoSerialized JSON of the span's input state. Sent only in full privacy mode.
[Agent] Output StatestringNoSerialized JSON of the span's output state. Sent only in full privacy mode.

[Agent] Session End properties

In addition to the common properties.

PropertyTypeDescription
[Agent] Abandonment TurnnumberTurn ID of the last user message that got a response before the user left. Low values signal early drop-off.
[Agent] Session Idle Timeout MinutesnumberThe session's idle timeout. Tells the server how long to wait before auto-closing the session.
[Agent] EnrichmentsstringSerialized JSON of any enrichments provided at session close.

[Agent] Session Enrichment properties

Sent in customer_enriched privacy mode. In addition to the common properties.

PropertyTypeRequiredDescription
[Agent] EnrichmentsstringYesSerialized JSON of your session enrichments: outcome, quality and sentiment scores, flags, and message labels.

[Agent] Score properties

[Agent] Score carries explicit user feedback. In addition to the common properties.

PropertyTypeRequiredDescription
[Agent] Score NamestringYesName of the score (for example, user-feedback).
[Agent] Score ValuenumberYesNumeric value: binary (0/1), continuous (0.0–1.0), or a rating scale.
[Agent] Target IDstringYesThe Message ID or Session ID being scored.
[Agent] Target TypestringYesWhat is being scored: message or session.
[Agent] Evaluation SourcestringYesSource of the score. For SDK feedback this is user or reviewer.
[Agent] CommentstringNoOptional text explanation. Respects the privacy mode.

Event JSON examples

These examples show what the SDK sends to Amplitude. Property names and the $llm_message content shape are the same whether you use the SDK or send events directly.
json
{
  "event_type": "[Agent] AI Response",
  "user_id": "user-42",
  "event_properties": {
    "[Agent] Session ID": "sess-abc123",
    "[Agent] Trace ID": "trace-def456",
    "[Agent] Turn ID": 2,
    "[Agent] Message ID": "msg-789xyz",
    "[Agent] Model Name": "gpt-4o",
    "[Agent] Provider": "openai",
    "[Agent] Model Tier": "standard",
    "[Agent] Latency Ms": 1203,
    "[Agent] Input Tokens": 150,
    "[Agent] Output Tokens": 847,
    "[Agent] Total Tokens": 997,
    "[Agent] Cost USD": 0.0042,
    "[Agent] Is Error": false,
    "[Agent] Finish Reason": "stop",
    "[Agent] Component Type": "llm",
    "[Agent] Agent ID": "support-bot",
    "[Agent] Env": "production",
    "[Agent] SDK Version": "1.0.0",
    "[Agent] Runtime": "node"
  }
}
json
{
  "event_type": "[Agent] User Message",
  "user_id": "user-42",
  "event_properties": {
    "[Agent] Session ID": "sess-abc123",
    "[Agent] Turn ID": 1,
    "[Agent] Message ID": "msg-123abc",
    "[Agent] Component Type": "user_input",
    "[Agent] Agent ID": "support-bot",
    "[Agent] SDK Version": "1.0.0",
    "[Agent] Runtime": "node",
    "$llm_message": { "text": "How do I reset my password?" }
  }
}
json
{
  "event_type": "[Agent] Tool Call",
  "user_id": "user-42",
  "event_properties": {
    "[Agent] Session ID": "sess-abc123",
    "[Agent] Turn ID": 3,
    "[Agent] Invocation ID": "inv-456def",
    "[Agent] Tool Name": "search_knowledge_base",
    "[Agent] Tool Success": true,
    "[Agent] Is Error": false,
    "[Agent] Latency Ms": 340,
    "[Agent] Component Type": "tool",
    "[Agent] Agent ID": "support-bot",
    "[Agent] SDK Version": "1.0.0",
    "[Agent] Runtime": "node"
  }
}
json
{
  "event_type": "[Agent] Score",
  "user_id": "user-42",
  "event_properties": {
    "[Agent] Score Name": "thumbs-up",
    "[Agent] Score Value": 1,
    "[Agent] Target ID": "msg-789xyz",
    "[Agent] Target Type": "message",
    "[Agent] Evaluation Source": "user",
    "[Agent] Session ID": "sess-abc123",
    "[Agent] Agent ID": "support-bot",
    "[Agent] SDK Version": "1.0.0",
    "[Agent] Runtime": "node"
  }
}

Server enrichment events

After a session closes, the enrichment pipeline assesses it and writes two events back to your event stream.

Session Record

[Agent] Session Record lands once per session. It carries the session rollups, the always-on signal results, and quality flags.

PropertyTypeDescription
[Agent] Turn CountnumberNumber of turns in the session.
[Agent] Session Total TokensnumberTotal LLM tokens across all turns.
[Agent] Session Avg Latency MsnumberAverage AI response latency in milliseconds across the session.
[Agent] Models Usedstring[]The LLM models used in the session.
[Agent] Has Negative FeedbackbooleanWhether the user expressed dissatisfaction during the session.
[Agent] Has Technical FailurebooleanWhether technical errors occurred, such as tool timeouts or API failures.
[Agent] Technical Error CountnumberCount of technical errors in the session.
[Agent] Has Data Quality IssuesbooleanWhether the AI output had data quality problems, such as wrong data or hallucinations.
[Agent] Root Agent NamestringThe entry-point agent in a multi-agent flow.
[Agent] Agent Chain DepthnumberNumber of agents in the delegation chain.

Evaluator Result

[Agent] Evaluator Result lands once per evaluator per session. It is the unified event for every server-side evaluation: signal detectors, topic classifiers, and rubric scorers.

PropertyTypeDescription
[Agent] Evaluator NamestringThe evaluator that produced this result. For topic classifications, this is the topic model name, such as product_area.
[Agent] Evaluator Output TypestringThe result shape: binary, classification, or score.
[Agent] Binary LabelbooleanFor binary evaluators, whether the condition was detected.
[Agent] Primary LabelstringFor classification evaluators, the primary label assigned.
[Agent] Selection ModestringWhether the topic model assigns a single label (MECE) or multiple.
[Agent] RationalestringThe model's explanation for the result.
[Agent] EvidencestringSupporting evidence the model cited.
[Agent] Evaluator ModelstringThe LLM that ran the evaluation.
[Agent] Evaluation SourcestringWhere the evaluation came from: ai, user, or reviewer.
[Agent] Evaluator VersionstringThe evaluator config version that produced this result.
[Agent] Evaluated AtnumberEpoch milliseconds when the result was computed.

User feedback scores

[Agent] Score records explicit user feedback, such as a thumbs up or down on a response. Scores come from your application through the SDK's score() method, not from the enrichment pipeline. To send scores, go to Send user feedback (scores).

Signals

Signals are the default, always-on evaluators that Amplitude runs on every closed session. They land as [Agent] Evaluator Result events. You don't configure them, and Amplitude refines them over time, so treat them as directional.

SignalOutputWhat it measures
Task completionbinaryWhether the agent completed the user's task.
Response qualityscore (0.0 to 1.0)Whether responses were accurate and well-formed.
User frictionbinaryWhether the user expressed dissatisfaction.
User intentclassificationThe user's intent for the session.
Session safetyclassificationClassifies the session as Normal, Off Topic, Prompt Injection, Abuse, Probing, Unsafe Output, or Data Leak.
Data qualitycode-based checkFlags wrong data or hallucination patterns. Returns a clear result rather than a generated rationale.

Topics and custom evaluators

Beyond the default signals, you define your own topic models and evaluators. The enrichment taxonomy is fully configurable: topic model names such as query_intent and product_area, and evaluator names such as task_completion, come from configuration and differ per project. To create and refine your own evaluators, go to Create and refine custom evaluators.

Deprecated events

[Agent] Topic Classification is deprecated. Topic classifications now land as [Agent] Evaluator Result events with an output type of classification. Rubric scores also moved off [Agent] Score onto [Agent] Evaluator Result with an output type of score. [Agent] Score now carries user feedback only.

Was this helpful?