Add Beyond Presence (Bey) plugin (#759)

Co-authored-by: aoife cassidy <[email protected]>

Author: mshehrozsajjad

.changeset/add-bey-plugin.md

@@ -0,0 +1,5 @@
+---
+'@livekit/agents-plugin-bey': major
+---
+
+Add Beyond Presence (Bey) plugin for LiveKit agents

examples/package.json

@@ -23,6 +23,7 @@
   "dependencies": {
     "@livekit/agents": "workspace:*",
     "@livekit/agents-plugin-anam": "workspace:*",
+    "@livekit/agents-plugin-bey": "workspace:*",
     "@livekit/agents-plugin-cartesia": "workspace:*",
     "@livekit/agents-plugin-deepgram": "workspace:*",
     "@livekit/agents-plugin-elevenlabs": "workspace:*",

examples/src/bey_avatar.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { type JobContext, WorkerOptions, cli, defineAgent, metrics, voice } from '@livekit/agents';
+import * as bey from '@livekit/agents-plugin-bey';
+import * as openai from '@livekit/agents-plugin-openai';
+import { fileURLToPath } from 'node:url';
+
+export default defineAgent({
+  entry: async (ctx: JobContext) => {
+    const agent = new voice.Agent({
+      instructions: 'You are a helpful assistant. Speak clearly and concisely.',
+    });
+
+    const session = new voice.AgentSession({
+      llm: new openai.realtime.RealtimeModel({
+        voice: 'alloy',
+      }),
+    });
+
+    await ctx.connect();
+
+    await session.start({
+      agent,
+      room: ctx.room,
+    });
+
+    const avatarId = process.env.BEY_AVATAR_ID;
+
+    const avatar = new bey.AvatarSession({
+      avatarId: avatarId || undefined,
+    });
+    await avatar.start(session, ctx.room);
+
+    const usageCollector = new metrics.UsageCollector();
+
+    session.on(voice.AgentSessionEventTypes.MetricsCollected, (ev) => {
+      metrics.logMetrics(ev.metrics);
+      usageCollector.collect(ev.metrics);
+    });
+
+    session.generateReply({
+      instructions: 'Greet the user briefly and confirm you are ready.',
+    });
+  },
+});
+
+cli.runApp(new WorkerOptions({ agent: fileURLToPath(import.meta.url) }));

plugins/bey/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @livekit/agents-plugin-bey
+
+## 0.0.1
+
+### Major Changes
+
+- Add Beyond Presence (Bey) plugin for LiveKit agents
+
+### Patch Changes
+
+- Updated dependencies:
+  - @livekit/agents@1.0.9

plugins/bey/README.md

@@ -0,0 +1,81 @@
+<!--
+SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Beyond Presence plugin for LiveKit Agents
+
+Support for [Beyond Presence](https://docs.bey.dev) virtual avatars.
+
+See [https://docs.livekit.io/agents/integrations/avatar/bey/](https://docs.livekit.io/agents/integrations/avatar/bey/) for more information.
+
+## Installation
+
+```bash
+npm install @livekit/agents-plugin-bey
+```
+
+or
+
+```bash
+pnpm add @livekit/agents-plugin-bey
+```
+
+## Pre-requisites
+
+Create a developer API key from the [creator dashboard](https://app.bey.chat) and set the `BEY_API_KEY` environment variable with it:
+
+```bash
+export BEY_API_KEY=<your-bey-api-key>
+```
+
+## Usage
+
+```typescript
+import { AvatarSession } from '@livekit/agents-plugin-bey';
+import { AgentSession } from '@livekit/agents';
+
+// Create an avatar session
+const avatarSession = new AvatarSession({
+  avatarId: 'your-avatar-id', // optional, defaults to stock avatar
+  apiKey: process.env.BEY_API_KEY, // optional if set via env var
+});
+
+// Start the avatar in your agent
+await avatarSession.start(agentSession, room, {
+  livekitUrl: process.env.LIVEKIT_URL,
+  livekitApiKey: process.env.LIVEKIT_API_KEY,
+  livekitApiSecret: process.env.LIVEKIT_API_SECRET,
+});
+```
+
+## API
+
+### `AvatarSession`
+
+Creates a new Beyond Presence avatar session.
+
+#### Constructor Options
+
+- `avatarId?: string` - The avatar ID to use. Defaults to stock avatar.
+- `apiUrl?: string` - The Bey API URL. Defaults to `https://api.bey.dev`.
+- `apiKey?: string` - Your Bey API key. Can also be set via `BEY_API_KEY` environment variable.
+- `avatarParticipantIdentity?: string` - The identity for the avatar participant. Defaults to `'bey-avatar-agent'`.
+- `avatarParticipantName?: string` - The name for the avatar participant. Defaults to `'bey-avatar-agent'`.
+- `connOptions?: APIConnectOptions` - Connection options for retry logic.
+
+#### Methods
+
+##### `start(agentSession: AgentSession, room: Room, options?: StartOptions): Promise<void>`
+
+Starts the avatar session and connects it to the room.
+
+**Options:**
+- `livekitUrl?: string` - The LiveKit server URL. Can also be set via `LIVEKIT_URL` environment variable.
+- `livekitApiKey?: string` - Your LiveKit API key. Can also be set via `LIVEKIT_API_KEY` environment variable.
+- `livekitApiSecret?: string` - Your LiveKit API secret. Can also be set via `LIVEKIT_API_SECRET` environment variable.
+
+## License
+
+Apache 2.0

plugins/bey/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@livekit/agents-plugin-bey",
+  "version": "0.0.1",
+  "description": "Beyond Presence plugin for LiveKit Node Agents",
+  "main": "dist/index.js",
+  "require": "dist/index.cjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "import": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "require": {
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
+    }
+  },
+  "author": "LiveKit",
+  "type": "module",
+  "repository": "[email protected]:livekit/agents-js.git",
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup --onSuccess \"pnpm build:types\"",
+    "build:types": "tsc --declaration --emitDeclarationOnly && node ../../scripts/copyDeclarationOutput.js",
+    "clean": "rm -rf dist",
+    "clean:build": "pnpm clean && pnpm build",
+    "lint": "eslint -f unix \"src/**/*.{ts,js}\"",
+    "api:check": "api-extractor run --typescript-compiler-folder ../../node_modules/typescript",
+    "api:update": "api-extractor run --local --typescript-compiler-folder ../../node_modules/typescript --verbose"
+  },
+  "devDependencies": {
+    "@livekit/agents": "workspace:*",
+    "@livekit/rtc-node": "^0.13.12",
+    "@microsoft/api-extractor": "^7.35.0",
+    "pino": "^8.19.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "livekit-server-sdk": "^2.13.3"
+  },
+  "peerDependencies": {
+    "@livekit/agents": "workspace:*",
+    "@livekit/rtc-node": "^0.13.12"
+  }
+}