Use lk agent for console, dev, and start

AGENTS.md

@@ -6,9 +6,9 @@ The following is a guide for working with this project.
 
 ## Project structure
 
-This Python project uses the `uv` package manager. You should always use `uv` to install dependencies, run the agent, and run tests.
+This Python project uses the `uv` package manager. You should always use `uv` to install dependencies and run tests. To run the agent itself, use the LiveKit CLI: `lk agent console` to talk to it in the terminal, `lk agent dev` for a reloading development server, and `lk agent start` for production mode. See the [agent commands reference](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/) for the options each one accepts.
 
-All app-level code is in the `src/` directory. In general, simple agents can be constructed with a single `agent.py` file. Additional files can be added, but you must retain `agent.py` as the entrypoint (see the associated Dockerfile for how this is deployed).
+All app-level code is in the `src/` directory. In general, simple agents can be constructed with a single `agent.py` file. Additional files can be added, but you must retain `agent.py` as the entrypoint (the Dockerfile and the CLI's entrypoint detection both expect `src/agent.py`).
 
 Be sure to maintain code formatting. You can use the ruff formatter/linter as needed: `uv run ruff format` and `uv run ruff check`.
 

README.md

@@ -27,7 +27,24 @@ This starter app is compatible with any [custom web/mobile frontend](https://doc
 
 This project is designed to work with coding agents like [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), and [Codex](https://openai.com/codex/).
 
-For your convenience, LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) that can be used to browse and search its documentation. The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) (`lk docs`) works with any coding agent that can run shell commands. Install it for your platform:
+For your convenience, LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) that can be used to browse and search its documentation. The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) (`lk docs`) works with any coding agent that can run shell commands. See [Install the LiveKit CLI](#install-the-livekit-cli) below for installation instructions.
+
+Once installed, your coding agent can search and browse LiveKit documentation directly from the terminal:
+
+```console
+lk docs search "voice agents"
+lk docs get-page /agents/start/voice-ai-quickstart
+```
+
+See the [Using coding agents](https://docs.livekit.io/intro/coding-agents/) guide for more details, including MCP server setup.
+
+The project includes a complete [AGENTS.md](AGENTS.md) file for these assistants. You can modify this file to suit your needs. To learn more about this file, see [https://agents.md](https://agents.md).
+
+## Dev Setup
+
+### Install the LiveKit CLI
+
+The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) creates the project and runs the agent locally. Install it for your platform:
 
 **macOS:**
 
@@ -47,20 +64,11 @@ curl -sSL https://get.livekit.io/cli | bash
 winget install LiveKit.LiveKitCLI
 ```
 
-The `lk docs` subcommand requires version 2.15.0 or higher. Check your version with `lk --version` and update if needed. Once installed, your coding agent can search and browse LiveKit documentation directly from the terminal:
+Requires version 2.15.0 or higher. Check your version with `lk --version` and update if needed.
 
-```console
-lk docs search "voice agents"
-lk docs get-page /agents/start/voice-ai-quickstart
-```
+### Create the project
 
-See the [Using coding agents](https://docs.livekit.io/intro/coding-agents/) guide for more details, including MCP server setup.
-
-The project includes a complete [AGENTS.md](AGENTS.md) file for these assistants. You can modify this file to suit your needs. To learn more about this file, see [https://agents.md](https://agents.md).
-
-## Dev Setup
-
-Create a project from this template with the LiveKit CLI (recommended):
+Create a project from this template with the CLI (recommended):
 
 ```bash
 lk cloud auth
@@ -70,7 +78,7 @@ lk agent init my-agent --template agent-starter-python
 The CLI clones the template and configures your environment. Then follow the rest of this guide from [Run the agent](#run-the-agent).
 
 <details>
-<summary>Alternative: Manual setup without the CLI</summary>
+<summary>Alternative: Set up the project manually</summary>
 
 Clone the repository and install dependencies to a virtual environment:
 
@@ -96,24 +104,28 @@ lk app env --write --destination .env.local
 
 ## Run the agent
 
+The `lk agent` commands run your agent on your own machine. Run them from the project root — the CLI finds `src/agent.py` on its own.
+
 Run this command to speak to your agent directly in your terminal:
 
 ```console
-uv run python src/agent.py console
+lk agent console
 ```
 
-To run the agent for use with a frontend or telephony, use the `dev` command:
+To run the agent for use with a frontend or telephony, use the `dev` command, which adds hot reload on source changes and debug-level logging:
 
 ```console
-uv run python src/agent.py dev
+lk agent dev
 ```
 
-In production, use the `start` command:
+To run it in production mode, with clean logging and graceful shutdown, use the `start` command:
 
 ```console
-uv run python src/agent.py start
+lk agent start
 ```
 
+Your deployed agent starts from the `CMD` in the [Dockerfile](Dockerfile) rather than the CLI, since the container image doesn't include `lk`. See [Server startup modes](https://docs.livekit.io/agents/server/startup-modes/) for the full set of options each command accepts.
+
 ## Frontend & Telephony
 
 Get started quickly with our pre-built frontend starter apps, or add telephony support:

taskfile.yaml

@@ -51,7 +51,7 @@ tasks:
       - echo ''
       - echo '{{ indent .INDENT "cd" }} {{ .REL_PATH }}'
       - task: help_install_hint_if_needed
-      - echo '{{ indent .INDENT "uv run" }} {{ .PYTHON_MAIN }} console'
+      - echo '{{ indent .INDENT "lk agent console" }}'
 
   help_open_web_console:
     status:
@@ -64,7 +64,7 @@ tasks:
       - echo ''
       - echo '{{ indent .INDENT "cd" }} {{ .REL_PATH }}'
       - task: help_install_hint_if_needed
-      - echo '{{ indent .INDENT "uv run" }} {{ .PYTHON_MAIN }} dev'
+      - echo '{{ indent .INDENT "lk agent dev" }}'
       - echo ''
       - echo 'Then visit:'
       - echo ''
@@ -90,4 +90,4 @@ tasks:
   dev:
     interactive: true
     cmds:
-      - "uv run src/agent.py dev"
+      - "lk agent dev"