Python Agents: Handling exceptions in your entrypoint

When an unhandled exception occurs inside your entrypoint() function, the agent process exits and leaves the LiveKit room. However, the SIP call itself isn't automatically terminated. This means the phone call stays connected to a silent, empty room until someone hangs up. This applies to both inbound and outbound calls — any scenario where an exception occurs after the call is established.

This can happen when any setup code in your entrypoint throws unexpectedly: a failed API call, a misconfigured service, a missing environment variable, or a transient infrastructure issue.

This guide covers why this happens, why the framework doesn't handle it automatically, and several strategies for cleaning up gracefully.

Why the framework doesn't auto-close the room

The Agents framework intentionally doesn't delete the room or hang up the call when an agent leaves. This is by design — the framework can't know your use case. For example:

• The room might be a multi-participant meeting where one agent crashing shouldn't end the call for everyone.
• You might want a different agent to retry or take over.
• You might have other participants in the room that should continue.

Because the agent leaves after the exception with CLIENT_REQUEST_LEAVE, another agent won't automatically be dispatched to replace it either. The room is left as-is.

Prerequisites

• An agent created using the Voice AI quickstart.
• LiveKit SIP configured to accept inbound calls.

Wrapping your entrypoint in try/except

The most straightforward approach is to wrap your entrypoint() function body in a try/except block. This gives you full control over cleanup when something goes wrong.

1
import logging
2
from livekit import api
3
from livekit.agents import AgentSession, AgentServer, JobContext, cli
4
from livekit.agents.voice import Agent
5
from livekit.plugins import silero
6

7
logger = logging.getLogger("safe-entrypoint")
8
logger.setLevel(logging.INFO)
9

10
server = AgentServer()
11

12

13
@server.rtc_session(agent_name="my-agent")
14
async def entrypoint(ctx: JobContext):
15
    try:
16
        # Your setup code that might fail
17
        session = AgentSession(
18
            stt="deepgram/nova-3",
19
            llm="openai/gpt-4o",
20
            tts="cartesia/sonic-3",
21
            vad=silero.VAD.load(),
22
        )
23

24
        await session.start(
25
            agent=Agent(instructions="You are a helpful assistant."),
26
            room=ctx.room,
27
        )
28

29
    except Exception as e:
30
        logger.error(f"Entrypoint failed: {e}", exc_info=True)
31

32
        # Clean up: delete the room to end the SIP call
33
        lkapi = api.LiveKitAPI()
34
        try:
35
            await lkapi.room.delete_room(
36
                api.DeleteRoomRequest(room=ctx.room.name)
37
            )
38
            logger.info(f"Deleted room {ctx.room.name} after entrypoint failure")
39
        except Exception as cleanup_error:
40
            logger.error(f"Failed to delete room: {cleanup_error}")
41
        finally:
42
            await lkapi.aclose()
43

44

45
if __name__ == "__main__":
46
    cli.run_app(server)

Choosing a cleanup strategy

Deleting the room is the most aggressive cleanup option. Depending on your use case, you might want a different approach.

Option 1: Delete the room

Best for dedicated SIP call rooms where the agent is the only reason the room exists. Deleting the room disconnects all participants, including the SIP caller.

1
lkapi = api.LiveKitAPI()
2
try:
3
    await lkapi.room.delete_room(
4
        api.DeleteRoomRequest(room=ctx.room.name)
5
    )
6
finally:
7
    await lkapi.aclose()

Option 2: Remove the SIP participant

Best for rooms where other participants should stay connected. This hangs up the phone call without affecting other room members.

1
lkapi = api.LiveKitAPI()
2
try:
3
    # List participants and remove only SIP ones
4
    res = await lkapi.room.list_participants(
5
        api.ListParticipantsRequest(room=ctx.room.name)
6
    )
7
    for p in res.participants:
8
        if p.identity.startswith("sip_"):
9
            await lkapi.room.remove_participant(
10
                api.RoomParticipantIdentity(
11
                    room=ctx.room.name,
12
                    identity=p.identity,
13
                )
14
            )
15
finally:
16
    await lkapi.aclose()

Option 3: Notify then hang up

Best when you want to give the caller a brief explanation before ending the call. Start a minimal session, apologize, then shut down.

1
except Exception as e:
2
    logger.error(f"Entrypoint failed: {e}", exc_info=True)
3

4
    try:
5
        # Start a minimal session just to say goodbye
6
        fallback_session = AgentSession(
7
            tts="cartesia/sonic-3",
8
        )
9

10
        fallback_agent = Agent(
11
            instructions="Apologize briefly for the technical difficulty and say goodbye."
12
        )
13

14
        await fallback_session.start(agent=fallback_agent, room=ctx.room)
15

16
        await fallback_session.say(
17
            "I'm sorry, we're experiencing a technical issue. Please try again later.",
18
            allow_interruptions=False,
19
        )
20

21
        fallback_session.shutdown()
22

23
    except Exception:
24
        # If even the fallback fails, just delete the room
25
        lkapi = api.LiveKitAPI()
26
        try:
27
            await lkapi.room.delete_room(
28
                api.DeleteRoomRequest(room=ctx.room.name)
29
            )
30
        finally:
31
            await lkapi.aclose()

Handling errors after session start

Exceptions can also occur after your session has started — for example, from inference API failures during the conversation. For these cases, use the error event on AgentSession rather than wrapping the entrypoint:

1
@session.on("error")
2
def on_error(error_event):
3
    if not error_event.error.recoverable:
4
        logger.error(f"Unrecoverable error: {error_event.error}")
5
        session.say(
6
            "I'm having trouble right now. Let me transfer you.",
7
            allow_interruptions=False,
8
        )

For more details, see Events and error handling.

You can also use a FallbackAdapter to automatically retry with backup providers when the primary STT, LLM, or TTS fails:

1
from livekit.agents import llm, stt, tts
2
from livekit.plugins import deepgram, openai, assemblyai
3

4
session = AgentSession(
5
    stt=stt.FallbackAdapter([
6
        deepgram.STT(),
7
        assemblyai.STT(),
8
    ]),
9
    llm=llm.FallbackAdapter([
10
        openai.LLM(model="gpt-4o"),
11
        openai.LLM.with_azure(model="gpt-4o", ...),
12
    ]),
13
)

How it works

1. The entrypoint() function is wrapped in a try/except that catches any exception during setup.
2. When an exception occurs, the agent logs the error and performs cleanup based on the chosen strategy.
3. For SIP calls, deleting the room or removing the SIP participant ensures the caller isn't left on a silent line.
4. For errors during an active session, the error event and FallbackAdapter provide runtime resilience.

Best practices

• Always wrap your entrypoint: Even if your setup code looks safe today, external services can fail at any time. A try/except costs nothing and prevents a poor caller experience.
• Log the original error: Always log the exception with exc_info=True before cleanup so you can diagnose the root cause.
• Clean up the API client: Use await lkapi.aclose() in a finally block to prevent resource leaks.
• Handle cleanup failures: The cleanup itself can fail (network issues, permissions). Wrap it in its own try/except so a cleanup failure doesn't mask the original error.
• Consider a shutdown callback: Use ctx.add_shutdown_callback() for cleanup that should run regardless of how the entrypoint exits.