Why Your Agent Leaves on Browser Refresh (and When to Keep It)

You build a voice agent, connect from the browser, and have a great conversation. Then the user hits refresh, and the agent is gone. Reconnect, and it has no memory of what you just said. In your agent logs you see:

1
livekit.agents - closing agent session due to participant disconnect

This is working as designed, but the default is tuned for telephony, not for long-lived web and mobile sessions. This guide explains what's actually happening, how to keep the agent in the room across a reconnect, and (because this is the part people skip) when you should not change the default.

Background: two separate things end a session#

When a browser refreshes, the WebRTC connection drops with the disconnect reason CLIENT_INITIATED. Two independent mechanisms react to that, and to keep an agent alive you have to understand both.

1. The agent SDK closes the session (the immediate cause)#

AgentSession talks to a single linked participant, which by default is the first non-agent participant to join. RoomIO watches that participant, and when they disconnect it closes the session:

1
# livekit-agents/livekit/agents/voice/room_io/room_io.py
2
def _on_participant_disconnected(self, participant: rtc.RemoteParticipant) -> None:
3
    if not (linked := self.linked_participant) or participant.identity != linked.identity:
4
        return
5
    self._participant_available_fut = asyncio.Future[rtc.RemoteParticipant]()
6

7
    if (
8
        self._options.close_on_disconnect
9
        and participant.disconnect_reason in DEFAULT_CLOSE_ON_DISCONNECT_REASONS
10
        and not self._close_session_atask
11
        and not self._delete_room_task
12
    ):
13
        logger.info("closing agent session due to participant disconnect ...")
14
        self._agent_session._close_soon(reason=CloseReason.PARTICIPANT_DISCONNECTED)

close_on_disconnect defaults to True, and the reasons that trigger it are:

1
# livekit-agents/livekit/agents/voice/room_io/types.py
2
DEFAULT_CLOSE_ON_DISCONNECT_REASONS: list[rtc.DisconnectReason.ValueType] = [
3
    rtc.DisconnectReason.CLIENT_INITIATED,
4
    rtc.DisconnectReason.ROOM_DELETED,
5
    rtc.DisconnectReason.USER_REJECTED,
6
]

A refresh is CLIENT_INITIATED, so the session closes immediately, before any room timeout matters. That's the log line above, and it's why the reconnected page meets a fresh, amnesiac agent. This option is documented under Agent session → Clean up options.

2. The server closes the room when the last human leaves#

Separately, LiveKit Cloud manages the room's lifecycle. The rule is specific: a room "is automatically closed when the last non-agent participant leaves" (Server lifecycle). Agents do not keep a room alive. Once the last human leaves, the room closes after a short grace period, the departureTimeout (default 20 seconds), and "any remaining agents disconnect."

This is the subtlety that trips people up: emptyTimeout and departureTimeout are real, but they don't override the agent-side close_on_disconnect, and they key off humans, not agents. So even if you stop mechanism #1, the room itself is on a countdown the moment your user disconnects.

The whole decision, from a disconnect to what happens to the agent, fits in one picture:

Keeping the agent alive across a reconnect#

Step 1: turn off close_on_disconnect#

Pass it through RoomOptions (Python) / RoomInputOptions (Node.js) when you start the session:

1
from livekit.agents import room_io
2

3
await session.start(
4
    agent=my_agent,
5
    room=ctx.room,
6
    room_options=room_io.RoomOptions(close_on_disconnect=False),
7
)

1
// Node.js
2
await session.start({
3
  agent: myAgent,
4
  room: ctx.room,
5
  inputOptions: { closeOnDisconnect: false },
6
});

Now the disconnect no longer tears down the session. The agent keeps its conversation history, so when the user returns it still remembers what they said.

Step 2: give the room a departureTimeout that covers the gap#

Because the server starts the room-close countdown when the last human leaves, set a departureTimeout long enough to outlast a reconnect. A refresh reconnects in a second or two, but for an interview agent where a candidate might lose Wi-Fi or step away, you may want minutes. Configure it in the room configuration you attach to the token (or via CreateRoom):

1
from livekit.api import RoomConfiguration
2

3
# In the token used by the browser client
4
room_config = RoomConfiguration(
5
    departure_timeout=300,  # keep the room open 5 min after the last human leaves
6
    empty_timeout=300,      # and 5 min if no one ever joins
7
)

Step 3: reconnect with the same identity#

When the user reconnects, they must use the same participant identity. RoomIO re-resolves its linked participant when someone rejoins, so a matching identity re-links the agent to the same person automatically. A new random identity each load will look like a different user.

The result: refresh the page, reconnect, and the agent is still there, mid-conversation.

In-session memory vs. remembering across sessions#

Keeping the session alive solves in-session memory. The agent holds the conversation in its ChatContext for as long as the AgentSession lives, so a refresh that reconnects in time finds everything intact. But that memory is still tied to one session. Once the room finally closes (the user is gone past departureTimeout, or closes the tab for good), the session ends and that context is gone. The next time the same person connects, they get a brand-new session that starts from zero.

If you want the agent to greet a returning user by name or recall what they said last week, you need persistent memory: write the relevant facts to a database keyed by a stable user id, then load them back at the start of the next session. LiveKit gives you the two hooks this needs. Identify the user from job metadata before ctx.connect() and pre-load their profile into the ChatContext, then persist a session report on hangup with the on_session_end callback.

For a complete, working example, see MongoDB Vector Search for Voice Agents, which wires Atlas into a LiveKit agent for per-user memory and includes a clonable starter kit. A demo video shows it in action.

Don't strand the agent: how it should leave#

