Agent insights

Overview

LiveKit Cloud includes a built-in observability stack for voice agents. When you enable Agent observability for a project, LiveKit Cloud collects transcripts, traces, logs, and audio recordings for each session. The Agent insights tab on each session aligns them on a single timeline, so you can play back a call and see what the agent did at each point.

Availability

Agent observability is available on all LiveKit Cloud plans, and works for agents deployed to LiveKit Cloud and for self-hosted agents that connect to LiveKit Cloud media servers. It does not work with self-hosted media servers or entirely self-hosted deployments. For complete information on pricing, see the LiveKit Cloud pricing page .

To enable agent observability, ensure the following conditions are met:

1. The Agent observability feature is enabled within the Observability settings section in your project settings .
2. Your agent uses the latest version of the LiveKit Agents SDK
   • Python SDK version 1.3.0 or higher
   • Node.js SDK version 1.0.18 or higher
   • Or the LiveKit Agent Builder

The project setting governs every session. To change what a single session collects, pass the record parameter to AgentSession.start(). See Session recording options.

Permissions

Only project admins can read the Agent insights data for a session. To give a teammate access, change their role to Admin in your project settings. A share link doesn't give access to other roles. Only project admins and, if you allow it, LiveKit support can open it.

Where to find session data

The data that agent observability collects appears at three levels in the LiveKit Cloud dashboard:

• Project: open the Agents  page to see traffic, latency, and model usage across every agent in the project.
• Agent: select an agent on the Agents page to see the same charts, scoped to that agent. An agent page also shows how the time in an average reply divides between pipeline stages, and charts for connection latency, uptime, and average load.
• Session: open a session on the Sessions  page and select the Agent insights tab to see the timeline for a single call.

Agent insights compared to the other session views

A session has several views, and they answer different questions. Switch between them from the session ID in the breadcrumb.

Session analytics and Session events come from the LiveKit media servers, so they're present for any session and visible to every project role. Agent insights comes from telemetry your agent uploads, so it needs agent observability enabled and is limited to project admins.

The data region for your project determines where these recordings, transcripts, and traces are stored. It's set when you create the project and can't be changed afterward. To keep agent observability data in the EU, select the EU data region at project creation. To learn more, see Data residency.

What the timeline includes

The timeline for each agent session combines transcripts, traces, logs, audio clips, and the per-event metrics emitted by the LiveKit Agents SDK.

Ingestion timing

Different parts of a session arrive at different times:

• Traces and logs stream to LiveKit Cloud while the session runs. Open a live session to see the spans and log lines that arrived so far, and reload the page to see newer ones.
• Transcripts and the audio recording are held in the agent process and uploaded after the session ends, because both are assembled from the whole call. If a session that has ended still shows no data, see Troubleshooting.

The SDK flushes the remaining telemetry after your on_session_end callback returns, so a long callback delays the upload. The session_end_timeout agent server option bounds how long that callback can run.

Transcripts

Turn-by-turn transcripts for the user and agent. Tool calls and handoffs also appear on the timeline so you can correlate them with traces and logs. Select any of them to see the metadata and metrics in a side panel.

Session traces and metrics

Traces capture the execution flow of a session, broken into spans for every stage of the voice pipeline. Spans cover user and agent turns, STT-LLM-TTS pipeline steps, tool calls, and more. Each span includes metrics and metadata, such as token counts, durations, and speech identifiers, that you can inspect in a side panel when you select the span.

For the full list of spans and what each one records, see Session traces and metrics.

Logs

Runtime logs from the agent server are uploaded to LiveKit Cloud and available in the session timeline. LiveKit Cloud collects whatever your agent server emits, so the log level you configure for the agent server is also the level collected for observability. By default, this is info and higher. See Log levels for details.

These logs only cover activity within a session. Server-level events that happen outside of a session (such as crashes, startup failures, and dispatch errors) aren't captured here. To collect those, set up a log drain.

Session metrics

The Metrics tab summarizes the performance of one session: how the conversation flowed, how long each stage of the voice pipeline took, and what the session used in models, tokens, and speech. Tiles that need audio, such as Interruptions and Speech usage, don't appear for text-only sessions.

Working with charts

Charts in Agent insights are interactive, and what a selection does depends on where the chart is. The current drawer and filter state is encoded in the URL as query parameters, so copying the URL shares the exact view you're looking at.

