Agent Analytics sessions and user identity

An agent session is one unit of work your agent performs for a user, with a start, a set of turns, and an outcome, such as a ticket resolved, a task completed, or a conversation ended. Agent Analytics groups every event that produced that outcome under one [Agent] Session ID, and runs enrichment on the session after it closes. Decide your session ID and user ID before you instrument, because both are hard to change after rollout.

What a session is

A session groups the events that produced one outcome (User Message, AI Response, Tool Call, Score, Span) under one [Agent] Session ID. A session opens when your code first attaches events to that ID, stays open while activity keeps arriving, and closes either explicitly or by idle timeout. Enrichment (Session Record, signals, evaluator results) runs once per session, after it closes.

Every session belongs to a user. Pass the same user ID you use for product analytics. Refer to Set user IDs.

Choose a session ID

Pass the ID your application already has for "this unit of work."

If nothing fits, generate a stable UUID when the session starts and persist it wherever your app already keeps unit-of-work state, such as a ticket row, thread record, or request context. Threading the same ID through every request handler keeps turns in one session, so don't generate a fresh ID per request.

When the same user returns with a new goal, start a new session with a new ID. Never reuse a session ID across users: a shared or global session ID merges different users' conversations and breaks per-user analytics.

How sessions close

Enrichment runs only on closed sessions. If your [Agent] Session Record events aren't appearing, start here.

A session closes one of two ways:

1. Explicit close (recommended): Your code sends [Agent] Session End when the unit of work finishes: ticket resolved, call ended, run completed. With the AI SDK, call trackSessionEnd() (Node) or track_session_end() (Python), or open the session with a scope helper that closes it when the scope exits: run() in Node, the session() context manager in Python. Without the SDK, send the event yourself. Refer to Close sessions. Amplitude writes the close when the next ingestion batch processes the Session End event, so the [Agent] Session Record event typically arrives within 15 to 20 minutes. It can take longer while an org has an enrichment backlog.
2. Idle timeout (automatic fallback): If you never close explicitly, the server closes the session after 30 minutes of inactivity by default, measured from the last agent event received for the session. Any of these six [Agent] events resets the clock: User Message, AI Response, Tool Call, Session End, Score, and Span. Server-generated enrichment events, including Session Record and Evaluator Result, don't. Ingestion runs on a cycle, so the close lands within roughly 15 minutes after the idle window elapses.

Every Session Record carries [Agent] Close Reason, either explicit_close or timeout, so you can monitor how often the idle timeout closes your sessions.

Idle timeout values

Sessions without a per-session override also close after 24 hours regardless of activity. Setting any override (a positive value or -1) exempts the session from that cap.

Set the timeout too low and a long pause closes the session early. Follow-up events still attach and Amplitude stores them, but they land after enrichment has run, so they never reach the Session Record. Use -1 when quiet stretches are normal and unbounded, such as a ticket idle over a weekend or a long-running background job, where any fixed timeout would eventually split a real job. The tradeoff is that a session your app forgets to close stays open and unenriched until the 90-day backstop closes it.

Two caveats on -1:

• Agents with enrichment disabled close on the org default schedule.
• The 90-day limit counts from when the session started, so a session that stays active for more than 90 days straight never auto-closes.

To set an override, refer to Configure session timeouts.

Set user IDs

Amplitude counts unique users by combining three identifiers (device ID, user ID, and Amplitude ID) into a single profile across anonymous sessions, sign-ins, and multiple devices. Send a stable user ID as soon as a person authenticates, so anonymous events on the same device merge into one profile and your active-user counts stay accurate.

When every [Agent] event carries your stable user ID, you can build funnels, cohorts, and retention charts that span agent and product behavior.

Two rules keep a single user from splitting into two:

• Never pass a placeholder user ID. Placeholders include "anonymous", an empty string, or a temporary ID. You can't change a user ID once it's set, so a placeholder creates a permanent separate user that doesn't merge later. Omit the user ID instead. Anonymous activity merges into the known identity through standard identity resolution once the user identifies.
• Reuse the same device ID across a pre-account session. If your backend generates a new device ID per request, the identity merge breaks. If possible, read the device ID from the Browser SDK and forward it.

Decide your ID strategy on day one of instrumentation.