Order and necessity of using session.start and ctx.connect

Agents
,
1

This question originally came up in our Slack community and the thread has been consolidated here for long-term reference.

Hi! Could you please clarify the order and necessity of using session.start and ctx.connect in the AI agent code?
I have seen example where the session.start goes first and ctx.connect second, reverse order and with the ctx.connect missing. I checked the guides and the docs but it’s still not clear for me; they are quite short: docs on JobContext.connect is quite short “Connect to the room. […]” (ref) and the docs on the AgentSession.start say “Start the voice agent. […]” (ref). I’m talking about the usage in the entrypoint function with @server.rtc_session() decorator.
Could you clarify what these methods do/refer to the relevant pages, so the order and the necessity of using them is more clear?

2

The order depends on whether you use RoomIO:

  1. When using room=ctx.room in session.start() (most common): You can omit ctx.connect() entirely. The framework automatically calls it for you (agent_session.py:616-618). This is the pattern shown in the README example (README.md:98-119).
  2. When calling ctx.connect() explicitly: Call it before session.start(). This ensures the room connection is established before the session tries to use it (README.md:312-323).
  3. When NOT using RoomIO (custom I/O setup): You must call ctx.connect() yourself, as the automatic connection only happens when RoomIO is created.