Configure Agent Analytics session timeouts

By default, Agent Analytics closes a session after 30 minutes without agent events, and caps any session at 24 hours. Override the idle timeout per session when your jobs have long natural gaps, such as support tickets that wait on a human, so a pause doesn't close the session before the work is done.

Choose the value first. Idle timeout values describes what 30, larger values, and -1 do, and the tradeoff of setting the timeout too low or too high. Where possible, close sessions explicitly instead of relying on the timeout.

Set the override with the AI SDK

Set idleTimeoutMinutes (Node) or idle_timeout_minutes (Python) when you open the session, and also add an idle_timeout_minutes key to the agent's context. The server reads the context key even for sessions that never close explicitly, so setting both makes sure the override takes effect.

const agent = ai.agent('support-bot', {
  context: { idle_timeout_minutes: 240 },   // read even without an explicit close
});
const session = agent.session({
  userId,
  sessionId: ticketId,
  idleTimeoutMinutes: 240,                  // the session-level parameter
});

Set the override without the AI SDK

Add an idle_timeout_minutes key to the [Agent] Context JSON on any event in the session. The first value wins, and the server reads it even for sessions that never receive a Session End. If you send a Session End, also set [Agent] Session Idle Timeout Minutes on it to the same value.

amplitude.track('[Agent] User Message', {
  '[Agent] Session ID': ticketId,
  '[Agent] Turn ID': 1,
  '[Agent] Trace ID': traceId,
  '[Agent] Agent ID': 'support-bot',
  '[Agent] Message ID': messageId,
  '[Agent] Context': JSON.stringify({ idle_timeout_minutes: 240 }),
  $llm_message: { text: redactedText },
});

// When the ticket resolves:
amplitude.track('[Agent] Session End', {
  '[Agent] Session ID': ticketId,
  '[Agent] Agent ID': 'support-bot',
  '[Agent] Session Idle Timeout Minutes': 240,
});

Don't build your own short idle timer. Rotating session IDs after a few quiet minutes splits one conversation into several sessions: enrichment judges partial conversations, task completion looks artificially low, and because billing is per agent session, one conversation bills as several. If your product defines sessions by inactivity, set a matching [Agent] Session Idle Timeout Minutes and keep the window generous. Refer to Should I build my own client-side idle timer to end sessions? in the FAQ.

Check how sessions closed

Every [Agent] Session Record carries [Agent] Close Reason, either explicit_close or timeout. Chart Session Records grouped by Close Reason to see how often the idle timeout closes your sessions. A high share of timeout on jobs with a known end can mean your code isn't sending Session End. Refer to Troubleshoot Agent Analytics setup.