feat: answering machine detection

[chenghao-mou]

• AMDResult with categories: human, machine-ivr, machine-vm, machine-unavailable, and uncertain
• amd.execute() API for agents to await detection results
• Example in ‎examples/telephony/amd.py

Usage

await session.start(
    agent=MyAgent(),
    room=ctx.room,
)

async with AMD(session, llm="openai/gpt-5-mini") as detector:
    result = await detector.execute()

    if result.category == "human":
        logger.info("human answered the call, proceeding with normal conversation")
    elif result.category == "machine-ivr":
        logger.info("ivr menu detected, starting navigation")
    elif result.category == "machine-vm":
        logger.info("voicemail detected, leaving a message")
        speech_handle = session.generate_reply(
            instructions=(
                "You've reached voicemail. Leave a brief message asking "
                "the customer to call back."
            ),
        )
        await speech_handle.wait_for_playout()
        session.shutdown()
    elif result.category == "machine-unavailable":
        logger.info("mailbox unavailable, ending call")
        session.shutdown()

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 11 additional findings in Devin Review.

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 15 additional findings in Devin Review.

[devin-ai-integration]

🟡 AMD authorization pause not applied to new AgentActivity created during agent handoff

When AMD pauses authorization via _pause_authorization() on the current AgentActivity, and then an agent handoff occurs (e.g., via update_agent), a new AgentActivity is created with _authorization_allowed initialized as set (livekit-agents/livekit/agents/voice/agent_activity.py:155-156). The AMD's _on_first_audio only fires once (it checks self._classifier.started at detector.py:139 and returns), so _pause_authorization() is never called on the new activity. This means the new activity's speech will bypass AMD's authorization gate, defeating the purpose of holding speech until AMD resolves.

Scenario

1. AMD starts, calls _pause_authorization() on current activity
2. Agent handoff occurs (e.g. user calls session.update_agent()) while AMD is still pending
3. New AgentActivity is created with _authorization_allowed already set
4. Speech on the new activity proceeds without waiting for AMD result

Prompt for agents

The AMD detector pauses authorization on the current AgentActivity, but if an agent handoff creates a new AgentActivity while AMD is still pending, the new activity won't have authorization paused. To fix this, either: (1) propagate the AMD authorization pause state to new AgentActivity instances when they are created in _update_activity (in agent_session.py), e.g. by checking if session._amd is pending and calling _pause_authorization() on the new activity; or (2) have the AMD store a reference to the session rather than the activity and apply the pause on whatever is the current activity at any given time, checking this in the activity's authorization wait path.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 execute() does not resume authorization if an exception occurs before _resume_authorization()

In execute(), if self._session.interrupt(force=True) (line 105) or self._session._start_ivr_detection(...) (line 108) raises an exception, the _resume_authorization() call at line 112 is skipped. When execute() is used inside the async with AMD(...) context manager, __aexit__ → aclose() will resume authorization as a fallback. However, if execute() is called directly (without the context manager), authorization remains permanently paused, deadlocking all subsequent speech generation.

Suggested change

	result = self._result
	if result.is_machine and self._interrupt_on_machine:
	await self._session.interrupt(force=True)
	if result.category == AMDCategory.MACHINE_IVR and self._ivr_detection:
	await self._session._start_ivr_detection(transcript=result.transcript)
	# eagerly resume so agent can speak immediately to a human
	if self._session._activity is not None:
	self._session._activity._resume_authorization()
	return result
	result = self._result
	try:
	if result.is_machine and self._interrupt_on_machine:
	await self._session.interrupt(force=True)
	if result.category == AMDCategory.MACHINE_IVR and self._ivr_detection:
	await self._session._start_ivr_detection(transcript=result.transcript)
	finally:
	# eagerly resume so agent can speak immediately to a human
	if self._session._activity is not None:
	self._session._activity._resume_authorization()
	return result

---

Was this helpful? React with 👍 or 👎 to provide feedback.