What is the precise difference between a room and a session? Why

room_id

is actually a

session_id

? Why are these two concepts divideed?

Thanks for reaching out, Hugo. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.

But first a session exists, then a room is created, or at least that's what we see in the logs. Is that correct? If we use livekit-agents, how does one agent process map to sessions and rooms? Is one process one session?

Thanks — good observations. I’ll clarify the lifecycle and how agent processes map to sessions and rooms. Quick answer • A room is created first, then an agent session starts when the agent connects to that existing room. • With livekit-agents, each agent process corresponds to one session: the agent server accepts a job for a room and starts a dedicated process to handle that session. What’s happening in the logs • When a participant joins a room using a valid token, the Room is created (or ensured exist) by the server. • After the room exists, the agent server receives the job for that room, accepts it, and starts the agent session (a separate process) which then connects into that room. • That ordering explains why you may see a room creation event in logs before you see the agent session connect. Why one process per session • The agent server starts a new process for each accepted job to handle the session, giving isolation between sessions and simplifying lifecycle management. • So one agent process = one session for that room instance. If you want, tell me: • Which log lines or timestamps you’re looking at (paste a snippet), and I can walk through precisely which event maps to room creation vs. agent session start. Sources: CreateRoom() is taking too long | LiveKit | Job lifecycle | LiveKit Documentation

What are the common reasons if sometimes we see a room created, the user joins the room in one session, the session ends after a few minutes, then agent joins the same room again in a separate session.

Thanks — great follow-up. I’ll explain why you might see a user session end and then an agent join the same room later, and give a few practical ways to diagnose and avoid surprises. Short summary • Rooms are created first (when someone joins with a valid token), then agent sessions connect to that existing room. • With livekit-agents, each agent process maps to a single session—so when an agent job runs it starts a new process/session that joins the room. • Seeing a user join/leave and then an agent join later in a separate session is expected and commonly caused by dispatch timing, room persistence, reuse of room names, or explicit backend triggers. Common reasons this pattern appears • Agent dispatch delay or retry ◦ If no agent is immediately available (server under load, restarting, or temporarily unreachable), dispatch is delayed or retried. The agent then accepts the job later and spawns a new process/session that joins the already-created room. • Room persistence / departure timeout ◦ Rooms often persist for a short grace period after the last participant leaves (e.g., a departure timeout) rather than being deleted immediately. A later agent dispatch can join that still-existing room in a new session. • Static or reused room names ◦ If you use the same room name for multiple uses (for example user-based room names), an agent can be dispatched later to join that same name; because each join creates a new session/process, it looks like a new session for the “same” room. • Explicit backend/automation triggers ◦ Your backend or workflows may intentionally trigger an agent to join an existing room after the user leaves (for post-processing, summarization, egress, etc.). That results in a new agent session. • SIP or routing rules ◦ In SIP/inbound call flows, routing rules may connect different callers/agents at different times to the same room name, producing separate sessions. • Room deletion and recreation edge-cases ◦ If a room is deleted and quickly recreated with the same name, you may see a new session that appears to reuse the room identity. Use Room SID vs. room name to disambiguate. How agent processes map to sessions • One agent job → server starts a dedicated agent process to handle the job → that process creates/owns a single session when it connects to the room. So yes: one process = one session for that agent run, ensuring isolation. Practical diagnostics to pin down what’s happening • Correlate timestamps: compare room creation, participant join/leave, and agent connect timestamps to confirm ordering. • Use Room SID vs. room name: log and compare the server-assigned Room SID (persistent identifier) and any session IDs in webhooks/payloads to tell whether agent joined the same room instance or a recreated one. • Inspect agent job lifecycle logs: check the agent dispatcher and agent server logs for delays, retries, or rejected jobs at the time the room was created. • Check departure_timeout and room TTL settings: confirm how long rooms persist after last participant leaves. • Search for external triggers: scan backend jobs, webhooks, or automation that may call the agent to join later (egress/recording triggers, summarization jobs). • If SIP is involved: review routing and trunk logs to see if inbound calls or re-routes caused the agent join. Practical mitigation strategies • Use unique room names per logical session (append a timestamp or UUID) when you need strict one-to-one mapping between room instance and user activity. • If you must reuse names, rely on Room SID or explicit session IDs to track per-instance data (recordings, billing, analytics). • Add instrumentation around agent dispatch to surface delays/retries and to tie agent job IDs to agent process sessions. • If agents must join immediately, ensure adequate agent capacity and health checks so dispatch doesn’t queue or retry. If you want, I can: • Walk through specific log snippets you’ve observed (paste a few timestamped lines) and point out which lines are room creation, user session start/end, and agent job start. • Help map your webhook/event payload fields (e.g.,

roomId

values) to Room SID vs. session ID so you can confidently correlate artifacts. Which would you prefer — share a short log snippet or an example webhook payload and I’ll annotate it for you? Sources: Server lifecycle | LiveKit Documentation | Ensuring Unique Room IDs with Dynamic Room Names | LiveKit | examples/bank-ivr | livekit/livekit_composite | DeepWiki | Why is there extra audio at the end of my recordings of an agent session? |...

