@livekit/agents-plugin-anam 0.0.0-next-20260624041820

package/src/api.ts

@@ -0,0 +1,187 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { log } from '@livekit/agents';
+import {
+  type APIConnectOptions,
+  AnamException,
+  type PersonaConfig,
+  type SessionOptions,
+} from './types.js';
+
+const DEFAULT_API_URL = 'https://api.anam.ai';
+
+/** @public */
+export class AnamAPI {
+  constructor(
+    private apiKey: string,
+    private apiUrl: string = DEFAULT_API_URL,
+    private conn: APIConnectOptions = { maxRetry: 3, retryInterval: 2, timeout: 10 },
+  ) {}
+
+  private get tokenPath(): string {
+    return '/v1/auth/session-token';
+  }
+
+  private get startPath(): string {
+    return '/v1/engine/session';
+  }
+
+  private async postWithHeaders<T>(
+    path: string,
+    body: unknown,
+    headersIn: Record<string, string>,
+  ): Promise<T> {
+    const url = `${this.apiUrl}${path}`;
+    const { maxRetry = 3, retryInterval = 2 } = this.conn;
+    let lastErr: unknown;
+    const logger = log().child({ module: 'AnamAPI' });
+
+    for (let attempt = 0; attempt < maxRetry; attempt++) {
+      try {
+        const headers: Record<string, string> = {
+          'Content-Type': 'application/json',
+          ...headersIn,
+        };
+
+        const redactedHeaders: Record<string, string> = { ...headers };
+        if (redactedHeaders.Authorization) {
+          redactedHeaders.Authorization = 'Bearer ****';
+        }
+        const redactedBody = (() => {
+          if (body && typeof body === 'object') {
+            try {
+              const clone = { ...(body as Record<string, unknown>) } as Record<string, unknown>;
+              if ('livekitToken' in clone) clone.livekitToken = '****';
+              if ('sessionToken' in clone) clone.sessionToken = '****' as unknown as never;
+              return clone;
+            } catch {
+              return { note: 'unserializable body' };
+            }
+          }
+          return body;
+        })();
+
+        logger.debug(
+          {
+            url,
+            method: 'POST',
+            headers: redactedHeaders,
+            body: redactedBody,
+            attempt: attempt + 1,
+          },
+          'calling Anam API',
+        );
+
+        const res = await fetch(url, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+          // simple timeout: rely on AbortController in real impl
+        });
+        if (!res.ok) {
+          const text = await res.text();
+          logger.error(
+            {
+              url,
+              method: 'POST',
+              headers: redactedHeaders,
+              body: redactedBody,
+              status: res.status,
+              response: text,
+            },
+            'Anam API request failed',
+          );
+          throw new AnamException(`Anam ${path} failed: ${res.status} ${text}`);
+        }
+        const json = (await res.json()) as T;
+        logger.debug({ url }, 'Anam API request succeeded');
+        return json;
+      } catch (e) {
+        lastErr = e;
+        if (attempt === maxRetry - 1) break;
+        logger.warn(
+          {
+            url,
+            method: 'POST',
+            body:
+              body && typeof body === 'object'
+                ? { ...(body as Record<string, unknown>), livekitToken: '****' }
+                : body,
+            error: (e as Error)?.message,
+            nextRetrySec: retryInterval,
+          },
+          'Anam API error, retrying',
+        );
+        await new Promise((r) => setTimeout(r, retryInterval * 1000));
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new AnamException('Anam API error');
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    return this.postWithHeaders<T>(path, body, { Authorization: `Bearer ${this.apiKey}` });
+  }
+
+  createSessionToken(params: {
+    personaConfig: PersonaConfig;
+    livekitUrl?: string;
+    livekitToken?: string;
+    sessionOptions?: SessionOptions;
+  }) {
+    const pc = params.personaConfig;
+    // Anam's personaConfig is a `oneOf`: reference a previously created
+    // (stateful) persona by `personaId` — the "dev flow" — or configure an
+    // ephemeral persona inline with name/avatarId/llmId. The two are mutually
+    // exclusive, so when a personaId is given we must not also send the
+    // ephemeral fields.
+    const personaPayload: Record<string, unknown> = pc.personaId
+      ? { personaId: pc.personaId }
+      : {
+          type: 'ephemeral',
+          name: pc.name,
+          avatarId: pc.avatarId,
+          llmId: 'CUSTOMER_CLIENT_V1',
+          // Only forward the avatar model version when set; otherwise let Anam
+          // fall back to the avatar's default model.
+          ...(pc.avatarModel ? { avatarModel: pc.avatarModel } : {}),
+        };
+
+    const payload: Record<string, unknown> = {
+      personaConfig: personaPayload,
+    };
+    payload.environment = {
+      livekitUrl: params.livekitUrl,
+      livekitToken: params.livekitToken,
+    };
+
+    if (
+      params.sessionOptions &&
+      (params.sessionOptions.videoWidth !== undefined ||
+        params.sessionOptions.videoHeight !== undefined)
+    ) {
+      if (
+        params.sessionOptions.videoWidth === undefined ||
+        params.sessionOptions.videoHeight === undefined
+      ) {
+        throw new AnamException(
+          'videoWidth and videoHeight must be set together (both or neither)',
+        );
+      }
+      payload.sessionOptions = {
+        videoWidth: params.sessionOptions.videoWidth,
+        videoHeight: params.sessionOptions.videoHeight,
+      };
+    }
+
+    return this.post<{ sessionToken: string }>(this.tokenPath, payload);
+  }
+
+  startEngineSession(params: { sessionToken: string }) {
+    return this.postWithHeaders<{ sessionId: string }>(
+      this.startPath,
+      {},
+      { Authorization: `Bearer ${params.sessionToken}` },
+    );
+  }
+}

package/src/avatar.test.ts

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { voice } from '@livekit/agents';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AvatarSession } from './avatar.js';
+
+describe('Anam AvatarSession', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('calls base AvatarSession.start first', async () => {
+    const sentinel = new Error('super-start-called');
+    const superStartSpy = vi
+      .spyOn(voice.AvatarSession.prototype, 'start')
+      .mockRejectedValue(sentinel);
+
+    const avatar = new AvatarSession({
+      personaConfig: {
+        personaId: 'persona-test',
+      },
+    });
+
+    await expect(
+      avatar.start({ _started: false, output: { audio: null } } as any, {} as any),
+    ).rejects.toThrow('super-start-called');
+    expect(superStartSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/avatar.ts

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { log, voice } from '@livekit/agents';
+import type { Room } from '@livekit/rtc-node';
+import { TrackKind } from '@livekit/rtc-node';
+import { AccessToken, type VideoGrant } from 'livekit-server-sdk';
+import { AnamAPI } from './api.js';
+import {
+  type APIConnectOptions,
+  AnamException,
+  type PersonaConfig,
+  type SessionOptions,
+} from './types.js';
+
+/** @public */
+export async function mintAvatarJoinToken({
+  roomName,
+  avatarIdentity,
+  publishOnBehalf,
+  apiKey = process.env.LIVEKIT_API_KEY!,
+  apiSecret = process.env.LIVEKIT_API_SECRET!,
+  ttl = '60s',
+}: {
+  roomName: string;
+  avatarIdentity: string;
+  publishOnBehalf: string;
+  apiKey?: string;
+  apiSecret?: string;
+  ttl?: string | number;
+}): Promise<string> {
+  const at = new AccessToken(apiKey, apiSecret);
+  at.identity = avatarIdentity;
+  at.name = 'Anam Avatar';
+  at.kind = 'agent';
+  at.ttl = ttl;
+  at.attributes = { 'lk.publish_on_behalf': publishOnBehalf };
+
+  at.addGrant({ roomJoin: true, room: roomName } as VideoGrant);
+  return at.toJwt();
+}
+
+const AVATAR_IDENTITY = 'anam-avatar-agent';
+const _AVATAR_NAME = 'anam-avatar-agent';
+
+/** @public */
+export class AvatarSession extends voice.AvatarSession {
+  private sessionId?: string;
+
+  constructor(
+    private opts: {
+      personaConfig: PersonaConfig;
+      sessionOptions?: SessionOptions;
+      apiUrl?: string;
+      apiKey?: string;
+      avatarParticipantIdentity?: string;
+      avatarParticipantName?: string;
+      connOptions?: APIConnectOptions;
+    },
+  ) {
+    super();
+  }
+
+  override get avatarIdentity(): string {
+    return this.opts.avatarParticipantIdentity ?? AVATAR_IDENTITY;
+  }
+
+  override get provider(): string {
+    return 'anam';
+  }
+
+  async start(
+    agentSession: voice.AgentSession,
+    room: Room,
+    params?: {
+      livekitUrl?: string;
+      livekitApiKey?: string;
+      livekitApiSecret?: string;
+    },
+  ) {
+    await super.start(agentSession, room);
+
+    const logger = log().child({ module: 'AnamAvatar' });
+    const apiKey = this.opts.apiKey ?? process.env.ANAM_API_KEY;
+    if (!apiKey) throw new AnamException('ANAM_API_KEY is required');
+
+    const apiUrl = this.opts.apiUrl ?? process.env.ANAM_API_URL;
+    const livekitUrl = params?.livekitUrl ?? process.env.LIVEKIT_URL;
+    const lkKey = params?.livekitApiKey ?? process.env.LIVEKIT_API_KEY;
+    const lkSecret = params?.livekitApiSecret ?? process.env.LIVEKIT_API_SECRET;
+
+    if (!livekitUrl || !lkKey || !lkSecret) {
+      throw new AnamException('LIVEKIT_URL/API_KEY/API_SECRET must be set');
+    }
+
+    const localIdentity = (room.localParticipant && room.localParticipant.identity) || 'agent';
+
+    logger.debug(
+      {
+        personaName: this.opts.personaConfig?.name,
+        avatarId: this.opts.personaConfig?.avatarId,
+        personaId: this.opts.personaConfig?.personaId,
+        apiUrl: apiUrl ?? '(default https://api.anam.ai)',
+        livekitUrl,
+        avatarParticipantIdentity: this.opts.avatarParticipantIdentity ?? 'anam-avatar-agent',
+        publishOnBehalf: localIdentity,
+      },
+      'starting Anam avatar session',
+    );
+
+    const jwt = await mintAvatarJoinToken({
+      roomName: room.name!,
+      avatarIdentity: this.avatarIdentity,
+      publishOnBehalf: localIdentity,
+      apiKey: lkKey,
+      apiSecret: lkSecret,
+    });
+
+    const anam = new AnamAPI(apiKey, apiUrl, this.opts.connOptions);
+    logger.debug({ livekitUrl }, 'requesting Anam session token');
+
+    const { sessionToken } = await anam.createSessionToken({
+      personaConfig: this.opts.personaConfig,
+      livekitUrl,
+      livekitToken: jwt,
+      sessionOptions: this.opts.sessionOptions,
+    });
+    logger.debug('starting Anam engine session');
+    const started = await anam.startEngineSession({ sessionToken });
+    this.sessionId = started.sessionId;
+
+    agentSession.output.audio = new voice.DataStreamAudioOutput({
+      room,
+      destinationIdentity: this.avatarIdentity,
+      waitRemoteTrack: TrackKind.KIND_VIDEO,
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { Plugin } from '@livekit/agents';
+
+export * from './types.js';
+export * from './api.js';
+export * from './avatar.js';
+
+class AnamPlugin extends Plugin {
+  constructor() {
+    super({
+      title: 'anam',
+      version: __PACKAGE_VERSION__,
+      package: __PACKAGE_NAME__,
+    });
+  }
+}
+Plugin.registerPlugin(new AnamPlugin());

package/src/types.ts

@@ -0,0 +1,32 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+/** @public */
+export type PersonaConfig = {
+  /** Optional display name (prod flow) */
+  name?: string;
+  /** Optional avatar asset id (prod flow) */
+  avatarId?: string;
+  /** Optional avatar model version, e.g. "cara-3" or "cara-4-latest" (prod flow) */
+  avatarModel?: string;
+  /** Optional persona id (dev flow) */
+  personaId?: string;
+};
+
+/** @public */
+export type SessionOptions = {
+  /** Output video frame width in pixels. Provide together with videoHeight. */
+  videoWidth?: number;
+  /** Output video frame height in pixels. Provide together with videoWidth. */
+  videoHeight?: number;
+};
+
+/** @public */
+export type APIConnectOptions = {
+  maxRetry?: number;
+  retryInterval?: number; // seconds
+  timeout?: number; // seconds
+};
+
+/** @public */
+export class AnamException extends Error {}