Session management

Overview

Building an agent frontend requires coordinating several moving parts: fetching authentication tokens, connecting to a room, dispatching an agent, and then interacting with it through media, data, and state APIs. The Session API handles this orchestration for you, giving you a single entry point that manages the full lifecycle of a 1:1 agent interaction.

Without Session, you need to generate tokens manually, call Room.connect, set up agent dispatch configuration, and manage cleanup yourself. Session wraps all of this into a simple start/end interface while still giving you access to lower-level APIs when needed.

Session is available on Web, Swift, Kotlin, Flutter, and React Native.

Session lifecycle

A session has four stages:

1. Create: Initialize a session with a TokenSource and options including the agent name. TokenSource handles token fetching, caching, and refreshing — see the Authentication guide for setup.
2. Start: Call session.start() to fetch a token, connect to a room, and dispatch the agent.
3. Interact: The agent joins the room and begins the conversation. Your frontend can access agent state, media tracks, transcriptions, and data through the session.
4. End: Call session.end() to disconnect from the room and clean up resources.

What you get inside a session

Once a session is started and the agent has joined, your frontend has access to the full set of realtime APIs for interacting with the agent.

Agent state

The agent moves through a lifecycle of states — connecting, listening, thinking, speaking — that your frontend can observe. Use these states to drive UI updates, like showing a visual indicator when the agent is thinking or disabling the microphone when the agent is speaking. State getters like canListen and isFinished simplify common UI decisions. See Agent state for details.

Media tracks

Your frontend and agent exchange audio and video over media tracks. A simple voice agent subscribes to the user's microphone and publishes its own audio. Agents with vision capabilities can subscribe to the user's camera or screen share. See Realtime media and data for details.

Transcriptions

Text transcriptions of both agent and user speech are available as text streams. Use these to build chat interfaces, display captions, or maintain conversation history. See Text streams for details.

Data and state synchronization

Beyond media and transcriptions, your frontend and agent can exchange arbitrary data. Use byte streams for files and images, RPC for request-response interactions, and state synchronization for shared key-value data that stays in sync across participants. See Realtime media and data for an overview.

Usage examples

'use client';
import { useEffect } from 'react';
import { useSession, SessionProvider } from '@livekit/components-react';
import { TokenSource } from 'livekit-client';

const tokenSource = TokenSource.sandboxTokenServer('<your sandbox token server id>');

export function App() {
  const session = useSession(tokenSource, { agentName: 'my-agent' });

  useEffect(() => {
    session.start();
    return () => {
      session.end();
    };
  }, []);

  return (
    <SessionProvider session={session}>
      {/* Your app components */}
    </SessionProvider>
  );
}

import LiveKitComponents

let tokenSource = SandboxTokenSource(id: "<your sandbox token server id>")
let session = Session.withAgent("my-agent", tokenSource: tokenSource)

// Start the session
await session.start()

// End the session
await session.end()

val tokenSource = remember {
    TokenSource.fromSandbox("<your sandbox token server id>")
}
val session = rememberSession(tokenSource = tokenSource)

LaunchedEffect(Unit) {
    session.start()
}

// End the session when done
session.end()

import 'package:livekit_client/livekit_client.dart' as sdk;

final tokenSource = sdk.SandboxTokenSource("<your sandbox token server id>");
final session = sdk.Session.fromConfigurableTokenSource(
  tokenSource,
  const TokenRequestOptions(agentName: "my-agent"),
);

await session.start();

// End the session when done
await session.end();

Using AgentSessionProvider

If you're building with Agents UI components, the AgentSessionProvider component wraps the session from useSession and provides session context to all child components. Agents UI components like AgentControlBar, AgentChatTranscript, and the audio visualizers require this provider as an ancestor.

'use client';
import { useSession } from '@livekit/components-react';
import { AgentSessionProvider } from '@/components/agents-ui/agent-session-provider';
import { TokenSource } from 'livekit-client';

const tokenSource = TokenSource.sandboxTokenServer('<your sandbox token server id>');

export function App() {
  const session = useSession(tokenSource, { agentName: 'my-agent' });

  return (
    <AgentSessionProvider session={session}>
      {/* Agents UI components can access session context here */}
    </AgentSessionProvider>
  );
}

Next steps