migrate to vite/vitest, update tests and docs

Author: rektdeckard

AGENTS.md

@@ -46,6 +46,16 @@ If you are another agentic IDE, refer to your own documentation for how to insta
 
 Voice AI agents are highly sensitive to excessive latency. For this reason, it's important to design complex agents in a structured manner that minimizes the amount of irrelevant context and unnecessary tools present on requests to the LLM. LiveKit Agents supports handoffs (one agent hands control to another) to support building reliable workflows. You should make use of these features, instead of writing long instruction prompts that cover multiple phases of a conversation. Refer to the [documentation](https://docs.livekit.io/agents/build/workflows/) for more information.
 
+### Submit docs feedback to LiveKit
+
+If you use the LiveKit Docs MCP Server to search or browse documentation, also submit constructive feedback to LiveKit with the submit_docs_feedback tool. Add this to your to-do list when planning work, to ensure you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps or any other documentation gap or issue.
+
+## Testing
+
+When possible, add tests for agent behavior. Read the [documentation](https://docs.livekit.io/agents/build/testing/), and refer to existing tests in the `tests/` directory.  Run tests with `uv run pytest`.
+
+Important: When modifying core agent behavior such as instructions, tool descriptions, and tasks/workflows/handoffs, never just guess what will work. Always use test-driven development (TDD) and begin by writing tests for the desired behavior. For instance, if you're planning to add a new tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass correctly. This will ensure you are able to produce a working, reliable agent for the user.
+
 ## Feature parity with Python SDK
 
 The Node.js SDK for LiveKit Agents has most, but not all, of the same features available in Python SDK for LiveKit Agents. You should always check the documentation for feature availability, and avoid using features that are not available in the Node.js SDK.

package.json

@@ -4,16 +4,16 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "build": "tsc",
+    "build": "vite build",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",
     "lint": "eslint \"**/*.{ts,js}\"",
     "lint:fix": "eslint --fix \"**/*.{ts,js}\"",
     "format": "prettier --write \"**/*.{ts,js,json,md}\"",
     "format:check": "prettier --check \"**/*.{ts,js,json,md}\"",
-    "test": "node --test --import tsx",
-    "test:watch": "node --test --watch --import tsx",
-    "dev": "tsx src/agent.ts dev",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "dev": "pnpm run build && node dist/agent.js dev",
     "download-files": "pnpm run build && node dist/agent.js download-files",
     "start": "node dist/agent.js start"
   },
@@ -22,20 +22,20 @@
     "pnpm": ">=10.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.38.0",
+    "@eslint/js": "^9.39.2",
     "@trivago/prettier-plugin-sort-imports": "^5.2.2",
-    "@types/node": "^22.18.11",
-    "eslint": "^9.38.0",
-    "globals": "^16.4.0",
-    "jiti": "^2.6.1",
-    "tsx": "^4.20.6",
+    "@types/node": "^22.19.7",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.2"
+    "typescript-eslint": "^8.53.1",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@livekit/agents": "^1.0.21",
-    "@livekit/agents-plugin-livekit": "^1.0.21",
-    "@livekit/agents-plugin-silero": "^1.0.21",
+    "@livekit/agents": "^1.0.38",
+    "@livekit/agents-plugin-livekit": "^1.0.38",
+    "@livekit/agents-plugin-silero": "^1.0.38",
     "@livekit/noise-cancellation-node": "^0.1.9",
     "dotenv": "^17.2.3",
     "zod": "^3.25.76"

src/agent.test.ts

