fix(voice): align AMD categories with python

Author: chenghao-mou

agents/src/voice/amd.test.ts

@@ -89,6 +89,33 @@ describe('AMD', () => {
     expect(session.interrupt).toHaveBeenCalledWith({ force: true });
   });
 
+  it('should classify unavailable mailbox as machine', async () => {
+    const session = new MockSession();
+    const llm = new StaticLLM(
+      JSON.stringify({
+        category: AMDCategory.MACHINE_UNAVAILABLE,
+        reason: 'The mailbox is unavailable and cannot accept messages.',
+      }),
+    );
+    llm.on('error', () => {});
+    const amd = new AMD(asAgentSession(session), { llm });
+
+    const promise = amd.execute();
+    session.emit(AgentSessionEventTypes.UserInputTranscribed, {
+      type: 'user_input_transcribed',
+      transcript: 'The mailbox you are trying to reach is unavailable',
+      isFinal: true,
+      speakerId: null,
+      createdAt: Date.now(),
+      language: null,
+    });
+
+    await expect(promise).resolves.toMatchObject({
+      category: AMDCategory.MACHINE_UNAVAILABLE,
+      isMachine: true,
+    });
+  });
+
   it('should resume authorization when detection fails', async () => {
     const session = new MockSession();
     const llm = new StaticLLM(new Error('boom'));

agents/src/voice/amd.ts

@@ -10,10 +10,10 @@ import { setParticipantSpanAttributes } from './utils.js';
 
 export enum AMDCategory {
   HUMAN = 'human',
-  MACHINE = 'machine',
   MACHINE_IVR = 'machine-ivr',
   MACHINE_VM = 'machine-vm',
-  UNKNOWN = 'unknown',
+  MACHINE_UNAVAILABLE = 'machine-unavailable',
+  UNCERTAIN = 'uncertain',
 }
 
 export interface AMDResult {
@@ -36,12 +36,12 @@ const DEFAULT_MAX_TRANSCRIPT_TURNS = 2;
 
 const AMD_PROMPT = `You classify the start of a phone call.
 Return strict JSON with keys "category" and "reason".
-Valid categories: "human", "machine", "machine-ivr", "machine-vm", "unknown".
+Valid categories: "human", "machine-ivr", "machine-vm", "machine-unavailable", "uncertain".
 - "human": a live person answered.
-- "machine": generic answering machine signal without enough detail to distinguish IVR or voicemail.
 - "machine-ivr": an IVR, phone tree, or menu system answered.
 - "machine-vm": a voicemail greeting or mailbox prompt answered.
-- "unknown": not enough evidence yet.
+- "machine-unavailable": the call reached an unavailable mailbox, failed mailbox, or generic machine state where no message should be left.
+- "uncertain": not enough evidence yet.
 Do not include markdown fences or extra text.`;
 
 export class AMD {
@@ -157,7 +157,7 @@ export class AMD {
               transcript.length > 0
                 ? await this.detect(transcript)
                 : {
-                    category: AMDCategory.UNKNOWN,
+                    category: AMDCategory.UNCERTAIN,
                     transcript: '',
                     reason,
                     rawResponse: '',
@@ -180,7 +180,7 @@ export class AMD {
 
           const result = await this.detect(transcriptParts.join('\n'));
           if (
-            result.category !== AMDCategory.UNKNOWN ||
+            result.category !== AMDCategory.UNCERTAIN ||
             transcriptParts.length >= this.maxTranscriptTurns
           ) {
             await finish(result, resolveRun);
@@ -240,9 +240,9 @@ export class AMD {
       transcript,
       rawResponse,
       isMachine:
-        parsed.category === AMDCategory.MACHINE ||
         parsed.category === AMDCategory.MACHINE_IVR ||
-        parsed.category === AMDCategory.MACHINE_VM,
+        parsed.category === AMDCategory.MACHINE_VM ||
+        parsed.category === AMDCategory.MACHINE_UNAVAILABLE,
     };
   }
 
@@ -263,7 +263,7 @@ export class AMD {
       };
     } catch {
       return {
-        category: AMDCategory.UNKNOWN,
+        category: AMDCategory.UNCERTAIN,
         reason: normalized || 'Failed to parse AMD model response.',
       };
     }
@@ -273,14 +273,16 @@ export class AMD {
     switch (category) {
       case AMDCategory.HUMAN:
         return AMDCategory.HUMAN;
-      case AMDCategory.MACHINE:
-        return AMDCategory.MACHINE;
       case AMDCategory.MACHINE_IVR:
         return AMDCategory.MACHINE_IVR;
       case AMDCategory.MACHINE_VM:
         return AMDCategory.MACHINE_VM;
+      case AMDCategory.MACHINE_UNAVAILABLE:
+        return AMDCategory.MACHINE_UNAVAILABLE;
+      case AMDCategory.UNCERTAIN:
+        return AMDCategory.UNCERTAIN;
       default:
-        return AMDCategory.UNKNOWN;
+        return AMDCategory.UNCERTAIN;
     }
   }
 }

examples/src/telephony_amd.ts

@@ -0,0 +1,96 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import {
+  type JobContext,
+  type JobProcess,
+  ServerOptions,
+  cli,
+  defineAgent,
+  inference,
+  log,
+  voice,
+} from '@livekit/agents';
+import * as livekit from '@livekit/agents-plugin-livekit';
+import * as silero from '@livekit/agents-plugin-silero';
+import { fileURLToPath } from 'node:url';
+
+class MyAgent extends voice.Agent {
+  constructor() {
+    super({
+      instructions:
+        'You are reaching out to a customer with a phone call. ' +
+        'You are calling to see if they are home. ' +
+        'You might encounter an answering machine with a DTMF menu or IVR system. ' +
+        'If you do, you will try to leave a message asking them to call back.',
+    });
+  }
+}
+
+export default defineAgent({
+  prewarm: async (proc: JobProcess) => {
+    proc.userData.vad = await silero.VAD.load();
+  },
+  entry: async (ctx: JobContext) => {
+    const logger = log().child({ room: ctx.room.name });
+
+    const session = new voice.AgentSession({
+      stt: new inference.STT({
+        model: 'deepgram/nova-3',
+        language: 'multi',
+      }),
+      llm: new inference.LLM({ model: 'openai/gpt-4.1-mini' }),
+      tts: new inference.TTS({
+        model: 'cartesia/sonic-3',
+        voice: '9626c31c-bec5-4cca-baa8-f8ba9e84c8bc',
+      }),
+      turnHandling: {
+        turnDetection: new livekit.turnDetector.MultilingualModel(),
+      },
+      vad: ctx.proc.userData.vad! as silero.VAD,
+      preemptiveGeneration: true,
+    });
+
+    await session.start({
+      agent: new MyAgent(),
+      room: ctx.room,
+    });
+
+    const detector = new voice.AMD(session, {
+      llm: new inference.LLM({ model: 'openai/gpt-5-mini' }),
+    });
+
+    const result = await detector.execute();
+
+    if (result.category === voice.AMDCategory.HUMAN) {
+      logger.info({ amd: result }, 'human answered the call, proceeding with normal conversation');
+      return;
+    }
+
+    if (result.category === voice.AMDCategory.MACHINE_IVR) {
+      logger.info({ amd: result }, 'ivr menu detected, starting navigation');
+      return;
+    }
+
+    if (result.category === voice.AMDCategory.MACHINE_VM) {
+      logger.info({ amd: result }, 'voicemail detected, leaving a message');
+      const speechHandle = session.generateReply({
+        instructions:
+          "You've reached voicemail. Leave a brief message asking the customer to call back.",
+      });
+      await speechHandle.waitForPlayout();
+      session.shutdown({ reason: 'amd:machine-vm' });
+      return;
+    }
+
+    if (result.category === voice.AMDCategory.MACHINE_UNAVAILABLE) {
+      logger.info({ amd: result }, 'mailbox unavailable, ending call');
+      session.shutdown({ reason: 'amd:machine-unavailable' });
+      return;
+    }
+
+    logger.info({ amd: result }, 'answering machine detection was uncertain');
+  },
+});
+
+cli.runApp(new ServerOptions({ agent: fileURLToPath(import.meta.url) }));