Build a LiveKit voice agent with Scalekit AgentKit tools

A voice agent that answers “what’s on my calendar?” needs a Google OAuth token scoped to that specific user. LiveKit handles the realtime voice pipeline — speech-to-text, the LLM turn, text-to-speech, turn detection — but it has no built-in concept of per-user third-party credentials. Wire that up yourself and you’re building a token vault, a refresh cycle, and a way to keep both out of reach of the browser and the LLM, before you’ve written a single line of agent logic.

Scalekit AgentKit removes that layer. It stores one OAuth session per connector per user and exposes a single executeTool call that runs any of 20,000+ connector tools on that user’s behalf. This cookbook connects a LiveKit Node.js agent to AgentKit directly — no MCP server, no separate auth service — and shows the one non-obvious part: getting the identity of the person talking to the agent from the browser to the worker process without ever exposing a credential.

• A Next.js route that dispatches a LiveKit agent into a room and mints a browser access token, carrying a Scalekit connection identifier through LiveKit’s dispatch metadata — the only channel between the two.
• A standalone LiveKit agent worker (a separate Node process, not a Next.js route) that reads that identifier from ctx.job.metadata and calls scalekit.actions.executeTool() directly when the LLM decides to check the calendar.
• A pattern that generalizes: swap googlecalendar_list_events for any AgentKit tool name and the identity-passing mechanism stays identical.

The complete, working source (including the Next.js UI, both API routes, and the agent) is in livekit-scalekit-voice-agent.

• A LiveKit Cloud project — copy LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET from Settings → Keys. No lk CLI login is required; the app and the agent both read these three values from the environment.
• A Scalekit account with AgentKit enabled and a googlecalendar connection that shows as Active for the identifier you’ll test with. See Configure a connection.
• Node.js 20.11+ — the agent worker uses import.meta.filename, which older Node versions don’t have.

1. Install dependencies

   Section titled “Install dependencies”

   This is a two-process app: a Next.js frontend/API layer, and a standalone agent worker that runs as a separate tsx process.

   npm install @scalekit-sdk/node livekit-server-sdk livekit-client @livekit/components-react @livekit/agents zod next react react-dom
   npm install -D tsx typescript

   @livekit/agents is the Node Agents SDK — it ships the voice.AgentSession pipeline, the defineAgent/cli.runApp worker entrypoint, and the llm.tool() helper for function tools. @scalekit-sdk/node is the same Scalekit client either side of this app uses to call AgentKit.

2. Set environment variables

   Section titled “Set environment variables”

   Create .env.local at the project root:

   # Scalekit — Settings → API Credentials in your Scalekit dashboard
   SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.com
   SCALEKIT_CLIENT_ID=skc_your_client_id
   SCALEKIT_CLIENT_SECRET=your_client_secret
   
   # Development only: the identifier getSignedInUser() returns until you connect your auth
   TEST_IDENTIFIER=user@example.com
   
   # LiveKit Cloud — Settings → Keys
   LIVEKIT_URL=wss://your-project.livekit.cloud
   LIVEKIT_API_KEY=your_api_key
   LIVEKIT_API_SECRET=your_api_secret

   TEST_IDENTIFIER stands in for whatever your app uses to identify a signed-in user. It’s only used in development. In production the identifier comes from the authenticated session — see Production notes.