If no agent is immediately available (server under load, restarting, or temporarily unreachable), dispatch is delayed or retried. The agent then accepts the job later and spawns a new process/session that joins the already-created room.

When might this happen? How to look for these situations in the logs?

Thanks — good question. I’ll explain when agent dispatch can be delayed or retried, what to look for in logs, and concrete log signals you can search for so you can detect these situations quickly. When dispatch delays or retries commonly happen • Agent server is under load (too many concurrent jobs) and can’t accept a new job immediately. • Agent server(s) are restarting or temporarily offline (deploys, crashes, or network interruptions). • Agent registration/heartbeat to the dispatcher times out, so the dispatcher skips that agent and retries later. • Transient network issues between the dispatcher and agent server cause job delivery failures. • Job acceptance logic rejects the job initially (capacity checks, resource limits, or version mismatches) and the dispatcher retries with another agent later. • Backoff/retry logic in the dispatcher intentionally delays retries after a failure. What to look for in logs (practical indicators) • Dispatcher logs: search for phrases like job queued, job dispatched, job accepted, job rejected, job failed, job retry, and job timeout. Typical sequence to look for: a. Dispatcher issues a job dispatch for room <room_name/room_sid>. b. Dispatcher records a failure or no acknowledgement (e.g., "no agents available", "dispatch failed", "agent not registered"). c. Dispatcher retries dispatch later (look for "retrying job" or repeated dispatch attempts for same job id). • Agent server logs: search for agent registration/heartbeat and job lifecycle lines: ◦ Agent registers or heartbeats with dispatcher (successful registration lines). ◦ Agent process starts and accepts job (look for "accept job", "starting job", or "spawn process for job <job_id>"). ◦ Agent rejects job (capacity/exceptions) or shows errors connecting to LiveKit or resources. ◦ Agent crash/restart entries (stack traces, process restart messages, or container restarts). • Room / LiveKit server logs: correlate room creation and participant events: ◦ Room created at T0, user joined at T0+X, user left at T0+Y. ◦ Agent connect event appears at T0+Z where Z >> X/Y (large gap indicates delayed dispatch). ◦ Look for webhook/egress events that include `roomId`/session IDs and timestamps to correlate. • Network / infra logs: ◦ Kubernetes events (Pod OOMKilled, CrashLoopBackOff, restarts) or autoscaler logs showing temporary lack of capacity. ◦ Load balancer or service mesh connection errors indicating transient connectivity issues. Concrete log patterns to grep for • Dispatcher: "no agents available", "dispatch failed", "job queued", "retrying job", "job timeout", repeated "dispatch for job_id=<id>". • Agent: "registered", "heartbeat", "accept job", "started job", "rejected job", "error", "panic", "reconnect", "connection refused". • Or correlate by IDs: search for the same job_id, room_sid, or room name appearing in multiple log files with different timestamps. How to triage when you find a gap 1. Identify timestamps: note room creation time, user join/leave times, and first agent dispatch/accept time. 2. Search dispatcher logs around room creation for initial dispatch attempts and any retry/backoff entries. 3. Check agent server logs for registration/heartbeat around that window and any errors or rejections. 4. Check infrastructure events (deployments, pod restarts, autoscaler actions) at the same time window. 5. If the dispatcher retried, identify whether it retried to the same agent or different agents (job_id in logs helps here). Monitoring and alerts to catch this proactively • Alert on dispatcher job queue length or job retry count rising above threshold. • Alert on agent registration/heartbeat failures or agent pool size dropping below required capacity. • Instrument job lifecycle with metrics: dispatch attempts per job, time from dispatch->accept, and average dispatch latency. Alert when dispatch->accept exceeds a threshold you consider acceptable. If you want, paste a short, timestamped snippet of your dispatcher and agent logs around one occurrence and I’ll annotate the sequence and point out the specific lines that indicate delay/retry and the likely root cause. Which logs do you have handy — dispatcher, agent, or both?

