[codeSTACKr]

What

Running the agent through its own script (uv run src/agent.py dev|console|start) is deprecated in favour of the LiveKit CLI (lk agent dev|console|start, CLI 2.19+) and the SDK's python -m livekit.agents. This follows the current agent-starter-python template and matches livekit-examples/mongodb-hacker-starter#59.

• pnpm dev runs the agent with lk agent dev --deployment local-dev, and pnpm agent:py:console uses lk agent console.
• pnpm agent:py:start and the Docker CMD use uv run -m livekit.agents start src/agent.py, exactly what lk agent start runs. agent.py keeps the template's __main__ / cli.run_app(server), but nothing documented goes through it anymore. That path emits the "built-in Python CLI is deprecated" DeprecationWarning, which the template's Dockerfile CMD still triggers.
• Dispatch to the dev agent:
  • lk agent dev registers the worker under a deployment, a random dev-<hex> unless one is passed (LiveKit CLI resolveDevDeployment), so a frontend token that dispatches to production wouldn't reach it.
  • RoomAgentDispatch has a deployment field (protocol field 4). The token route now sets it to AGENT_DEPLOYMENT (default local-dev) when the dispatch has none; set it empty to target production (pnpm agent:py:start, Docker, LiveKit Cloud). Added to frontend/.env.example.
• CI: the --help checks (on the runner and inside the Docker image) are replaced by a worker-start smoke test. It runs python -m livekit.agents start src/agent.py against an unreachable server with PYTHONWARNINGS=default, requires "starting worker", and fails on any deprecation warning.
• Docs: README (LiveKit CLI 2.19+, deployment explanation, Dockerfile CMD), agent-py README and AGENTS.md.

Testing

• frontend: lint (0 errors), tsc --noEmit, format:check.
• Token from POST /api/token in next dev (decoded roomConfig.agents):

  [{"agentName": "agent-py", "metadata": "{\"user_id\":\"67706c17-…\"}", "restartPolicy": "JRP_ON_FAILURE", "deployment": "local-dev", "attributes": {}}]

  With AGENT_DEPLOYMENT= empty it carries "deployment": "" (production).
• The Moss agent can't run on the maintenance VM (inferedge-moss-core needs glibc 2.38), so the worker start, deprecation check and Docker run are covered by CI here.
• The same setup was verified end to end in mongodb-hacker-starter#59 against a local livekit-server with lk agent dev --deployment local-dev. The worker registered under local-dev and received the token's dispatch. A production-deployment token was not delivered to it.

🤖 Generated with Claude Code

https://claude.ai/code/session_013EcAtRg8aYia9VZrTAZ4Av