3. Carry the identifier through LiveKit dispatch metadata

   Section titled “Carry the identifier through LiveKit dispatch metadata”

   The Next.js route that starts a call is the only place that decides which Scalekit identity the agent runs as. It takes the identifier from the signed-in user on the server, never from the request body, and sends it — not a token — inside LiveKit’s own metadata field on the agent dispatch.

   First, a stand-in for your app’s session lookup. Replace its body with however your app reads the signed-in user from a request:

   export async function getSignedInUser(_req: Request): Promise<{ identifier: string } | null> {
     // Replace this with your app's session lookup, and return null when no one is signed in.
     if (process.env.NODE_ENV !== 'production' && process.env.TEST_IDENTIFIER) {
       return { identifier: process.env.TEST_IDENTIFIER };
     }
     throw new Error('getSignedInUser is not connected to your auth yet');
   }

   Then the route:

   1
   import { randomUUID } from 'node:crypto';
   2
   import { NextResponse } from 'next/server';
   3
   import { AccessToken, AgentDispatchClient } from 'livekit-server-sdk';
   4
   import { getSignedInUser } from '@/lib/auth';
   5
   
   6
   const AGENT_NAME = 'scalekit-voice-agent';
   7
   
   8
   export async function POST(req: Request) {
   9
     const user = await getSignedInUser(req);
   10
     if (!user) {
   11
       return NextResponse.json({ error: 'Not signed in' }, { status: 401 });
   12
     }
   13
   
   14
     const livekitUrl = process.env.LIVEKIT_URL!;
   15
     const apiKey = process.env.LIVEKIT_API_KEY!;
   16
     const apiSecret = process.env.LIVEKIT_API_SECRET!;
   17
   
   18
     const identifier = user.identifier;
   19
     const roomName = `voice-${randomUUID()}`;
   20
     const metadata = JSON.stringify({ scalekitConnectionId: identifier });
   21
   
   22
     const dispatchClient = new AgentDispatchClient(livekitUrl, apiKey, apiSecret);
   23
     await dispatchClient.createDispatch(roomName, AGENT_NAME, { metadata });
   24
   
   25
     const at = new AccessToken(apiKey, apiSecret, { identity: `user-${randomUUID()}` });
   26
     at.addGrant({ roomJoin: true, room: roomName });
   27
     const token = await at.toJwt();
   28
   
   29
     return NextResponse.json({ roomName, token, url: livekitUrl });
   30
   }

   createDispatch(roomName, agentName, { metadata }) tells LiveKit’s cloud infrastructure to route this room to a worker registered under agentName — you’ll register the same string in the next step. metadata is a plain JSON string; LiveKit stores it and hands it to the worker’s job context untouched. The browser only ever receives token (a room-join JWT) and roomName — never a Scalekit credential.

4. Read the identifier and call the tool directly

   Section titled “Read the identifier and call the tool directly”

   The agent worker is a separate file, run as its own process — not a Next.js route. It parses the same metadata shape the dispatch call sent, then wires a Scalekit-backed function tool:

   1
   import { ScalekitClient } from '@scalekit-sdk/node';
   2
   import { cli, defineAgent, llm, ServerOptions, voice, type JobContext } from '@livekit/agents';
   3
   import { z } from 'zod';
   4
   
   5
   const scalekit = new ScalekitClient(
   6
     process.env.SCALEKIT_ENVIRONMENT_URL!,
   7
     process.env.SCALEKIT_CLIENT_ID!,
   8
     process.env.SCALEKIT_CLIENT_SECRET!,
   9
   );
   10
   
   11
   const entry = async (ctx: JobContext): Promise<void> => {
   12
     await ctx.connect();
   13
   
   14
     const metadata = JSON.parse(ctx.job.metadata || '{}') as { scalekitConnectionId?: string };
   15
     const identifier = metadata.scalekitConnectionId;
   16
     if (!identifier) {
   17
       // Only the start route sets this. Don't fall back to a default user.
   18
       throw new Error('Dispatch metadata has no scalekitConnectionId');
   19
     }
   20
     console.log(`[scalekit-voice-agent] job=${ctx.job.id} room=${ctx.room.name} identifier=${identifier}`);
   21
   
   22
     const googlecalendar_list_events = llm.tool({
   23
       description: "List events from the user's Google Calendar. Use this when the user asks about their schedule.",
   24
       parameters: z.object({
   25
         calendar_id: z.string().optional().describe("Defaults to 'primary'."),
   26
       }),
   27
       execute: async ({ calendar_id }) => {
   28
         const result = await scalekit.actions.executeTool({
   29
           connector: 'googlecalendar',
   30
           identifier,
   31
           toolName: 'googlecalendar_list_events',
   32
           toolInput: { calendar_id: calendar_id ?? 'primary' },
   33
         });
   34
         return result.data ?? result;
   35
       },
   36
     });
   37
   
   38
     const agent = new voice.Agent({
   39
       instructions: "You are a helpful voice assistant. Check the user's calendar when asked.",
   40
       tools: { googlecalendar_list_events },
   41
     });
   42
   
   43
     const session = new voice.AgentSession({
   44
       llm: 'openai/gpt-4o-mini',
   45
       stt: 'assemblyai/universal-streaming',
   46
       tts: 'cartesia/sonic-2',
   47
     });
   48
   
   49
     await session.start({ agent, room: ctx.room });
   50
     await session.generateReply({ instructions: 'Greet the user and offer to help with their calendar.' });
   51
   };
   52
   
   53
   export default defineAgent({ entry });
   54
   
   55
   cli.runApp(new ServerOptions({ agent: import.meta.filename, agentName: 'scalekit-voice-agent' }));

   Three things worth naming explicitly:

   • llm.tool()’s object key is the tool’s name — there’s no name field inside the call. The LLM sees the tool as googlecalendar_list_events because that’s the key in the tools: { googlecalendar_list_events } map.
   • voice.Agent is a plain constructor — new voice.Agent({ instructions, tools }). There’s no static factory method.
   • The three model strings are LiveKit Inference identifiers, not your own API keys. They route STT/LLM/TTS through LiveKit Cloud’s gateway, billed to your LiveKit project — no separate OpenAI, AssemblyAI, or Cartesia account needed to get this running.

   agentName: 'scalekit-voice-agent' must match the string AgentDispatchClient.createDispatch() used in step 3 exactly. That’s the only thing connecting the two processes — get it wrong and the dispatch succeeds, a room gets created, and the agent simply never joins it.