We often see this message in the logs when the issue happens:

livekit_api::signal_client:167:livekit_api::signal_client - fallback connection to: <URL>

Could it be related?

Thanks — that log line is a useful clue. I’ll explain what that message means, how it can cause delayed agent dispatch, and the concrete log signals and checks you can run to confirm whether it’s the root cause. What that log line means • The message

livekit_api::signal_client ... fallback connection to: <URL>

is emitted when the Rust signal client fails or times out on its initial signaling endpoint and falls back to an alternate endpoint or retry. It’s a recovery mechanism in the signaling layer used by agent components. How it can contribute to delayed agent dispatch • Agent dispatch requires the agent process to be connected and healthy so it can accept jobs. If the agent’s signaling client is failing initial connections (and falling back), the agent may: ◦ Take longer to become “available” to the dispatcher. ◦ Temporarily appear unreachable or delayed in heartbeats/registration. ◦ Reject or be skipped for job dispatch while it’s still reconnecting. • Repeated fallback events therefore can correlate with dispatch retries or long dispatch→accept latency. What to look for in your logs (concrete checks) • Correlate timestamps: ◦ Note the time of room creation and the time the agent actually connects/accepts the job. ◦ Search for

fallback connection to:

entries near that window and see if they precede the delayed agent accept. • Dispatcher logs: ◦ Look for entries like

dispatch failed

,

no agents available

,

retrying job

,

job queued

, or repeated dispatch attempts for the same job_id/room_sid. ◦ If you see retries timed shortly after

fallback

logs, that strongly suggests a relationship. • Agent logs: ◦ Search for

registered

,

heartbeat

,

accept job

,

started job

,

rejected job

,

error

,

reconnect

, or connection timeout errors. ◦ Look for restarts, connection timeouts, or repeated fallback messages from the same agent process. • LiveKit server and room events: ◦ Verify when the Room was created, user join/leave events, and agent connect. Large gaps between user leave and agent connect are the symptom to debug. • Infra/Kubernetes logs: ◦ Check for Pod restarts, CrashLoopBackOff, OOMKilled, node/network events, or deployment rollouts around the same timestamps. • Metrics to inspect (if available): ◦ Agent dispatch latency (dispatch → accept time) ◦ Number of dispatch retries per job ◦ Agent registration/heartbeat failure counts How to triage once you find matching patterns 1. If

fallback

messages precede dispatch retries: focus on network/connectivity (DNS, TLS, routing) and agent availability. 2. If agent process shows restarts or crashes: investigate resource limits, OOM, or process-level exceptions. 3. If dispatcher shows “no agents available” without agent errors: check agent pool size, capacity limits, or throttling. 4. If infra shows transient network errors: check load balancers, service meshes, firewall rules, and any recent network changes. Short tests to confirm causation • Reproduce with controlled load: temporarily reduce agent capacity and observe if you can trigger the fallback + retry pattern. • Temporarily increase logging level for the agent signal client and dispatcher around a test window to capture detailed connection/dispatch traces. • Run

WorkerStatus

or equivalent to query agent availability and see whether agents are marked healthy during the period you observed fallbacks. Mitigations to reduce occurrence • Ensure healthy agent capacity so dispatch doesn’t queue (scale agents or add autoscaling). • Improve agent resilience to transient network issues (retries/backoff tuning, keepalive/heartbeat frequency). • Harden network (load balancer timeouts, firewall rules, DNS/TLS stability) so the initial signaling endpoint succeeds more often. • Add monitoring/alerts on dispatch latency and fallback frequency so you catch regressions early. If you’d like, I can: • Annotate a short log snippet (dispatcher + agent) you paste here and point to the exact lines showing fallback → retry → agent accept. • Suggest specific log queries or grep expressions to find the relevant lines in your logs. Would you like to paste a 20–50 line window from the dispatcher and the agent logs around one occurrence? I’ll annotate it and tell you whether the fallback is the likely cause. Sources: Rust SDKs | livekit/livekit_composite | DeepWiki | Server lifecycle | LiveKit Documentation | Why do jobs stop after agent rejection? | LiveKit | Firewall Tips for LiveKit Connectivity | LiveKit