Conversation
Precedence is now LIVEKIT_AGENT_NAME_OVERRIDE, the rtc_session agent_name arg, LIVEKIT_AGENT_NAME, then [agent] name from livekit.toml in the working directory. Dev workers skip the toml name so they never join the deployed agent's pool. A name set in code logs a deprecation warning at run().
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| if self._agent_name_source != "none" or devmode: | ||
| return | ||
| name = _toml_agent_name(os.path.join(os.getcwd(), "livekit.toml")) | ||
| if name: | ||
| self._agent_name = name | ||
| self._agent_name_source = "toml" |
There was a problem hiding this comment.
🟡 Development restart retains TOML name
A production-to-development restart keeps livekit.toml's name. _agent_name_source remains toml, so the dev worker joins the deployed dispatch pool.
Learn more
AgentServer.aclose() restores _closed, and run() supports another invocation on the same instance. The first production run changes _agent_name_source from none to toml. On a later development run, the source check returns before devmode can suppress that persisted fallback.
Example: Run one server with devmode=False and [agent] name = "deployed", close it, then run it with devmode=True. The second run still registers as deployed instead of using an empty name.
Recommended fix: When entering development mode, clear a previously resolved TOML name and reset its source to none. Preserve override, code, and environment names.
| if self._agent_name_source != "none" or devmode: | |
| return | |
| name = _toml_agent_name(os.path.join(os.getcwd(), "livekit.toml")) | |
| if name: | |
| self._agent_name = name | |
| self._agent_name_source = "toml" | |
| if devmode: | |
| if self._agent_name_source == "toml": | |
| self._agent_name = "" | |
| self._agent_name_source = "none" | |
| return | |
| if self._agent_name_source != "none": | |
| return | |
| name = _toml_agent_name(os.path.join(os.getcwd(), "livekit.toml")) | |
| if name: | |
| self._agent_name = name | |
| self._agent_name_source = "toml" |
Was this helpful? React with 👍 or 👎 to provide feedback.
| except FileNotFoundError: | ||
| return "" | ||
| except (OSError, tomllib.TOMLDecodeError) as e: | ||
| logger.debug("ignoring unreadable livekit.toml", extra={"path": path, "error": str(e)}) |
There was a problem hiding this comment.
🟨 TOML errors bypass log redaction
Unreadable configs log path and str(e) without PII markers. Customer data in either value bypasses structured-log redaction.
Was this helpful? React with 👍 or 👎 to provide feedback.
| logger.warning( | ||
| "agent_name is set in code; move it to livekit.toml ([agent] name). " | ||
| "The agent_name parameter will be removed in a future release.", | ||
| extra={"agent_name": self._agent_name}, |
There was a problem hiding this comment.
🟨 Agent name bypasses log redaction
A code-defined agent name is logged as agent_name without a PII marker. The value bypasses structured-log redaction.
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
Why
The agent name is moving out of code into
livekit.toml, checked into git, so Cloud,lk, simulations and observability can all read the same name without booting the worker. Proposal: https://app.notion.com/p/livekit/Proposal-livekit-toml-layout-for-agent-name-and-regions-3d83c4901a4281beb3b9f1f3e74de44dThis is phase 1: the SDK learns to read the file and warns about names set in code. Phase 2, a few weeks out, removes the code parameter.
What
Agent name precedence is now
LIVEKIT_AGENT_NAME_OVERRIDE, then theagent_nameargument tortc_session(code), thenLIVEKIT_AGENT_NAME, then[agent] namefrom./livekit.toml.run()and only in production.run(devmode=True)(lk agent dev,dev,console) never takes it, so dev workers stay out of the deployed agent's pool.run()logs one warning pointing atlivekit.toml. Theagent_namedocstrings mark the parameter deprecated.[agent]/name, or a malformed file means no name; malformed files log at debug.tomllibon 3.11+,tomlion 3.10 (new marker dependency,uv.lockupdated).JS parity: livekit/agents-js has the matching change.
Verification
uv run --project livekit-agents pytest tests/test_worker_config.py -q --unit: 15 passed (5 new: toml fallback, env beats toml, devmode ignores toml, missing file, code-name warning).ruff check,ruff format --checkandscripts/check_types.pyclean on touched files.