5. Run both processes

   Section titled “Run both processes”

   npm run dev

   npx tsx watch --env-file=.env.local agent/src/agent.ts dev

   --env-file matters here: Next.js loads .env.local automatically, but a plain tsx process doesn’t unless you tell it to.

Confirm the identity actually reaches the agent before wiring up a browser. Hit the dispatch route directly. In development, getSignedInUser() returns TEST_IDENTIFIER:

curl -X POST http://localhost:3000/api/livekit/start

The agent worker’s terminal should log that identifier within a couple of seconds:

[scalekit-voice-agent] job=AJ_giyT9fjSxPg8 room=voice-2eb7cc3d-... identifier=user@example.com

If that line doesn’t appear, the agent never received the dispatch — see Common mistakes below before checking anything else. Once it does, open your frontend, click Start, and ask “what’s on my calendar today?” — the agent should call executeTool, get back real calendar data, and speak a summary.

No token ever reaches the browser or the LLM. The Next.js route returns only roomName, url and a room-join JWT scoped to one room — never a Scalekit credential or the identifier. The agent worker is the only process that ever constructs a ScalekitClient, and executeTool()’s result — plain calendar data — is the only thing that reaches the LLM.

Tools run through executeTool(). The LiveKit Node Agents SDK (@livekit/agents 1.4.11) has no MCP toolset, so the agent calls executeTool() directly, as shown above.

Connect getSignedInUser() to your auth before you deploy. TEST_IDENTIFIER is a development convenience, and the stub throws in production until you replace it. Read the identifier from the signed-in user’s session on the server that handles the dispatch request, never from a field the client sends.

Add more tools by changing one string. The connector/toolName pair in executeTool() is the only connector-specific part of this code. Swap googlecalendar_list_events for any of 400+ AgentKit connectors and the identity-passing mechanism is unchanged.

• Configure more connectors — extend beyond Google Calendar to Gmail, Slack, or GitHub.
• Connected accounts — check connection status and revoke access programmatically.
• AgentKit quickstart — connect your first user in under five minutes.
• LiveKit Agents docs — turn detection, interruption handling, and telephony/SIP.