@@ -1,24 +1,47 @@
-import assert from 'node:assert';
-import { describe, it } from 'node:test';
-
-describe('Agent Configuration', () => {
-  it('should have Node.js environment available', () => {
-    // Basic test to ensure Node.js environment is working
-    assert.ok(typeof process !== 'undefined', 'Process should be available');
-    assert.ok(typeof process.env !== 'undefined', 'Environment variables should be accessible');
-  });
+import { inference, initializeLogger, voice } from '@livekit/agents';
+import { afterEach, beforeEach, describe, it } from 'vitest';
+import { Assistant } from './agent';
+
+type TestableAgentSession = InstanceType<typeof voice.AgentSession> & {
+  run(options: { userInput: string }): voice.testing.RunResult;
+};
+
+// Initialize logger for testing
+initializeLogger({ pretty: false, level: 'debug' });
+
+describe('agent evaluation', () => {
+  let session: TestableAgentSession;
+  let llmInstance: inference.LLM;
 
-  it('should be able to import required modules', async () => {
-    // Test that core Node.js modules work
-    const path = await import('node:path');
-    const url = await import('node:url');
+  beforeEach(async () => {
+    llmInstance = new inference.LLM({ model: 'openai/gpt-5.1' });
+    session = new voice.AgentSession({ llm: llmInstance }) as TestableAgentSession;
+    await session.start({ agent: new Assistant() });
+  });
 
-    assert.ok(typeof path.dirname === 'function', 'Path module should be available');
-    assert.ok(typeof url.fileURLToPath === 'function', 'URL module should be available');
+  afterEach(async () => {
+    await session?.close();
   });
 
-  it('should have TypeScript compilation working', () => {
-    // This test file being run means TypeScript compiled successfully
-    assert.ok(true, 'TypeScript compilation is working');
+  it('offers assistance', { timeout: 30000 }, async () => {
+    // Run an agent turn following the user's greeting
+    const result = await session.run({ userInput: 'Hello' }).wait();
+
+    // Evaluate the agent's response for friendliness
+    await result.expect
+      .nextEvent()
+      .isMessage({ role: 'assistant' })
+      .judge(llmInstance, {
+        intent: `\
+Greets the user in a friendly manner.
+
+Optional context that may or may not be included:
+- Offer of assistance with any request the user may have
+- Other small talk or chit chat is acceptable, so long as it is friendly and not too intrusive
+`,
+      });
+
+    // Assert that there are no unexpected further events
+    result.expect.noMoreEvents();
   });
 });

src/agent.ts

@@ -16,7 +16,7 @@ import { fileURLToPath } from 'node:url';
 
 dotenv.config({ path: '.env.local' });
 
-class Assistant extends voice.Agent {
+export class Assistant extends voice.Agent {
   constructor() {
     super({
       instructions: `You are a helpful voice AI assistant. The user is interacting with you via voice, even if you perceive the conversation as text.
@@ -65,7 +65,7 @@ export default defineAgent({
       // A Large Language Model (LLM) is your agent's brain, processing user input and generating a response
       // See all providers at https://docs.livekit.io/agents/models/llm/
       llm: new inference.LLM({
-        model: 'openai/gpt-4.1-mini',
+        model: 'openai/gpt-5.1-mini',
       }),
 
       // Text-to-speech (TTS) is your agent's voice, turning the LLM's text into speech that the user can hear
@@ -127,4 +127,7 @@ export default defineAgent({
   },
 });
 
-cli.runApp(new ServerOptions({ agent: fileURLToPath(import.meta.url) }));
+// Only run the CLI if we're not in a test environment
+if (process.env.NODE_ENV !== 'test') {
+  cli.runApp(new ServerOptions({ agent: fileURLToPath(import.meta.url) }));
+}

tsconfig.json

@@ -1,6 +1,6 @@
 {
   "include": ["./src/**/*"],
-  "exclude": ["./dist", "./node_modules"],
+  "exclude": ["./dist", "./node_modules", "**/*.test.ts", "**/*.spec.ts"],
   "compilerOptions": {
     "target": "ES2022",
     "module": "ES2022",

vite.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  build: {
+    ssr: 'src/agent.ts', // marks entry as Node
+    target: 'node18',
+    sourcemap: true,
+    outDir: 'dist',
+    rollupOptions: {
+      output: {
+        entryFileNames: 'agent.js',
+      },
+    },
+  },
+});