@amplitude/ai 0.3.4 → 0.3.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +1 -1
- package/README.md +176 -172
- package/data/agent_event_catalog.json +18 -3
- package/dist/client.d.ts +1 -0
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +1 -0
- package/dist/client.js.map +1 -1
- package/dist/core/constants.d.ts +4 -1
- package/dist/core/constants.d.ts.map +1 -1
- package/dist/core/constants.js +4 -1
- package/dist/core/constants.js.map +1 -1
- package/dist/core/privacy.d.ts +7 -1
- package/dist/core/privacy.d.ts.map +1 -1
- package/dist/core/privacy.js +78 -2
- package/dist/core/privacy.js.map +1 -1
- package/dist/core/tracking.d.ts +3 -2
- package/dist/core/tracking.d.ts.map +1 -1
- package/dist/core/tracking.js +4 -2
- package/dist/core/tracking.js.map +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.js +3 -3
- package/dist/providers/anthropic.d.ts.map +1 -1
- package/dist/providers/anthropic.js +6 -0
- package/dist/providers/anthropic.js.map +1 -1
- package/dist/providers/bedrock.d.ts.map +1 -1
- package/dist/providers/bedrock.js +8 -0
- package/dist/providers/bedrock.js.map +1 -1
- package/dist/providers/gemini.d.ts.map +1 -1
- package/dist/providers/gemini.js +6 -0
- package/dist/providers/gemini.js.map +1 -1
- package/dist/providers/mistral.d.ts.map +1 -1
- package/dist/providers/mistral.js +6 -0
- package/dist/providers/mistral.js.map +1 -1
- package/dist/providers/openai.d.ts +2 -1
- package/dist/providers/openai.d.ts.map +1 -1
- package/dist/providers/openai.js +13 -1
- package/dist/providers/openai.js.map +1 -1
- package/dist/types.d.ts +1 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/dist/utils/logger.d.ts.map +1 -1
- package/llms-full.txt +1 -1
- package/llms.txt +1 -1
- package/mcp.schema.json +1 -1
- package/package.json +1 -1
package/AGENTS.md
CHANGED
package/README.md
CHANGED
|
@@ -2060,228 +2060,232 @@ All event properties are prefixed with `[Agent]` (except `[Amplitude] Session Re
|
|
|
2060
2060
|
|
|
2061
2061
|
### Common Properties (present on all SDK events)
|
|
2062
2062
|
|
|
2063
|
-
| Property
|
|
2064
|
-
|
|
2065
|
-
| `[Agent] Session ID`
|
|
2066
|
-
| `[Agent] Trace ID`
|
|
2067
|
-
| `[Agent] Turn ID`
|
|
2068
|
-
| `[Agent] Agent ID`
|
|
2069
|
-
| `[Agent] Parent Agent ID` | string | No
|
|
2070
|
-
| `[Agent] Customer Org ID` | string | No
|
|
2071
|
-
| `[Agent] Agent Version`
|
|
2072
|
-
| `[Agent]
|
|
2073
|
-
| `[Agent]
|
|
2074
|
-
| `[Agent]
|
|
2075
|
-
| `[Agent]
|
|
2063
|
+
| Property | Type | Required | Description |
|
|
2064
|
+
|----------|------|----------|-------------|
|
|
2065
|
+
| `[Agent] Session ID` | string | Yes | Unique session identifier. All events in one conversation share the same session ID. |
|
|
2066
|
+
| `[Agent] Trace ID` | string | No | Identifies one user-message-to-AI-response cycle within a session. |
|
|
2067
|
+
| `[Agent] Turn ID` | number | No | Monotonically increasing counter for event ordering within a session. |
|
|
2068
|
+
| `[Agent] Agent ID` | string | No | Identifies which AI agent handled the interaction (e.g., 'support-bot', 'houston'). |
|
|
2069
|
+
| `[Agent] Parent Agent ID` | string | No | For multi-agent orchestration: the agent that delegated to this agent. |
|
|
2070
|
+
| `[Agent] Customer Org ID` | string | No | Organization ID for multi-tenant platforms. Enables account-level group analytics. |
|
|
2071
|
+
| `[Agent] Agent Version` | string | No | Agent code version (e.g., 'v4.2'). Enables version-over-version quality comparison. |
|
|
2072
|
+
| `[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. |
|
|
2073
|
+
| `[Agent] Context` | string | No | Serialized JSON dict of arbitrary segmentation dimensions (experiment_variant, surface, feature_flag, prompt_revision, etc.). |
|
|
2074
|
+
| `[Agent] Env` | string | No | Deployment environment: 'production', 'staging', or 'dev'. |
|
|
2075
|
+
| `[Agent] SDK Version` | string | Yes | Version of the amplitude-ai SDK that produced this event. |
|
|
2076
|
+
| `[Agent] Runtime` | string | Yes | SDK runtime: 'python' or 'node'. |
|
|
2076
2077
|
|
|
2077
2078
|
### User Message Properties
|
|
2078
2079
|
|
|
2079
2080
|
Event-specific properties for `[Agent] User Message` (in addition to common properties above).
|
|
2080
2081
|
|
|
2081
|
-
| Property
|
|
2082
|
-
|
|
2083
|
-
| `[Agent] Message ID`
|
|
2084
|
-
| `[Agent] Component Type`
|
|
2085
|
-
| `[Agent] Locale`
|
|
2086
|
-
| `[Amplitude] Session Replay ID`
|
|
2087
|
-
| `[Agent] Is Regeneration`
|
|
2088
|
-
| `[Agent] Is Edit`
|
|
2089
|
-
| `[Agent] Edited Message ID`
|
|
2090
|
-
| `[Agent] Has Attachments`
|
|
2091
|
-
| `[Agent] Attachment Types`
|
|
2092
|
-
| `[Agent] Attachment Count`
|
|
2093
|
-
| `[Agent] Total Attachment Size Bytes` | number
|
|
2094
|
-
| `[Agent] Attachments`
|
|
2095
|
-
| `[Agent] Message Labels`
|
|
2096
|
-
| `[Agent] Message Source`
|
|
2082
|
+
| Property | Type | Required | Description |
|
|
2083
|
+
|----------|------|----------|-------------|
|
|
2084
|
+
| `[Agent] Message ID` | string | Yes | Unique identifier for this message event (UUID). Used to link scores and tool calls back to specific messages. |
|
|
2085
|
+
| `[Agent] Component Type` | string | Yes | Type of component that produced this event: 'user_input', 'llm', 'tool', 'embedding'. |
|
|
2086
|
+
| `[Agent] Locale` | string | No | User locale (e.g., 'en-US'). |
|
|
2087
|
+
| `[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. |
|
|
2088
|
+
| `[Agent] Is Regeneration` | boolean | No | Whether the user requested the AI regenerate a previous response. |
|
|
2089
|
+
| `[Agent] Is Edit` | boolean | No | Whether the user edited a previous message and resubmitted. |
|
|
2090
|
+
| `[Agent] Edited Message ID` | string | No | The message_id of the original message that was edited (links the edit to the original). |
|
|
2091
|
+
| `[Agent] Has Attachments` | boolean | No | Whether this message includes file attachments (uploads, images, etc.). |
|
|
2092
|
+
| `[Agent] Attachment Types` | string[] | No | Distinct attachment types (e.g., 'pdf', 'image', 'csv'). Serialized JSON array. |
|
|
2093
|
+
| `[Agent] Attachment Count` | number | No | Number of file attachments included with this message. |
|
|
2094
|
+
| `[Agent] Total Attachment Size Bytes` | number | No | Total size of all attachments in bytes. |
|
|
2095
|
+
| `[Agent] Attachments` | string | No | Serialized JSON array of attachment metadata (type, name, size_bytes, mime_type). Only metadata, never file content. |
|
|
2096
|
+
| `[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. |
|
|
2097
|
+
| `[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. |
|
|
2097
2098
|
|
|
2098
2099
|
### AI Response Properties
|
|
2099
2100
|
|
|
2100
2101
|
Event-specific properties for `[Agent] AI Response` (in addition to common properties above).
|
|
2101
2102
|
|
|
2102
|
-
| Property
|
|
2103
|
-
|
|
2104
|
-
| `[Agent] Message ID`
|
|
2105
|
-
| `[Agent] Component Type`
|
|
2106
|
-
| `[Agent] Model Name`
|
|
2107
|
-
| `[Agent] Provider`
|
|
2108
|
-
| `[Agent] Latency Ms`
|
|
2109
|
-
| `[Agent] Is Error`
|
|
2110
|
-
| `[Agent] Error Message`
|
|
2111
|
-
| `[Agent] Locale`
|
|
2112
|
-
| `[Agent] Span Kind`
|
|
2113
|
-
| `[Amplitude] Session Replay ID`
|
|
2114
|
-
| `[Agent] TTFB Ms`
|
|
2115
|
-
| `[Agent] Input Tokens`
|
|
2116
|
-
| `[Agent] Output Tokens`
|
|
2117
|
-
| `[Agent] Total Tokens`
|
|
2118
|
-
| `[Agent] Reasoning Tokens`
|
|
2119
|
-
| `[Agent] Cache Read Tokens`
|
|
2120
|
-
| `[Agent] Cache Creation Tokens`
|
|
2121
|
-
| `[Agent] Cost USD`
|
|
2122
|
-
| `[Agent] Finish Reason`
|
|
2123
|
-
| `[Agent] Tool Calls`
|
|
2124
|
-
| `[Agent] Has Reasoning`
|
|
2125
|
-
| `[Agent] Reasoning Content`
|
|
2126
|
-
| `[Agent] System Prompt`
|
|
2127
|
-
| `[Agent] System Prompt Length`
|
|
2128
|
-
| `[Agent]
|
|
2129
|
-
| `[Agent]
|
|
2130
|
-
| `[Agent]
|
|
2131
|
-
| `[Agent]
|
|
2132
|
-
| `[Agent]
|
|
2133
|
-
| `[Agent]
|
|
2134
|
-
| `[Agent]
|
|
2135
|
-
| `[Agent]
|
|
2136
|
-
| `[Agent]
|
|
2137
|
-
| `[Agent]
|
|
2138
|
-
| `[Agent]
|
|
2139
|
-
| `[Agent]
|
|
2140
|
-
| `[Agent]
|
|
2141
|
-
| `[Agent]
|
|
2142
|
-
| `[Agent]
|
|
2103
|
+
| Property | Type | Required | Description |
|
|
2104
|
+
|----------|------|----------|-------------|
|
|
2105
|
+
| `[Agent] Message ID` | string | Yes | Unique identifier for this message event (UUID). Used to link scores and tool calls back to specific messages. |
|
|
2106
|
+
| `[Agent] Component Type` | string | Yes | Type of component that produced this event: 'user_input', 'llm', 'tool', 'embedding'. |
|
|
2107
|
+
| `[Agent] Model Name` | string | Yes | LLM model identifier (e.g., 'gpt-4o', 'claude-sonnet-4-20250514'). |
|
|
2108
|
+
| `[Agent] Provider` | string | Yes | LLM provider name (e.g., 'openai', 'anthropic', 'google', 'mistral', 'bedrock'). |
|
|
2109
|
+
| `[Agent] Latency Ms` | number | Yes | Total wall-clock latency in milliseconds for this operation. |
|
|
2110
|
+
| `[Agent] Is Error` | boolean | Yes | Whether this event represents an error condition. |
|
|
2111
|
+
| `[Agent] Error Message` | string | No | Error message text when Is Error is true. |
|
|
2112
|
+
| `[Agent] Locale` | string | No | User locale (e.g., 'en-US'). |
|
|
2113
|
+
| `[Agent] Span Kind` | string | No | Classification of the span type for OTEL bridge compatibility. |
|
|
2114
|
+
| `[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. |
|
|
2115
|
+
| `[Agent] TTFB Ms` | number | No | Time to first byte/token in milliseconds. Measures perceived responsiveness for streaming. |
|
|
2116
|
+
| `[Agent] Input Tokens` | number | No | Number of input/prompt tokens consumed by this LLM call. |
|
|
2117
|
+
| `[Agent] Output Tokens` | number | No | Number of output/completion tokens generated by this LLM call. |
|
|
2118
|
+
| `[Agent] Total Tokens` | number | No | Total tokens consumed (input + output). |
|
|
2119
|
+
| `[Agent] Reasoning Tokens` | number | No | Tokens consumed by reasoning/thinking (o1, o3, extended thinking models). |
|
|
2120
|
+
| `[Agent] Cache Read Tokens` | number | No | Input tokens served from the provider's prompt cache (cheaper rate). Used for cache-aware cost calculation. |
|
|
2121
|
+
| `[Agent] Cache Creation Tokens` | number | No | Input tokens that created new prompt cache entries. |
|
|
2122
|
+
| `[Agent] Cost USD` | number | No | Estimated cost in USD for this LLM call. Cache-aware when cache token counts are provided. |
|
|
2123
|
+
| `[Agent] Finish Reason` | string | No | Why the model stopped generating: 'stop', 'end_turn', 'tool_use', 'length', 'content_filter', etc. |
|
|
2124
|
+
| `[Agent] Tool Calls` | string | No | Serialized JSON array of tool call requests made by the AI in this response. |
|
|
2125
|
+
| `[Agent] Has Reasoning` | boolean | No | Whether the AI response included reasoning/thinking content. |
|
|
2126
|
+
| `[Agent] Reasoning Content` | string | No | The AI's reasoning/thinking content (when available and content_mode permits). |
|
|
2127
|
+
| `[Agent] System Prompt` | string | No | The system prompt used for this LLM call (when content_mode permits). Chunked for long prompts. |
|
|
2128
|
+
| `[Agent] System Prompt Length` | number | No | Character length of the system prompt. |
|
|
2129
|
+
| `[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. |
|
|
2130
|
+
| `[Agent] Tool Definitions Count` | number | No | Number of tool definitions in the LLM request. |
|
|
2131
|
+
| `[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. |
|
|
2132
|
+
| `[Agent] Temperature` | number | No | Temperature parameter used for this LLM call. |
|
|
2133
|
+
| `[Agent] Max Output Tokens` | number | No | Maximum output tokens configured for this LLM call. |
|
|
2134
|
+
| `[Agent] Top P` | number | No | Top-p (nucleus sampling) parameter used for this LLM call. |
|
|
2135
|
+
| `[Agent] Is Streaming` | boolean | No | Whether this response was generated via streaming. |
|
|
2136
|
+
| `[Agent] Prompt ID` | string | No | Identifier for the prompt template or version used. |
|
|
2137
|
+
| `[Agent] Was Copied` | boolean | No | Whether the user copied this AI response content. An implicit positive quality signal. |
|
|
2138
|
+
| `[Agent] Was Cached` | boolean | No | Whether this response was served from a semantic/full-response cache (distinct from token-level prompt caching). |
|
|
2139
|
+
| `[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. |
|
|
2140
|
+
| `[Agent] Has Attachments` | boolean | No | Whether this AI response includes generated attachments (images, charts, files). |
|
|
2141
|
+
| `[Agent] Attachment Types` | string[] | No | Distinct attachment types in this AI response. Serialized JSON array. |
|
|
2142
|
+
| `[Agent] Attachment Count` | number | No | Number of attachments generated by the AI in this response. |
|
|
2143
|
+
| `[Agent] Total Attachment Size Bytes` | number | No | Total size of all AI-generated attachments in bytes. |
|
|
2144
|
+
| `[Agent] Attachments` | string | No | Serialized JSON array of AI-generated attachment metadata. |
|
|
2145
|
+
| `[Agent] Message Labels` | string | No | Serialized JSON array of MessageLabel objects attached to this AI response. |
|
|
2146
|
+
| `[Agent] Message Label Map` | string | No | Serialized JSON map of label key to value for quick lookup. |
|
|
2143
2147
|
|
|
2144
2148
|
### Tool Call Properties
|
|
2145
2149
|
|
|
2146
2150
|
Event-specific properties for `[Agent] Tool Call` (in addition to common properties above).
|
|
2147
2151
|
|
|
2148
|
-
| Property
|
|
2149
|
-
|
|
2150
|
-
| `[Agent] Component Type`
|
|
2151
|
-
| `[Agent] Latency Ms`
|
|
2152
|
-
| `[Agent] Is Error`
|
|
2153
|
-
| `[Agent] Error Message`
|
|
2154
|
-
| `[Agent] Locale`
|
|
2155
|
-
| `[Agent] Span Kind`
|
|
2156
|
-
| `[Amplitude] Session Replay ID` | string
|
|
2157
|
-
| `[Agent] Invocation ID`
|
|
2158
|
-
| `[Agent] Tool Name`
|
|
2159
|
-
| `[Agent] Tool Success`
|
|
2160
|
-
| `[Agent] Tool Input`
|
|
2161
|
-
| `[Agent] Tool Output`
|
|
2162
|
-
| `[Agent] Parent Message ID`
|
|
2152
|
+
| Property | Type | Required | Description |
|
|
2153
|
+
|----------|------|----------|-------------|
|
|
2154
|
+
| `[Agent] Component Type` | string | Yes | Type of component that produced this event: 'user_input', 'llm', 'tool', 'embedding'. |
|
|
2155
|
+
| `[Agent] Latency Ms` | number | Yes | Total wall-clock latency in milliseconds for this operation. |
|
|
2156
|
+
| `[Agent] Is Error` | boolean | Yes | Whether this event represents an error condition. |
|
|
2157
|
+
| `[Agent] Error Message` | string | No | Error message text when Is Error is true. |
|
|
2158
|
+
| `[Agent] Locale` | string | No | User locale (e.g., 'en-US'). |
|
|
2159
|
+
| `[Agent] Span Kind` | string | No | Classification of the span type for OTEL bridge compatibility. |
|
|
2160
|
+
| `[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. |
|
|
2161
|
+
| `[Agent] Invocation ID` | string | Yes | Unique identifier for this tool invocation (UUID). Used to link tool calls to parent messages. |
|
|
2162
|
+
| `[Agent] Tool Name` | string | Yes | Name of the tool/function that was invoked (e.g., 'search_docs', 'web_search'). |
|
|
2163
|
+
| `[Agent] Tool Success` | boolean | Yes | Whether the tool call completed successfully. |
|
|
2164
|
+
| `[Agent] Tool Input` | string | No | Serialized JSON of the tool's input arguments. Only sent when content_mode='full'. |
|
|
2165
|
+
| `[Agent] Tool Output` | string | No | Serialized JSON of the tool's output/return value. Only sent when content_mode='full'. |
|
|
2166
|
+
| `[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. |
|
|
2163
2167
|
|
|
2164
2168
|
### Embedding Properties
|
|
2165
2169
|
|
|
2166
2170
|
Event-specific properties for `[Agent] Embedding` (in addition to common properties above).
|
|
2167
2171
|
|
|
2168
|
-
| Property
|
|
2169
|
-
|
|
2170
|
-
| `[Agent] Component Type`
|
|
2171
|
-
| `[Agent] Model Name`
|
|
2172
|
-
| `[Agent] Provider`
|
|
2173
|
-
| `[Agent] Latency Ms`
|
|
2174
|
-
| `[Agent] Span ID`
|
|
2175
|
-
| `[Agent] Input Tokens`
|
|
2176
|
-
| `[Agent] Embedding Dimensions` | number | No
|
|
2177
|
-
| `[Agent] Cost USD`
|
|
2172
|
+
| Property | Type | Required | Description |
|
|
2173
|
+
|----------|------|----------|-------------|
|
|
2174
|
+
| `[Agent] Component Type` | string | Yes | Type of component that produced this event: 'user_input', 'llm', 'tool', 'embedding'. |
|
|
2175
|
+
| `[Agent] Model Name` | string | Yes | LLM model identifier (e.g., 'gpt-4o', 'claude-sonnet-4-20250514'). |
|
|
2176
|
+
| `[Agent] Provider` | string | Yes | LLM provider name (e.g., 'openai', 'anthropic', 'google', 'mistral', 'bedrock'). |
|
|
2177
|
+
| `[Agent] Latency Ms` | number | Yes | Total wall-clock latency in milliseconds for this operation. |
|
|
2178
|
+
| `[Agent] Span ID` | string | Yes | Unique identifier for this embedding operation (UUID). |
|
|
2179
|
+
| `[Agent] Input Tokens` | number | No | Number of input tokens processed by the embedding model. |
|
|
2180
|
+
| `[Agent] Embedding Dimensions` | number | No | Dimensionality of the output embedding vector. |
|
|
2181
|
+
| `[Agent] Cost USD` | number | No | Estimated cost in USD for this embedding operation. |
|
|
2178
2182
|
|
|
2179
2183
|
### Span Properties
|
|
2180
2184
|
|
|
2181
2185
|
Event-specific properties for `[Agent] Span` (in addition to common properties above).
|
|
2182
2186
|
|
|
2183
|
-
| Property
|
|
2184
|
-
|
|
2185
|
-
| `[Agent] Latency Ms`
|
|
2186
|
-
| `[Agent] Is Error`
|
|
2187
|
-
| `[Agent] Error Message`
|
|
2188
|
-
| `[Agent] Span ID`
|
|
2189
|
-
| `[Agent] Span Name`
|
|
2190
|
-
| `[Agent] Parent Span ID` | string
|
|
2191
|
-
| `[Agent] Input State`
|
|
2192
|
-
| `[Agent] Output State`
|
|
2187
|
+
| Property | Type | Required | Description |
|
|
2188
|
+
|----------|------|----------|-------------|
|
|
2189
|
+
| `[Agent] Latency Ms` | number | Yes | Total wall-clock latency in milliseconds for this operation. |
|
|
2190
|
+
| `[Agent] Is Error` | boolean | Yes | Whether this event represents an error condition. |
|
|
2191
|
+
| `[Agent] Error Message` | string | No | Error message text when Is Error is true. |
|
|
2192
|
+
| `[Agent] Span ID` | string | Yes | Unique identifier for this span (UUID). |
|
|
2193
|
+
| `[Agent] Span Name` | string | Yes | Name of the operation (e.g., 'rag_pipeline', 'vector_search', 'rerank'). |
|
|
2194
|
+
| `[Agent] Parent Span ID` | string | No | Span ID of the parent span for nested pipeline steps. |
|
|
2195
|
+
| `[Agent] Input State` | string | No | Serialized JSON of the span's input state. Only sent when content_mode='full'. |
|
|
2196
|
+
| `[Agent] Output State` | string | No | Serialized JSON of the span's output state. Only sent when content_mode='full'. |
|
|
2193
2197
|
|
|
2194
2198
|
### Session End Properties
|
|
2195
2199
|
|
|
2196
2200
|
Event-specific properties for `[Agent] Session End` (in addition to common properties above).
|
|
2197
2201
|
|
|
2198
|
-
| Property
|
|
2199
|
-
|
|
2200
|
-
| `[Agent] Enrichments`
|
|
2201
|
-
| `[Agent] Abandonment Turn`
|
|
2202
|
-
| `[Agent] Session Idle Timeout Minutes` | number | No
|
|
2202
|
+
| Property | Type | Required | Description |
|
|
2203
|
+
|----------|------|----------|-------------|
|
|
2204
|
+
| `[Agent] Enrichments` | string | No | Serialized JSON of SessionEnrichments (topic classifications, rubric scores, outcome, flags). Attached when enrichments are provided at session close. |
|
|
2205
|
+
| `[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. |
|
|
2206
|
+
| `[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. |
|
|
2203
2207
|
|
|
2204
2208
|
### Session Enrichment Properties
|
|
2205
2209
|
|
|
2206
2210
|
Event-specific properties for `[Agent] Session Enrichment` (in addition to common properties above).
|
|
2207
2211
|
|
|
2208
|
-
| Property
|
|
2209
|
-
|
|
2210
|
-
| `[Agent] Enrichments` | string | Yes
|
|
2212
|
+
| Property | Type | Required | Description |
|
|
2213
|
+
|----------|------|----------|-------------|
|
|
2214
|
+
| `[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. |
|
|
2211
2215
|
|
|
2212
2216
|
### Score Properties
|
|
2213
2217
|
|
|
2214
2218
|
Event-specific properties for `[Agent] Score` (in addition to common properties above).
|
|
2215
2219
|
|
|
2216
|
-
| Property
|
|
2217
|
-
|
|
2218
|
-
| `[Agent] Score Name`
|
|
2219
|
-
| `[Agent] Score Value`
|
|
2220
|
-
| `[Agent] Target ID`
|
|
2221
|
-
| `[Agent] Target Type`
|
|
2222
|
-
| `[Agent] Evaluation Source` | string | Yes
|
|
2223
|
-
| `[Agent] Comment`
|
|
2224
|
-
| `[Agent] Taxonomy Version`
|
|
2225
|
-
| `[Agent] Evaluated At`
|
|
2226
|
-
| `[Agent] Score Label`
|
|
2220
|
+
| Property | Type | Required | Description |
|
|
2221
|
+
|----------|------|----------|-------------|
|
|
2222
|
+
| `[Agent] Score Name` | string | Yes | Name of the score (e.g., 'user-feedback', 'task_completion', 'accuracy', 'groundedness'). |
|
|
2223
|
+
| `[Agent] Score Value` | number | Yes | Numeric score value. Binary (0/1), continuous (0.0-1.0), or rating scale (1-5). |
|
|
2224
|
+
| `[Agent] Target ID` | string | Yes | The message_id or session_id being scored. |
|
|
2225
|
+
| `[Agent] Target Type` | string | Yes | What is being scored: 'message' or 'session'. |
|
|
2226
|
+
| `[Agent] Evaluation Source` | string | Yes | Source of the evaluation: 'user' (end-user feedback), 'ai' (automated/server pipeline), or 'reviewer' (human expert). |
|
|
2227
|
+
| `[Agent] Comment` | string | No | Optional text explanation for the score (respects content_mode). |
|
|
2228
|
+
| `[Agent] Taxonomy Version` | string | No | Which taxonomy config version produced this enrichment (from ai_category_config.config_version_id). |
|
|
2229
|
+
| `[Agent] Evaluated At` | number | No | Epoch milliseconds when this enrichment/evaluation was computed. |
|
|
2230
|
+
| `[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. |
|
|
2227
2231
|
|
|
2228
2232
|
### Server-Side: Session Evaluation Properties
|
|
2229
2233
|
|
|
2230
2234
|
`[Agent] Session Evaluation` is emitted automatically by the server-side enrichment pipeline — do not send this event from your code.
|
|
2231
2235
|
|
|
2232
|
-
| Property
|
|
2233
|
-
|
|
2234
|
-
| `[Agent] Session ID`
|
|
2235
|
-
| `[Agent] Agent ID`
|
|
2236
|
-
| `[Agent] Customer Org ID`
|
|
2237
|
-
| `[Agent] Evaluation Source`
|
|
2238
|
-
| `[Agent] Taxonomy Version`
|
|
2239
|
-
| `[Agent] Evaluated At`
|
|
2240
|
-
| `[Agent] Overall Outcome`
|
|
2241
|
-
| `[Agent] Turn Count`
|
|
2242
|
-
| `[Agent] Session Total Tokens`
|
|
2243
|
-
| `[Agent] Session Avg Latency Ms`
|
|
2244
|
-
| `[Agent] Request Complexity`
|
|
2245
|
-
| `[Agent] Has Task Failure`
|
|
2246
|
-
| `[Agent] Has Negative Feedback`
|
|
2247
|
-
| `[Agent] Has Technical Failure`
|
|
2248
|
-
| `[Agent] Has Data Quality Issues` | boolean
|
|
2249
|
-
| `[Agent] Models Used`
|
|
2250
|
-
| `[Agent] Root Agent Name`
|
|
2251
|
-
| `[Agent] Agent Chain Depth`
|
|
2252
|
-
| `[Agent] Task Failure Type`
|
|
2253
|
-
| `[Agent] Technical Error Count`
|
|
2254
|
-
| `[Agent] Error Categories`
|
|
2255
|
-
| `[Agent] Behavioral Patterns`
|
|
2256
|
-
| `[Agent] Session Cost USD`
|
|
2257
|
-
| `[Agent] Enrichment Cost USD`
|
|
2258
|
-
| `[Agent] Quality Score`
|
|
2259
|
-
| `[Agent] Sentiment Score`
|
|
2260
|
-
| `[Agent] Task Failure Reason`
|
|
2261
|
-
| `[Agent] Agent Chain`
|
|
2262
|
-
| `[Agent] Project ID`
|
|
2263
|
-
| `[Agent] Has User Feedback`
|
|
2264
|
-
| `[Agent] User Score`
|
|
2265
|
-
| `[Agent] Agent Version`
|
|
2236
|
+
| Property | Type | Required | Description |
|
|
2237
|
+
|----------|------|----------|-------------|
|
|
2238
|
+
| `[Agent] Session ID` | string | Yes | Unique session identifier. All events in one conversation share the same session ID. |
|
|
2239
|
+
| `[Agent] Agent ID` | string | Yes | Identifies which AI agent handled the interaction (e.g., 'support-bot', 'houston'). |
|
|
2240
|
+
| `[Agent] Customer Org ID` | string | Yes | Organization ID for multi-tenant platforms. Enables account-level group analytics. |
|
|
2241
|
+
| `[Agent] Evaluation Source` | string | Yes | Source of the evaluation: 'user' (end-user feedback), 'ai' (automated/server pipeline), or 'reviewer' (human expert). |
|
|
2242
|
+
| `[Agent] Taxonomy Version` | string | Yes | Which taxonomy config version produced this enrichment (from ai_category_config.config_version_id). |
|
|
2243
|
+
| `[Agent] Evaluated At` | number | Yes | Epoch milliseconds when this enrichment/evaluation was computed. |
|
|
2244
|
+
| `[Agent] Overall Outcome` | string | Yes | Session outcome classification: 'success', 'partial_success', 'failure', 'abandoned', 'response_provided', etc. |
|
|
2245
|
+
| `[Agent] Turn Count` | number | Yes | Number of conversation turns in this session. |
|
|
2246
|
+
| `[Agent] Session Total Tokens` | number | No | Total LLM tokens consumed across all turns in this session. |
|
|
2247
|
+
| `[Agent] Session Avg Latency Ms` | number | No | Average AI response latency in milliseconds across the session. |
|
|
2248
|
+
| `[Agent] Request Complexity` | string | No | Complexity classification of the user's request: 'simple', 'moderate', 'complex', or 'ambiguous'. |
|
|
2249
|
+
| `[Agent] Has Task Failure` | boolean | Yes | Whether the agent failed to complete the user's request. |
|
|
2250
|
+
| `[Agent] Has Negative Feedback` | boolean | Yes | Whether the user expressed dissatisfaction during the session. |
|
|
2251
|
+
| `[Agent] Has Technical Failure` | boolean | Yes | Whether technical errors occurred (tool timeouts, API failures, etc.). |
|
|
2252
|
+
| `[Agent] Has Data Quality Issues` | boolean | Yes | Whether the AI output had data quality problems (wrong data, hallucinations, etc.). |
|
|
2253
|
+
| `[Agent] Models Used` | string[] | No | LLM models used in this session. JSON array of strings. |
|
|
2254
|
+
| `[Agent] Root Agent Name` | string | No | Entry-point agent in multi-agent flows. |
|
|
2255
|
+
| `[Agent] Agent Chain Depth` | number | No | Number of agents in the delegation chain. |
|
|
2256
|
+
| `[Agent] Task Failure Type` | string | No | Specific failure type when has_task_failure is true (e.g., 'wrong_answer', 'unable_to_complete'). |
|
|
2257
|
+
| `[Agent] Technical Error Count` | number | No | Count of technical errors that occurred during the session. |
|
|
2258
|
+
| `[Agent] Error Categories` | string[] | No | Categorized error types (e.g., 'chart_not_found', 'timeout'). JSON array of strings. |
|
|
2259
|
+
| `[Agent] Behavioral Patterns` | string[] | No | Detected behavioral anti-patterns (e.g., 'retry_storm', 'clarification_loop', 'early_abandonment'). JSON array of strings. |
|
|
2260
|
+
| `[Agent] Session Cost USD` | number | No | Total LLM cost in USD for this AI session (aggregated from per-message costs). |
|
|
2261
|
+
| `[Agent] Enrichment Cost USD` | number | No | Cost in USD of running the enrichment pipeline's LLM inference for this session. Distinct from the session's own LLM cost. |
|
|
2262
|
+
| `[Agent] Quality Score` | number | No | Overall quality score (0.0-1.0) computed by the enrichment pipeline for this session. |
|
|
2263
|
+
| `[Agent] Sentiment Score` | number | No | User sentiment score (0.0-1.0) inferred from the conversation by the enrichment pipeline. |
|
|
2264
|
+
| `[Agent] Task Failure Reason` | string | No | Explanation of why the task failed when has_task_failure is true (e.g., 'chart data source unavailable'). |
|
|
2265
|
+
| `[Agent] Agent Chain` | string[] | No | Serialized JSON array of agent IDs representing the delegation chain in multi-agent flows. |
|
|
2266
|
+
| `[Agent] Project ID` | string | No | Amplitude project ID that owns the AI session being evaluated. |
|
|
2267
|
+
| `[Agent] Has User Feedback` | boolean | Yes | Whether the session received explicit user feedback (thumbs up/down, rating). |
|
|
2268
|
+
| `[Agent] User Score` | number | No | Aggregate user feedback score for the session (0.0-1.0). Present only when has_user_feedback is true. |
|
|
2269
|
+
| `[Agent] Agent Version` | string | No | Agent code version (e.g., 'v4.2'). Enables version-over-version quality comparison. |
|
|
2270
|
+
| `[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. |
|
|
2266
2271
|
|
|
2267
2272
|
### Server-Side: Topic Classification Properties
|
|
2268
2273
|
|
|
2269
2274
|
`[Agent] Topic Classification` is emitted automatically by the server-side enrichment pipeline — do not send this event from your code.
|
|
2270
2275
|
|
|
2271
|
-
| Property
|
|
2272
|
-
|
|
2273
|
-
| `[Agent] Session ID`
|
|
2274
|
-
| `[Agent] Agent ID`
|
|
2275
|
-
| `[Agent] Customer Org ID`
|
|
2276
|
-
| `[Agent] Evaluation Source` | string
|
|
2277
|
-
| `[Agent] Taxonomy Version`
|
|
2278
|
-
| `[Agent] Evaluated At`
|
|
2279
|
-
| `[Agent] Topic`
|
|
2280
|
-
| `[Agent] Selection Mode`
|
|
2281
|
-
| `[Agent] Primary`
|
|
2282
|
-
| `[Agent] Secondary`
|
|
2283
|
-
| `[Agent] Subcategories`
|
|
2284
|
-
|
|
2276
|
+
| Property | Type | Required | Description |
|
|
2277
|
+
|----------|------|----------|-------------|
|
|
2278
|
+
| `[Agent] Session ID` | string | Yes | Unique session identifier. All events in one conversation share the same session ID. |
|
|
2279
|
+
| `[Agent] Agent ID` | string | Yes | Identifies which AI agent handled the interaction (e.g., 'support-bot', 'houston'). |
|
|
2280
|
+
| `[Agent] Customer Org ID` | string | Yes | Organization ID for multi-tenant platforms. Enables account-level group analytics. |
|
|
2281
|
+
| `[Agent] Evaluation Source` | string | Yes | Source of the evaluation: 'user' (end-user feedback), 'ai' (automated/server pipeline), or 'reviewer' (human expert). |
|
|
2282
|
+
| `[Agent] Taxonomy Version` | string | Yes | Which taxonomy config version produced this enrichment (from ai_category_config.config_version_id). |
|
|
2283
|
+
| `[Agent] Evaluated At` | number | Yes | Epoch milliseconds when this enrichment/evaluation was computed. |
|
|
2284
|
+
| `[Agent] Topic` | string | Yes | Which topic model this classification is for (e.g., 'product_area', 'query_intent', 'error_domain'). |
|
|
2285
|
+
| `[Agent] Selection Mode` | string | Yes | Whether this topic model uses 'single' (MECE) or 'multiple' (multi-label) selection. |
|
|
2286
|
+
| `[Agent] Primary` | string | No | Primary classification value (e.g., 'charts', 'billing_issues'). |
|
|
2287
|
+
| `[Agent] Secondary` | string[] | No | Secondary classifications for multi-label topics. JSON array of strings. |
|
|
2288
|
+
| `[Agent] Subcategories` | string[] | No | Subcategories for finer classification within the primary topic (e.g., 'TREND_ANALYSIS', 'WRONG_EVENT'). JSON array of strings. |
|
|
2285
2289
|
<!-- END EVENT PROPERTY REFERENCE -->
|
|
2286
2290
|
|
|
2287
2291
|
## Event JSON Examples
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"_meta": {
|
|
3
|
-
"schema_version":
|
|
4
|
-
"generated_at": "2026-03-
|
|
3
|
+
"schema_version": 3,
|
|
4
|
+
"generated_at": "2026-03-25T22:00:10.579458+00:00",
|
|
5
5
|
"source": "langley/langley/llm_analytics/taxonomy_catalog.py",
|
|
6
6
|
"category": "Agent Analytics"
|
|
7
7
|
},
|
|
@@ -144,7 +144,7 @@
|
|
|
144
144
|
{
|
|
145
145
|
"name": "[Agent] Message Source",
|
|
146
146
|
"type": "string",
|
|
147
|
-
"description": "Origin of the message: 'user' for
|
|
147
|
+
"description": "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."
|
|
148
148
|
}
|
|
149
149
|
]
|
|
150
150
|
},
|
|
@@ -341,6 +341,21 @@
|
|
|
341
341
|
"type": "number",
|
|
342
342
|
"description": "Character length of the system prompt."
|
|
343
343
|
},
|
|
344
|
+
{
|
|
345
|
+
"name": "[Agent] Tool Definitions",
|
|
346
|
+
"type": "string",
|
|
347
|
+
"description": "Normalized JSON array of tool definitions sent to the LLM (when content_mode permits). Each entry contains name, description, and parameters schema."
|
|
348
|
+
},
|
|
349
|
+
{
|
|
350
|
+
"name": "[Agent] Tool Definitions Count",
|
|
351
|
+
"type": "number",
|
|
352
|
+
"description": "Number of tool definitions in the LLM request."
|
|
353
|
+
},
|
|
354
|
+
{
|
|
355
|
+
"name": "[Agent] Tool Definitions Hash",
|
|
356
|
+
"type": "string",
|
|
357
|
+
"description": "Stable SHA-256 hash of the normalized tool definitions. Always present regardless of content_mode; enables toolset change detection without exposing schemas."
|
|
358
|
+
},
|
|
344
359
|
{
|
|
345
360
|
"name": "[Agent] Temperature",
|
|
346
361
|
"type": "number",
|
package/dist/client.d.ts
CHANGED
|
@@ -83,6 +83,7 @@ declare class AmplitudeAI {
|
|
|
83
83
|
finishReason?: string | null;
|
|
84
84
|
toolCalls?: Array<Record<string, unknown>> | null;
|
|
85
85
|
reasoningContent?: string | null;
|
|
86
|
+
toolDefinitions?: Array<Record<string, unknown>> | null;
|
|
86
87
|
systemPrompt?: string | null;
|
|
87
88
|
temperature?: number | null;
|
|
88
89
|
maxOutputTokens?: number | null;
|
package/dist/client.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAsEA;;;;;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAsEA;;;;;;;;;;;;;;;;AA+M4B,cA/Mf,WAAA,CA+Me;EAAN,UAAA,UAAA,EA9ME,mBA8MF;EAUJ,UAAA,WAAA,EAAA,OAAA;EACL,UAAA,OAAA,EAvNQ,QAuNR;EASC,UAAA,cAAA,EA/Nc,aA+Nd;EAKQ,UAAA,oBAAA,EAnOY,GAmOZ,CAAA,MAAA,EAAA,MAAA,CAAA;EACT;EACO,qBAAA,EAAA,MAAA;EA+FN,WAAA,CAAA,OAAA,EAAA;IAGQ,SAAA,CAAA,EAlUN,mBAkUM;IACT,MAAA,CAAA,EAAA,MAAA;IA6CC,MAAA,CAAA,EA9WD,QA8WC;EAEQ,CAAA;EACT,QAAA,oBAAA;EAgCI,QAAA,iBAAA;EACC,IAAA,SAAA,CAAA,CAAA,EA9SC,mBA8SD;EAWJ,IAAA,MAAA,CAAA,CAAA,EArTE,QAqTF;EAEQ,WAAA,CAAA,SAAA,EAAA,MAAA,CAAA,EAAA,MAAA;EACT,gBAAA,CAAA,IAAA,EAAA;IAmCK,MAAA,EAAA,MAAA;IAQJ,OAAA,EAAA,MAAA;IAIQ,SAAA,EAAA,MAAA;IACT,OAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IA4BI,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IAQH,SAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IAEQ,aAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IACT,OAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IA0CC,aAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IAEQ,aAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IACT,YAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IA+BkB,WAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IAAoB,OAAA,CAAA,EAvbrC,MAubqC,CAAA,MAAA,EAAA,OAAA,CAAA,GAAA,IAAA;IAU9B,GAAA,CAAA,EAAA,MAAA,GAAA,IAAA;IAChB,cAAA,CAAA,EAAA,OAAA;IAQO,MAAA,CAAA,EAAA,OAAA;IAAM,eAAA,CAAA,EAAA,MAAA,GAAA,IAAA;kBArcA;aACL;sBACS;aACT;;;;;;;;;;;;;;;;;gBA6CG,MAAM;;sBAEA,MAAM;;;;;;;;;;kBAUV;aACL;;;;;;;;;cASC;;;;;sBAKQ;aACT;oBACO;;;;;;;;;;;;;;;;;;;cA+FN;;;sBAGQ;aACT;;;;;;;;;;;;;;;;;;cA6CC;;sBAEQ;aACT;;;;;;;iBAgCI;kBACC;;;;;;;;;;;cAWJ;;sBAEQ;aACT;;;;;kBAmCK;;;;;;;;cAQJ;;;;sBAIQ;aACT;;;;;iBA4BI;;;;;;;;cAQH;;sBAEQ;aACT;;;;;;;;;;;;;;;;;;cA0CC;;sBAEQ;aACT;;gCA+BkB,eAAoB;;aAU9B;;MAChB;YAQO"}
|
package/dist/client.js
CHANGED
|
@@ -186,6 +186,7 @@ var AmplitudeAI = class {
|
|
|
186
186
|
finishReason: opts.finishReason,
|
|
187
187
|
toolCalls: opts.toolCalls,
|
|
188
188
|
reasoningContent: opts.reasoningContent,
|
|
189
|
+
toolDefinitions: opts.toolDefinitions,
|
|
189
190
|
systemPrompt: opts.systemPrompt,
|
|
190
191
|
temperature: opts.temperature,
|
|
191
192
|
maxOutputTokens: opts.maxOutputTokens,
|