Turning off close_on_disconnect creates a new risk: an agent that never leaves, holding a worker process and live STT/LLM/TTS connections (and the bill that comes with them). Pair it with a cleanup path. You have three options, and they compose:

Let the room timeout do it (simplest). With close_on_disconnect=False and a departureTimeout of, say, 300s, the agent survives short blips but the server still closes the room (and disconnects the agent) once the user is gone past the timeout. Cleanup is automatic and bounded.

Detect an absent user in the agent (most control). Use user_away_timeout with the user_state_changed event to notice silence, prompt a few times, then shut down:

1
import asyncio
2
from livekit.agents import AgentSession, UserStateChangedEvent
3

4
session = AgentSession(user_away_timeout=15.0)  # seconds of silence → "away"
5

6
inactivity_task: asyncio.Task | None = None
7

8
async def check_if_user_present():
9
    for _ in range(3):
10
        await session.generate_reply(
11
            instructions="The user has been quiet. Politely check if they're still there."
12
        )
13
        await asyncio.sleep(10)
14
    session.shutdown()  # give up and end the session
15

16
@session.on("user_state_changed")
17
def _on_user_state_changed(ev: UserStateChangedEvent):
18
    global inactivity_task
19
    if ev.new_state == "away":
20
        inactivity_task = asyncio.create_task(check_if_user_present())
21
    elif inactivity_task:
22
        inactivity_task.cancel()
23
        inactivity_task = None

Delete the room immediately on close. If you want the room gone the instant the session ends rather than lingering for the grace period, set delete_room_on_close=True.

Telephony vs. web: branch on the participant kind#

close_on_disconnect is a single session-level setting (a plain bool on RoomOptions), not something you can scope per participant. It applies to whichever participant the session is linked to, whether that's a STANDARD web user or a SIP caller. That matters because the same disconnect reason means opposite things for the two kinds:

• STANDARD (browser, mobile): a CLIENT_INITIATED disconnect is often just a refresh or a brief network blip. You usually want to stay.
• SIP (telephony): a clean hangup (a SIP BYE from either side) also surfaces as CLIENT_INITIATED (Handling mid-call disconnections). But a hangup is final: there is no "reconnect," and you want to end the session and free the worker right away.

So you can't tell intent from the disconnect reason alone. You have to look at the participant kind.

If your agent only ever serves one kind, pick the matching default: web and mobile get close_on_disconnect=False plus a cleanup path, while pure telephony keeps the default close_on_disconnect=True so a hangup ends the call immediately.

If a single agent serves both (a common setup, since the same entrypoint can take inbound calls and web sessions), keep close_on_disconnect=False for the web case and add a participant_disconnected handler that shuts down when the caller is a SIP participant:

1
from livekit import rtc
2

3
# With close_on_disconnect=False, the agent survives web refreshes.
4
# A phone hangup, though, is final: end the session right away.
5
@ctx.room.on("participant_disconnected")
6
def on_participant_disconnected(participant: rtc.RemoteParticipant):
7
    # A clean SIP hangup (BYE) arrives as CLIENT_INITIATED, the same reason a
8
    # browser refresh uses, so branch on the participant kind, not the reason.
9
    if participant.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP:
10
        session.shutdown()

Identify SIP callers with participant.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP (see Identifying SIP callers). For richer SIP-only behavior, inspect the SIP attributes such as sip.phoneNumber.

When to keep close_on_disconnect=False, and when not to#

This is the decision that matters. Setting it the wrong way either frustrates users or quietly burns money.

Keep the agent alive (close_on_disconnect=False) when:#

• Browser and mobile sessions where a refresh, tab switch, or network blip is routine and expected.
• Long or high-stakes sessions such as interviews, tutoring, or support, where a momentary drop shouldn't throw away the conversation.
• Multi-party rooms where one participant leaving shouldn't end the agent for everyone else.

In all of these, always pair it with a cleanup path (a sane departureTimeout, an away-timeout shutdown, or both).

Leave the default (close_on_disconnect=True) when:#

• Telephony / SIP. A hangup is the end of the call. You want the session to close immediately and free the worker. This is exactly why the default exists; see Handling mid-call disconnections, where CLIENT_INITIATED, ROOM_DELETED, and USER_REJECTED are treated as call-ending. If one agent handles both telephony and web, see the section above on branching by participant kind.
• Single-shot tasks where a disconnect genuinely means "done."
• Cost-sensitive workloads. Every open session holds a worker process and live model connections. If you keep sessions open on disconnect without a reliable shutdown path, a flaky network can leave a pile of orphaned agents running indefinitely.

The short version: close_on_disconnect=True optimizes for freeing resources fast; False optimizes for not losing the conversation. Pick based on whether a disconnect in your app means "the user is done" or "the user will be right back." If you pick False, make sure something still ends the session when they're truly gone.

Related resources#

• Agent session → Clean up options: close_on_disconnect and delete_room_on_close
• Handling inactive users: user_away_timeout and the away/shutdown pattern
• Server lifecycle: when rooms close and agents disconnect
• Room management: room lifecycle and creation
• Room service API reference: the emptyTimeout and departureTimeout fields (with defaults) on CreateRoom and RoomConfiguration
• Events and error handling: CloseReason, user_state_changed, and session events
• Types of participants: the STANDARD, SIP, and AGENT participant kinds
• Identifying SIP callers: branching on participant.kind for telephony
• MongoDB Vector Search for Voice Agents: persistent per-user memory that survives across sessions
• Handling mid-call disconnections (telephony): why the default closes on CLIENT_INITIATED
• room_io.py and types.py: the disconnect-handling source