Skip to content

Client Application Developer Guide

This guide walks you through integrating a client application with the LiveKit Platform Service (LKPS) to start real-time sessions with AI agents.

Table of Contents

  1. Overview
  2. Prerequisites
  3. How Session Start Works
  4. Step 1 — Obtain an Entra ID Access Token
  5. Step 2 — Start a Session
  6. Step 3 — Connect to the LiveKit Room
  7. Session Start API Reference
  8. Troubleshooting
  9. Next Steps

Overview

As a client application developer, your workflow is:

  1. Authenticate your application with Microsoft Entra ID to obtain an access token.
  2. Call LKPS to start a session — LKPS creates a LiveKit room, issues a participant token, and dispatches the target agent.
  3. Connect to the LiveKit room using the participant token and the LiveKit client SDK (JavaScript, React, etc.).
  4. Communicate with the AI agent in real time via WebRTC (audio, video, data).

Tip

For detailed LiveKit client SDK documentation including connection handling, track management, and React components, see the LiveKit Client SDK Documentation ⧉.

Prerequisites

Before integrating your client application, ensure you have completed:

How Session Start Works

Session Start Flow

Step 1 — Obtain an Entra ID Access Token

Your application must acquire an Entra ID token targeting the LKPS audience before calling the session start API.

Required scope (use the value matching your target environment):

Environment Scope
Non-Production api://livekit-platform-service-np.int.bayer.com/.default
Production api://livekit-platform-service.int.bayer.com/.default

There are multiple ways to obtain an Entra access token depending on your setup:

Method Use Case
MSAL React (@azure/msal-react) React SPAs with user sign-in
MSAL Browser (@azure/msal-browser) Vanilla JS/TS SPAs
Client Credentials Backend services (server-to-server)

Example using MSAL React:

import { useMsal } from "@azure/msal-react";

const { instance, accounts } = useMsal();

const tokenResponse = await instance.acquireTokenSilent({
  scopes: ["api://livekit-platform-service-np.int.bayer.com/.default"], // use -np for non-prod
  account: accounts[0],
});

const accessToken = tokenResponse.accessToken;

Tip

For complete MSAL setup guides, see: - MSAL React ⧉ — React applications - MSAL Browser ⧉ — Vanilla JS/TS

Step 2 — Start a Session

Call the LKPS session start endpoint with your Entra token and the target agent's Entra App ID:

const LKPS_URL = "https://eu-livekit-platform-service-np.int.bayer.com";

interface SessionData {
  room_name: string;
  livekit_url: string;
  participant_token: string;
}

async function startSession(agentId: string, accessToken: string): Promise<SessionData> {
  const response = await fetch(`${LKPS_URL}/api/session/start`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_entra_app_id: agentId,
      metadata: { language: "en" },
    }),
  });

  if (!response.ok) {
    throw new Error(`Session failed: ${response.status}`);
  }

  return response.json();
}

Step 3 — Connect to the LiveKit Room

Use the livekit_url and participant_token from the session response to connect with the LiveKit React SDK:

npm install @livekit/components-react livekit-client

import { LiveKitRoom, RoomAudioRenderer, ControlBar } from "@livekit/components-react";
import "@livekit/components-styles";

function AgentSession({ session }: { session: SessionData }) {
  return (
    <LiveKitRoom
      serverUrl={session.livekit_url}
      token={session.participant_token}
      connect={true}
      audio={true}
    >
      <RoomAudioRenderer />
      <ControlBar />
    </LiveKitRoom>
  );
}

Tip

For complete examples, see LiveKit React Components ⧉ and LiveKit React Examples ⧉.

Session Start API Reference

POST /api/session/start
Content-Type: application/json
Authorization: Bearer <entra_jwt>

Request body:

Field Type Required Description
agent_entra_app_id string (UUID) Yes The target agent's Entra App Registration Client ID
metadata object No Custom key-value pairs forwarded to the agent (max 50 keys, 10 KB)

Response 200 OK:

Field Description
room_name Unique room identifier (format: {cwid}-{agent_entra_app_id}-{timestamp}-{hex})
livekit_url LiveKit server WebSocket URL — connect here with the participant token
participant_token Signed LiveKit JWT with participant grants and agent dispatch configuration

Room configuration embedded in the token:

Setting Value Description
maxParticipants 2 One participant + one agent
syncStreams true Synchronize audio/video streams
departureTimeout 30s Room stays open 30 seconds after a participant leaves
agents [{ agentName: agent_entra_app_id }] LiveKit automatically dispatches the named agent

Error responses:

Code Error Cause
400 Bad Request Missing or invalid agent_entra_app_id, or metadata exceeds limits
403 Forbidden Client not authorized for the target agent (see Client-to-Agent Authorization)
404 Not Found Agent is not registered/connected
500 Internal Server Error Session creation failed

Troubleshooting

Common Errors

Error Possible Cause Resolution
400: "agent_entra_app_id" is required Missing agent ID in request body Include agent_entra_app_id as a valid UUID
403: You are not authorized to access this agent Client not in agent's preAuthorizedApplications Ask the agent owner to add your Client ID (see Client-to-Agent Authorization)
404: Agent with app ID '...' is not connected Agent is offline Verify the agent is running and registered
401 Unauthorized (from Ocelot) Invalid or expired Entra token Refresh your Entra token; verify the audience
Connection drops after joining room Participant token expired Tokens are valid for the session duration; ensure you connect promptly after receiving the token

Debugging Tips

  1. Check the LKPS health endpoint to verify the service is running: 
    curl https://eu-livekit-platform-service-np.int.bayer.com/api/health
  2. Verify your Entra token is valid and targets the correct audience using jwt.ms ⧉.
  3. Start with non-production environments for testing before moving to production.

Tip

For LiveKit connection issues, see LiveKit Client SDK Error Codes ⧉ and Handling Device Failures ⧉.

Next Steps

Next Guide
Full LKPS API reference LiveKit Platform Service — API Reference
LiveKit client SDK docs LiveKit Client SDK ⧉
LiveKit React components LiveKit React Components ⧉
Configure client authorization Client-to-Agent Authorization
View all environment URLs Environments & URLs