My First Agent

This guide walks you through building your first voice agent in under 10 minutes. You will create a web page with a single button that starts a conversation, shows the agent’s status, and displays the transcript in real time.

What you will build

A web page with:

A Start button that requests microphone permission and connects to Lokutor
A status indicator that shows whether the agent is listening, thinking, or speaking
A transcript panel that displays what the user said and what the agent replied

Prerequisites

An API key from app.lokutor.com
A modern browser with microphone support (Chrome, Firefox, Edge, Safari)
Node.js installed on your machine

Step 1: Create the project

npm create vite@latest my-first-agent -- --template vanilla-ts
cd my-first-agent
npm install @lokutor/sdk

Create a .env file:

VITE_LOKUTOR_API_KEY=sk_...

Step 2: Write the HTML

Replace index.html with:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My First Agent</title>
  <style>
    body { font-family: system-ui, sans-serif; max-width: 600px; margin: 40px auto; padding: 0 20px; }
    #status { font-weight: bold; padding: 8px 16px; border-radius: 8px; display: inline-block; margin-bottom: 16px; }
    .listening { background: #dbeafe; color: #1e40af; }
    .thinking { background: #fef3c7; color: #92400e; }
    .speaking { background: #d1fae5; color: #065f46; }
    .disconnected { background: #f3f4f6; color: #6b7280; }
    #transcript { border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; min-height: 200px; }
    .message { margin-bottom: 12px; }
    .user { color: #1e40af; }
    .agent { color: #065f46; }
    button { padding: 12px 24px; font-size: 16px; cursor: pointer; border-radius: 8px; border: none; background: #9e4851; color: white; }
    button:disabled { opacity: 0.5; cursor: not-allowed; }
  </style>
</head>
<body>
  <h1>My First Agent</h1>
  <button id="start">Start Conversation</button>
  <div id="status" class="disconnected">Disconnected</div>
  <div id="transcript"></div>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>

Step 3: Write the agent logic

Replace src/main.ts with:

import { VoiceAgentClient, VoiceStyle } from '@lokutor/sdk';

const startBtn = document.getElementById('start') as HTMLButtonElement;
const statusEl = document.getElementById('status') as HTMLDivElement;
const transcriptEl = document.getElementById('transcript') as HTMLDivElement;

const client = new VoiceAgentClient({
  apiKey: import.meta.env.VITE_LOKUTOR_API_KEY,
  prompt: 'You are a helpful and friendly AI assistant. Keep your answers short and conversational.',
  voice: VoiceStyle.F1,
  visemes: false,
});

client.on('transcription', (text: string) => {
  addMessage('user', text);
});

client.on('response', (text: string) => {
  addMessage('agent', text);
});

client.on('status', (status: string) => {
  statusEl.textContent = status;
  statusEl.className = status;
});

client.on('error', (error: any) => {
  console.error('Agent error:', error);
  statusEl.textContent = 'Error';
  statusEl.className = 'disconnected';
});

startBtn.addEventListener('click', async () => {
  startBtn.disabled = true;
  startBtn.textContent = 'Connecting...';

  try {
    await client.startManaged();
    startBtn.textContent = 'Connected';
  } catch (err) {
    console.error('Failed to start:', err);
    startBtn.disabled = false;
    startBtn.textContent = 'Start Conversation';
  }
});

function addMessage(role: 'user' | 'agent', text: string) {
  const div = document.createElement('div');
  div.className = `message ${role}`;
  div.textContent = role === 'user' ? `You: ${text}` : `Agent: ${text}`;
  transcriptEl.appendChild(div);
  transcriptEl.scrollTop = transcriptEl.scrollHeight;
}

Step 4: Run it

npm run dev

Open http://localhost:5173 in your browser, click Start Conversation, and speak into your microphone.

How it works

startManaged() requests microphone permission and opens a WebSocket to Lokutor
The SDK sends your configuration (prompt, voice, language) to the server
When you speak, the SDK streams microphone audio to the server
The server runs VAD, STT, LLM, and TTS, then streams audio back
The SDK plays the audio and emits events for transcription, response, and status

Next steps

Add visemes for lip-sync animation: set visemes: true and handle the visemes event. See SDK Visemes.
Give your agent tools so it can fetch data from external APIs. See SDK Tool Calling.
Optimize for latency by tuning steps and buffer sizes. See Best Practices.
Handle interruptions gracefully. See Guides / Handling Barge-in.

Complete code

You can find the full source for this guide in the examples repository.

Get Started

SDK

API Reference

Resources

What you will build

Prerequisites

Step 1: Create the project

Step 2: Write the HTML

Step 3: Write the agent logic

Step 4: Run it

How it works

Next steps

Complete code

​What you will build

​Prerequisites

​Step 1: Create the project

​Step 2: Write the HTML

​Step 3: Write the agent logic

​Step 4: Run it

​How it works

​Next steps

​Complete code

What you will build

Prerequisites

Step 1: Create the project

Step 2: Write the HTML

Step 3: Write the agent logic

Step 4: Run it

How it works

Next steps

Complete code