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..d55659a 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 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: 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"