In a session timeline

Charts on the Metrics tab are keyed to turns. Select a turn in Agent turn latency, or an outlier point in Latency distribution, and playback moves to that turn and marks it on the charts. Then switch to Transcript, Traces, or Session logs to see what happened at that point. Selecting a span or item in any of those tabs also marks its turn on the charts.

In an agent dashboard

Charts on the Agents  page drill down to sessions. Selecting part of a chart opens a drawer listing the sessions behind it. A latency chart ranks those sessions by their slowest turn for that stage. A count chart, such as interruption rate, lists only the sessions that recorded one.

Drag across the x-axis of a time-series chart to select a window. Zoom to selection applies that window to the whole page, so every other chart rescales to match, and View sessions opens the sessions drawer for it.

Compare agents side by side

On the Agents  page, select two or more agents in the Agents table and select Compare agents. A drawer opens with the selected agents ranked slowest first, with sessions per bucket and E2E metrics. Charts in the drawer drill down to the selected agents only, and you can compare up to 25 agents at once.

Audio recordings

Audio recordings are collected for each agent session and play back in the browser, in sync with the timeline. They're recorded in the agent process and uploaded to LiveKit Cloud after the session ends, along with the transcripts. Recordings include both the agent and the user audio, on separate channels. To save a recording, select Download data on the session. To learn more, see Download a session.

Recording limitations

The recorder taps the audio input and output of the agent session, which sets what it can capture:

• If noise cancellation is enabled, user audio is recorded after noise cancellation is applied. The recording reflects what the STT or realtime model heard.
• Audio from a background audio player is published as a separate track and doesn't pass through the session audio output, so it isn't in the recording. Audio you speak with session.say() is in the recording, so use it for content that must be captured, such as a disclosure.
• When the user interrupts, playback stops early, so agent audio can end mid-sentence. The transcript for that turn keeps only the text that played. See Missing parts of a session.

Agent insights audio compared to LiveKit Egress

Agent insights audio and LiveKit Egress are separate pipelines, and neither one populates the other. Agent insights audio is recorded by the agent and uploaded to LiveKit Cloud, where it's subject to the retention window. It never reaches your own storage bucket. An Egress recording writes to your bucket, and it doesn't add audio to the Agent insights waveform or player.

You can save one Agent insights recording at a time with Download data. Use Egress instead when you need every call delivered to your own storage, video as well as audio, or audio captured before noise cancellation. To learn more, see Record audio and video.

Download a session

Within the dashboard, an admin can select Download data on a session to save it as a ZIP archive. This is how you keep one session past its retention window.

The archive holds one file per category the session recorded, named <project ID>_<session ID>_<category>:

A category the session didn't record is absent from the archive, so a session that ran with record={"audio": False} has no audio file.

Retention window

By default, agent observability data is deleted 30 days after a session ends. After that, the session reports Agent insights expired. To keep a session for longer, select Download data on it before it expires. To keep every session, write the data somewhere you control while sessions run: see Accessing data outside the dashboard.

This window covers what LiveKit stores. Models you call through LiveKit Inference are zero data retention on every plan, so model providers don't retain or train on the data you send them.

PII redaction

To remove personally identifiable information from session transcripts, audio, and telemetry before it's stored, enable PII redaction for your project. Redaction is bundled with agent observability at no additional cost and is off by default.

Sharing sessions with LiveKit support

You can share insights for a specific agent session with LiveKit support. When sharing is enabled, LiveKit support staff can access the session timeline, transcripts, traces, logs, and audio recordings to help troubleshoot issues.

If you haven't already, work through Troubleshooting first. It covers the common causes of missing and incomplete session data.

To enable or disable sharing with LiveKit support, follow these steps:

1. Sign in to the LiveKit Cloud dashboard and navigate to the Sessions  page.
2. Select the session you want to share.
3. Select the Agent insights tab → select Share.
4. Select Allow LiveKit support to access this page to turn sharing with LiveKit support on or off.
5. Select Copy link to copy the share link to the clipboard.
6. Email the link to LiveKit support.

The sharing link for a session remains active until the retention period ends. To stop sharing the session before then, you must disable it explicitly by repeating the previous steps.

Additional resources