Forwarding to the frontend | LiveKit Documentation

Overview

Forward tool calls to a frontend app using RPC. This is useful when the data needed to fulfill the function call is only available at the frontend. You may also use RPC to trigger actions or UI updates in a structured way.

For instance, the following sections include a function that accesses the user's live location from their web browser.

Agent implementation

from livekit.agents import function_tool, get_job_context, RunContext

@function_tool()
async def get_user_location(
    context: RunContext,
    high_accuracy: bool
):
    """Retrieve the user's current geolocation as lat/lng.
    
    Args:
        high_accuracy: Whether to use high accuracy mode, which is slower but more precise
    
    Returns:
        A dictionary containing latitude and longitude coordinates
    """
    try:
        room = get_job_context().room
        participant_identity = next(iter(room.remote_participants))
        response = await room.local_participant.perform_rpc(
            destination_identity=participant_identity,
            method="getUserLocation",
            payload=json.dumps({
                "highAccuracy": high_accuracy
            }),
            response_timeout=10.0 if high_accuracy else 5.0,
        )
        return response
    except Exception:
        raise ToolError("Unable to retrieve user location")

import { llm, getJobContext } from '@livekit/agents';
import { z } from 'zod';

const getUserLocation = llm.tool({
  description: 'Retrieve the user\'s current geolocation as lat/lng.',
  parameters: z.object({
    highAccuracy: z.boolean().describe('Whether to use high accuracy mode, which is slower but more precise'),
  }),
  execute: async ({ highAccuracy }, { ctx }) => {
    try {
      const room = getJobContext().room;
      const participant = Array.from(room.remoteParticipants.values())[0]!;
      
      const response = await room.localParticipant!.performRpc({
        destinationIdentity: participant.identity,
        method: 'getUserLocation',
        payload: JSON.stringify({ highAccuracy }),
        responseTimeout: highAccuracy ? 10000 : 5000,
      });
      
      return response;
    } catch (error) {
      throw new llm.ToolError("Unable to retrieve user location");
    }
  },
});

Frontend implementation

The following example uses the JavaScript SDK. The same pattern works for other SDKs. For more examples, see the RPC documentation.

import { RpcError, RpcInvocationData } from 'livekit-client';

localParticipant.registerRpcMethod(
    'getUserLocation',
    async (data: RpcInvocationData) => {
        try {
            let params = JSON.parse(data.payload);
            const position: GeolocationPosition = await new Promise((resolve, reject) => {
                navigator.geolocation.getCurrentPosition(resolve, reject, {
                    enableHighAccuracy: params.highAccuracy ?? false,
                    timeout: data.responseTimeout,
                });
            });

            return JSON.stringify({
                latitude: position.coords.latitude,
                longitude: position.coords.longitude,
            });
        } catch (error) {
            throw new RpcError(1, "Could not retrieve user location");
        }
    }
);

Additional resources

RPC

Complete documentation on function calling between LiveKit participants.

Frontends

Build the client app that registers RPC methods and connects to the room.

Sessions (frontend)

Connect to rooms and access the participant for RPC registration.

Function tool definition

Define the agent-side tool and use RunContext, speech, and error handling.

Tool definition & use

Overview of tools, types, and related topics.