From b76bcc3887ec55846a59cbd2e0fdcc7449f291f8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 19:24:25 +0000 Subject: [PATCH 1/2] Use `lk agent` for console, dev, and start The Python CLI's dev mode is deprecated and its in-process auto-reload has been removed, so `lk agent dev` is now the only way to get hot reload. Point the README, the taskfile help output, and the `dev` task at the LiveKit CLI for all three local modes, and move the CLI install instructions into Dev Setup so they come before the first command that needs them. The Dockerfile still starts the deployed agent with `uv run src/agent.py start`, since the container image doesn't include `lk`. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv --- AGENTS.md | 4 ++-- README.md | 50 +++++++++++++++++++++++++++++++------------------- taskfile.yaml | 6 +++--- 3 files changed, 36 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5a7db78..8ddadd3 100644 --- a/AGENTS.md +++ b/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`. diff --git a/README.md b/README.md index eb0f4fd..ea74304 100644 --- a/README.md +++ b/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).
-Alternative: Manual setup without the CLI +Alternative: Set up the project manually 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 reloads the agent whenever you change its source: ```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: diff --git a/taskfile.yaml b/taskfile.yaml index 70d6b4d..dd453f7 100644 --- a/taskfile.yaml +++ b/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" From a3afb2da2eacbf09bd1c78e151464c96665b52a4 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 20:31:57 +0000 Subject: [PATCH 2/2] Describe what dev mode adds, not just reload Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ea74304..d55659a 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ Run this command to speak to your agent directly in your terminal: lk agent console ``` -To run the agent for use with a frontend or telephony, use the `dev` command, which reloads the agent whenever you change its source: +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 lk agent dev