From b76bcc3887ec55846a59cbd2e0fdcc7449f291f8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 19:24:25 +0000 Subject: [PATCH 01/11] 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 02/11] 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 From c6717232db8421e679023418db6556d30c299313 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 18:37:11 +0000 Subject: [PATCH 03/11] Trim the README and AGENTS.md, and apply the docs style guide Mirrors the Node starter's review round: drop guidance a coding agent can work out on its own, show the direct `uv run src/agent.py start` for production since that's what the Dockerfile runs, and collapse the CLI install block into a three-line list with a link to update instructions. Also a copy pass against the docs style guide: sentence-case headings, no "we", no hyphens standing in for dashes, bulleted rather than numbered non-sequential lists, and less filler throughout. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv --- AGENTS.md | 38 +++++++--------- README.md | 133 ++++++++++++++++++++---------------------------------- 2 files changed, 66 insertions(+), 105 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8ddadd3..45b4d6a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,24 +1,20 @@ # AGENTS.md -This is a LiveKit Agents project. LiveKit Agents is a Python SDK for building voice AI agents. This project is intended to be used with LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem. +This is a LiveKit Agents project. LiveKit Agents is a Python SDK for building voice AI agents, and this project is designed for LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem. -The following is a guide for working with this project. +## Tooling -## Project structure +This Python project uses the `uv` package manager. -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. +Be sure to maintain code formatting, using `uv run ruff format` and `uv run ruff check`. -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`). +## LiveKit documentation -Be sure to maintain code formatting. You can use the ruff formatter/linter as needed: `uv run ruff format` and `uv run ruff check`. - -## LiveKit Documentation - -LiveKit Agents is a fast-evolving project, and the documentation is updated frequently. You should always refer to the latest documentation when working with this project. For your convenience, LiveKit offers both a CLI and an MCP server that can be used to browse and search its documentation. If the developer has not yet installed the CLI, you should recommend that they install it. +LiveKit Agents changes quickly, and its documentation is updated often. Always refer to the latest documentation when working with this project. LiveKit offers both a CLI and an MCP server for browsing and searching its documentation. If the developer hasn't installed the CLI yet, recommend that they install it. ### LiveKit CLI -The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) `lk docs` subcommand gives full access to LiveKit documentation from the terminal. Requires CLI version 2.15.0+. Check with `lk --version`. +The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) `lk docs` subcommand gives full access to LiveKit documentation from the terminal. It requires CLI version 2.15.0 or later. Check with `lk --version`. Install or update the CLI: @@ -26,28 +22,28 @@ Install or update the CLI: - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` - **Windows:** `winget install LiveKit.LiveKitCLI` (update: `winget upgrade LiveKit.LiveKitCLI`) -Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, `lk docs submit-feedback`. Run `lk docs --help` before using a command for the first time, as the help text includes advice on usage and interpreting results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, as docs pages are more up-to-date and provide better context than raw code. +Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, and `lk docs submit-feedback`. Run `lk docs --help` before using a command for the first time, because the help text explains how to use it and how to interpret results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, because docs pages are more current and give better context than raw code. -### LiveKit Docs MCP Server +### LiveKit docs MCP server -For deeper IDE integration, LiveKit also offers an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) with the same documentation access. It uses Streamable HTTP transport at `https://docs.livekit.io/mcp`. Refer to your IDE's documentation for how to add it. +For deeper IDE integration, LiveKit also offers an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) with the same documentation access. It uses Streamable HTTP transport at `https://docs.livekit.io/mcp`. See your IDE's documentation for how to add it. ### Submit docs feedback to LiveKit -If you use the LiveKit CLI or MCP Server to search or browse documentation, also submit constructive feedback to LiveKit with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool. Add this to your to-do list when planning work, to ensure you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps or any other documentation gap or issue. +If you use the LiveKit CLI or MCP server to search or browse documentation, also submit constructive feedback to LiveKit with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool. Add this to your to-do list when planning work, so you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, or any other gap or issue in the docs. ## Handoffs and tasks ("workflows") -Voice AI agents are highly sensitive to excessive latency. For this reason, it's important to design complex agents in a structured manner that minimizes the amount of irrelevant context and unnecessary tools included in requests to the LLM. LiveKit Agents supports handoffs (one agent hands control to another) and tasks (tightly-scoped prompts to achieve a specific outcome) to support building reliable workflows. You should make use of these features, instead of writing long instruction prompts that cover multiple phases of a conversation. Refer to the [documentation](https://docs.livekit.io/agents/build/workflows/) for more information. +Voice AI agents are highly sensitive to latency. Design complex agents in a structured way that keeps irrelevant context and unneeded tools out of each LLM request. LiveKit Agents supports handoffs, where one agent hands control to another, and tasks, which are tightly scoped prompts that achieve a specific outcome, for building reliable workflows. Use them instead of long instruction prompts that cover several phases of a conversation. See the [workflows documentation](https://docs.livekit.io/agents/build/workflows/) for more information. ## Testing -When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to main; read the [simulations documentation](https://docs.livekit.io/agents/start/testing/simulations/) before editing them. +When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/agents/start/testing/simulations/) before editing them. -For turn-level checks that don't need a live session, use the in-process [testing framework](https://docs.livekit.io/agents/start/testing/); `tests/test_agent.py` has a commented-out example. Run those with `uv run pytest`. +For turn-level checks that don't need a live session, use the in-process [testing framework](https://docs.livekit.io/agents/start/testing/). `tests/test_agent.py` has a commented-out example. Run those tests with `uv run pytest`. -Important: When modifying core agent behavior such as instructions, tool descriptions, and tasks/workflows/handoffs, never just guess what will work. Always use test-driven development (TDD) and begin by writing tests for the desired behavior. For instance, if you're planning to add a new tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass correctly. This will ensure you are able to produce a working, reliable agent for the user. +Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Use test-driven development (TDD) and start by writing tests for the desired behavior. For example, if you're adding a tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass. This is how you produce a working, reliable agent. -## LiveKit CLI +## Other CLI commands -Beyond documentation access, the LiveKit CLI (`lk`) supports other tasks such as managing SIP trunks for telephony-based agents. Run `lk --help` to explore available commands. +Beyond documentation access, the LiveKit CLI (`lk`) handles tasks such as managing SIP trunks for telephony agents. Run `lk --help` to explore available commands. diff --git a/README.md b/README.md index d55659a..4c3c4c6 100644 --- a/README.md +++ b/README.md @@ -2,100 +2,70 @@ LiveKit logo -# LiveKit Agents Starter - Python +# LiveKit Agents starter for Python -A complete starter project for building voice AI apps with [LiveKit Agents for Python](https://github.com/livekit/agents) and [LiveKit Cloud](https://cloud.livekit.io/). +A starter project for building voice AI apps with [LiveKit Agents for Python](https://github.com/livekit/agents) and [LiveKit Cloud](https://cloud.livekit.io/). -The starter project includes: +The starter includes: -- A simple voice AI assistant, ready for extension and customization -- A voice AI pipeline built on [LiveKit Inference](https://docs.livekit.io/agents/models/inference), providing zero-configuration access to [models](https://docs.livekit.io/agents/models) from top labs - - Uses the fast, open-weight Gemma 4 31B model, [hosted by LiveKit](https://docs.livekit.io/agents/models/llm/livekit/) and tuned for optimal performance in voice AI, as the default LLM - - Uses Fish Audio S2.1 Pro for TTS, which renders the inline delivery markup that expressive mode relies on - - Supports more than 50 models from OpenAI, Cartesia, Deepgram, and other providers - - Access to a wide range of other models, including [Realtime models](https://docs.livekit.io/agents/models/realtime), through extensive plugin ecosystem -- Expressive mode, enabled by default: the framework injects the TTS provider's markup guide into the LLM prompt, so the model emits inline delivery tags (emotion, pacing, non-verbal sounds) that the TTS renders and the transcript never shows -- Eval suite based on the LiveKit Agents [testing & evaluation framework](https://docs.livekit.io/agents/start/testing/) -- [LiveKit Turn Detector](https://docs.livekit.io/agents/logic/turns/turn-detector/), an end-of-turn model that listens to the user's audio directly, combining semantic understanding with acoustic cues for state-of-the-art accuracy across 14 languages -- [Background voice cancellation](https://docs.livekit.io/transport/media/noise-cancellation/) -- Deep session insights from LiveKit [Agent Observability](https://docs.livekit.io/deploy/observability/) -- A Dockerfile ready for [production deployment to LiveKit Cloud](https://docs.livekit.io/deploy/agents/) +- A simple voice AI assistant to extend and customize. +- A voice pipeline built on [LiveKit Inference](https://docs.livekit.io/agents/models/inference), which gives you access to [models](https://docs.livekit.io/agents/models) from top labs with no extra configuration: + - The default LLM is Gemma 4 31B, an open-weight model [hosted by LiveKit](https://docs.livekit.io/agents/models/llm/livekit/) and tuned for voice AI. + - The default TTS is Fish Audio S2.1 Pro, which renders the inline delivery markup that expressive mode relies on. + - More than 50 other models are available from OpenAI, Cartesia, Deepgram, and other providers. + - [Realtime models](https://docs.livekit.io/agents/models/realtime) and many others are available through the plugin ecosystem. +- Expressive mode, on by default. The framework adds the TTS provider's markup guide to the LLM prompt, so the model emits inline delivery tags (emotion, pacing, non-verbal sounds) that the TTS renders and the transcript omits. +- [LiveKit Turn Detector](https://docs.livekit.io/agents/logic/turns/turn-detector/), an end-of-turn model that listens to the user's audio directly and combines semantic understanding with acoustic cues, in 14 languages. +- [Background voice cancellation](https://docs.livekit.io/transport/media/noise-cancellation/). +- Session insights from LiveKit [Agent Observability](https://docs.livekit.io/deploy/observability/). +- [Simulations](https://docs.livekit.io/agents/start/testing/simulations/) that test full conversations with your agent, run in CI on every merge to `main`. +- A `Dockerfile` for [deploying to LiveKit Cloud](https://docs.livekit.io/deploy/agents/). -This starter app is compatible with any [custom web/mobile frontend](https://docs.livekit.io/frontends/) or [telephony](https://docs.livekit.io/telephony/). +The starter works with any [custom web or mobile frontend](https://docs.livekit.io/frontends/) or with [telephony](https://docs.livekit.io/telephony/). ## Using coding agents -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/). +This project works 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. 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: +LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) for browsing and searching its documentation. For example: ```console -lk docs search "voice agents" -lk docs get-page /agents/start/voice-ai-quickstart +lk docs search "testing my agent" ``` -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 +See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup. -### Install the LiveKit CLI +## Dev setup -The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) creates the project and runs the agent locally. Install it for your platform: +Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.15.0 or later: -**macOS:** +- **macOS:** `brew install livekit-cli` +- **Linux:** `curl -sSL https://get.livekit.io/cli | bash` +- **Windows:** `winget install LiveKit.LiveKitCLI` -```console -brew install livekit-cli -``` +Check your version with `lk --version`. To update an existing install, see [Update the CLI](https://docs.livekit.io/reference/developer-tools/livekit-cli/#updates). -**Linux:** +Then create a project from this template. The CLI clones the template and configures your environment: ```console -curl -sSL https://get.livekit.io/cli | bash -``` - -**Windows:** - -```console -winget install LiveKit.LiveKitCLI -``` - -Requires version 2.15.0 or higher. Check your version with `lk --version` and update if needed. - -### Create the project - -Create a project from this template with the CLI (recommended): - -```bash lk cloud auth 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: Set up the project manually +Set up the project manually -Clone the repository and install dependencies to a virtual environment: +Clone the repository and install dependencies into a virtual environment with [uv](https://docs.astral.sh/uv/): ```console +git clone https://github.com/livekit-examples/agent-starter-python.git cd agent-starter-python uv sync ``` -Sign up for [LiveKit Cloud](https://cloud.livekit.io/) then set up the environment by copying `.env.example` to `.env.local` and filling in the required keys: - -- `LIVEKIT_URL` -- `LIVEKIT_API_KEY` -- `LIVEKIT_API_SECRET` +Sign up for [LiveKit Cloud](https://cloud.livekit.io/), then copy `.env.example` to `.env.local` and fill it in. To have the CLI write your project's URL and API keys into the file instead, run: -You can load the LiveKit environment automatically using the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/): - -```bash +```console lk cloud auth lk app env --write --destination .env.local ``` @@ -104,31 +74,27 @@ 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: +The `lk agent console` and `lk agent dev` commands run your agent on your own machine. To talk to it in your terminal: ```console lk agent console ``` -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: +To connect it to LiveKit Cloud so a frontend or phone call can reach it: ```console lk agent dev ``` -To run it in production mode, with clean logging and graceful shutdown, use the `start` command: +In production, run the agent directly: ```console -lk agent start +uv run src/agent.py 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. +## Frontends and telephony -## Frontend & Telephony - -Get started quickly with our pre-built frontend starter apps, or add telephony support: +Pair the agent with a prebuilt frontend starter, or add telephony: | Platform | Link | Description | |----------|----------|-------------| @@ -140,36 +106,35 @@ Get started quickly with our pre-built frontend starter apps, or add telephony s | **Web Embed** | [`livekit-examples/agent-starter-embed`](https://github.com/livekit-examples/agent-starter-embed) | Voice AI widget for any website | | **Telephony** | [Documentation](https://docs.livekit.io/telephony/) | Add inbound or outbound calling to your agent | -For advanced customization, see the [complete frontend guide](https://docs.livekit.io/frontends/). +For more options, see the [frontend guide](https://docs.livekit.io/frontends/). ## Tests and evals -Simulations run full multi-turn conversations between a simulated user and your agent on LiveKit Cloud, then judge each transcript. The scenarios live in [`scenarios.yaml`](scenarios.yaml). Run them locally with the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/): +Simulations run full multi-turn conversations between a simulated user and your agent on LiveKit Cloud, then judge each transcript. The scenarios live in [`scenarios.yaml`](scenarios.yaml). Run them locally with the CLI: ```console lk agent simulate --scenarios scenarios.yaml ``` -The `Simulations` workflow in `.github/workflows/simulations.yml` runs the same file on every merge to `main` and on demand from the Actions tab. It runs there rather than on every pull request push because each run spends real inference. See the [simulations guide](https://docs.livekit.io/agents/start/testing/simulations/) for how to write scenarios and read results. - -For turn-level checks that don't need a live session, the LiveKit Agents [testing & evaluation framework](https://docs.livekit.io/agents/start/testing/) runs your agent in-process under `pytest`. A commented-out example lives in [`tests/test_agent.py`](tests/test_agent.py). +The `Simulations` workflow in [`.github/workflows/simulations.yml`](.github/workflows/simulations.yml) runs the same file on every merge to `main`, and on demand from the Actions tab. It doesn't run on every pull request push because each run uses real inference. See the [simulations guide](https://docs.livekit.io/agents/start/testing/simulations/) for how to write scenarios and read results. -## Using this template repo for your own project +For turn-level checks that don't need a live session, the LiveKit Agents [testing and evaluation framework](https://docs.livekit.io/agents/start/testing/) runs your agent in-process under `pytest`. [`tests/test_agent.py`](tests/test_agent.py) has a commented-out example. -Once you've started your own project based on this repo, you should: +## Using this template for your own project -1. **Check in your `uv.lock`**: This file is currently untracked for the template, but you should commit it to your repository for reproducible builds and proper configuration management. (The same applies to `livekit.toml`, if you run your agents in LiveKit Cloud) +After you create your own project from this template: -2. **Add your own repository secrets**: You must [add secrets](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/using-secrets-in-github-actions) for `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` so that the simulations can run in CI. +- **Commit `uv.lock`.** The template doesn't track it, but your project should, for reproducible builds. If you deploy to LiveKit Cloud, commit `livekit.toml` too. +- **Add repository secrets.** Add `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` as [repository secrets](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/using-secrets-in-github-actions) so the simulations can run in CI. ## Deploying to production -This project is production-ready and includes a working `Dockerfile`. To deploy it to LiveKit Cloud or another environment, see the [deploying to production](https://docs.livekit.io/deploy/agents/) guide. +To deploy the agent to LiveKit Cloud or another environment with the included `Dockerfile`, see the [deployment guide](https://docs.livekit.io/deploy/agents/). ## Self-hosted LiveKit -You can also self-host LiveKit instead of using LiveKit Cloud. See the [self-hosting](https://docs.livekit.io/transport/self-hosting/local/) guide for more information. If you choose to self-host, you'll need to also use [model plugins](https://docs.livekit.io/agents/models/#plugins) instead of LiveKit Inference and will need to remove the [LiveKit Cloud noise cancellation](https://docs.livekit.io/transport/media/noise-cancellation/) plugin. +You can self-host LiveKit instead of using LiveKit Cloud. See the [self-hosting guide](https://docs.livekit.io/transport/self-hosting/local/). If you self-host, use [model plugins](https://docs.livekit.io/agents/models/#plugins) instead of LiveKit Inference, and remove the [LiveKit Cloud noise cancellation](https://docs.livekit.io/transport/media/noise-cancellation/) plugin. ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. From e8666760fcba32b4f0f8de2bd14d51251cb93265 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 19:47:32 +0000 Subject: [PATCH 04/11] Sell outcomes in the feature list, and cover skills and debugging The README feature list now says what each piece does for you and links the docs for how: Fish Audio as an expressive, cost-effective default, expressive mode, and adaptive interruption handling, which the starter enables but the list never mentioned. "Using coding agents" points at the bundled AGENTS.md and livekit-agents skill, and the testing section adds Agent Console and `lk agent logs` for debugging. AGENTS.md gains a section on the bundled skill (with a fallback path for tools that do not load skills on their own) and a debugging checklist. Links to the moved testing, observability, and workflows pages now point at their current paths. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv --- AGENTS.md | 20 +++++++++++++++++--- README.md | 29 ++++++++++++++++------------- 2 files changed, 33 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 45b4d6a..55fe584 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,18 +32,32 @@ For deeper IDE integration, LiveKit also offers an [MCP server](https://docs.liv If you use the LiveKit CLI or MCP server to search or browse documentation, also submit constructive feedback to LiveKit with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool. Add this to your to-do list when planning work, so you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, or any other gap or issue in the docs. +## LiveKit Agents skill + +This project includes the `livekit-agents` skill in `.claude/skills/` and `.agents/skills/`. It covers how to approach agent architecture, workflows, handoffs, tasks, and testing, and it defers to the live documentation for API details. If your tool doesn't load skills automatically, read `.agents/skills/livekit-agents/SKILL.md` before you design or restructure an agent. + ## Handoffs and tasks ("workflows") -Voice AI agents are highly sensitive to latency. Design complex agents in a structured way that keeps irrelevant context and unneeded tools out of each LLM request. LiveKit Agents supports handoffs, where one agent hands control to another, and tasks, which are tightly scoped prompts that achieve a specific outcome, for building reliable workflows. Use them instead of long instruction prompts that cover several phases of a conversation. See the [workflows documentation](https://docs.livekit.io/agents/build/workflows/) for more information. +Voice AI agents are highly sensitive to latency. Design complex agents in a structured way that keeps irrelevant context and unneeded tools out of each LLM request. LiveKit Agents supports handoffs, where one agent hands control to another, and tasks, which are tightly scoped prompts that achieve a specific outcome, for building reliable workflows. Use them instead of long instruction prompts that cover several phases of a conversation. See the [workflows documentation](https://docs.livekit.io/agents/logic/workflows/) for more information. ## Testing -When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/agents/start/testing/simulations/) before editing them. +When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/testing/simulations/) before editing them. -For turn-level checks that don't need a live session, use the in-process [testing framework](https://docs.livekit.io/agents/start/testing/). `tests/test_agent.py` has a commented-out example. Run those tests with `uv run pytest`. +For turn-level checks that don't need a live session, use the in-process [unit testing framework](https://docs.livekit.io/testing/unit-tests/). `tests/test_agent.py` has a commented-out example. Run those tests with `uv run pytest`. Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Use test-driven development (TDD) and start by writing tests for the desired behavior. For example, if you're adding a tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass. This is how you produce a working, reliable agent. +## Debugging + +To investigate unexpected agent behavior: + +- Reproduce it in a unit test or simulation scenario first, so you have a repeatable case to iterate against. +- Run `lk agent dev --log-level DEBUG` for verbose logs from a local agent. +- Run `lk agent logs` to stream logs from a deployed agent. +- Ask the developer to open the [Agent Console](https://docs.livekit.io/testing/agent-console/), which shows events, tool calls, and model timing for a live session. +- For sessions with real users, check [Agent Observability](https://docs.livekit.io/testing/observability/) for transcripts, traces, logs, and recordings. + ## Other CLI commands Beyond documentation access, the LiveKit CLI (`lk`) handles tasks such as managing SIP trunks for telephony agents. Run `lk --help` to explore available commands. diff --git a/README.md b/README.md index 4c3c4c6..c0e6f3a 100644 --- a/README.md +++ b/README.md @@ -8,17 +8,18 @@ A starter project for building voice AI apps with [LiveKit Agents for Python](ht The starter includes: -- A simple voice AI assistant to extend and customize. -- A voice pipeline built on [LiveKit Inference](https://docs.livekit.io/agents/models/inference), which gives you access to [models](https://docs.livekit.io/agents/models) from top labs with no extra configuration: +- A simple [voice AI assistant](https://docs.livekit.io/agents/start/voice-ai/) to extend and customize. +- A voice pipeline built on [LiveKit Inference](https://docs.livekit.io/agents/models/inference/), which gives you access to [models](https://docs.livekit.io/agents/models/) from top labs with no extra configuration: - The default LLM is Gemma 4 31B, an open-weight model [hosted by LiveKit](https://docs.livekit.io/agents/models/llm/livekit/) and tuned for voice AI. - - The default TTS is Fish Audio S2.1 Pro, which renders the inline delivery markup that expressive mode relies on. + - The default TTS is [Fish Audio S2.1 Pro](https://docs.livekit.io/agents/models/tts/fishaudio/), an expressive and cost-effective voice. - More than 50 other models are available from OpenAI, Cartesia, Deepgram, and other providers. - - [Realtime models](https://docs.livekit.io/agents/models/realtime) and many others are available through the plugin ecosystem. -- Expressive mode, on by default. The framework adds the TTS provider's markup guide to the LLM prompt, so the model emits inline delivery tags (emotion, pacing, non-verbal sounds) that the TTS renders and the transcript omits. -- [LiveKit Turn Detector](https://docs.livekit.io/agents/logic/turns/turn-detector/), an end-of-turn model that listens to the user's audio directly and combines semantic understanding with acoustic cues, in 14 languages. + - [Realtime models](https://docs.livekit.io/agents/models/realtime/) and many others are available through the [plugin ecosystem](https://docs.livekit.io/agents/models/#plugins). +- [Expressive mode](https://docs.livekit.io/agents/models/tts/expressive/), on by default, so your agent's voice carries emotion and pacing that fit the conversation. +- [LiveKit Turn Detector](https://docs.livekit.io/agents/logic/turns/turn-detector/), which knows when the user has finished speaking, in 14 languages. +- [Adaptive interruption handling](https://docs.livekit.io/agents/logic/turns/adaptive-interruption-handling/), which tells a real interruption from an "uh-huh" or background noise, so your agent doesn't stop talking when it shouldn't. - [Background voice cancellation](https://docs.livekit.io/transport/media/noise-cancellation/). -- Session insights from LiveKit [Agent Observability](https://docs.livekit.io/deploy/observability/). -- [Simulations](https://docs.livekit.io/agents/start/testing/simulations/) that test full conversations with your agent, run in CI on every merge to `main`. +- Session transcripts, traces, and recordings from LiveKit [Agent Observability](https://docs.livekit.io/testing/observability/). +- [Simulations](https://docs.livekit.io/testing/simulations/) that test full conversations with your agent, run in CI on every merge to `main`. - A `Dockerfile` for [deploying to LiveKit Cloud](https://docs.livekit.io/deploy/agents/). The starter works with any [custom web or mobile frontend](https://docs.livekit.io/frontends/) or with [telephony](https://docs.livekit.io/telephony/). @@ -33,7 +34,7 @@ LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/ lk docs search "testing my agent" ``` -See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup. +The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing. See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill. ## Dev setup @@ -80,7 +81,7 @@ The `lk agent console` and `lk agent dev` commands run your agent on your own ma lk agent console ``` -To connect it to LiveKit Cloud so a frontend or phone call can reach it: +To connect it to LiveKit Cloud so a frontend, a phone call, or the [Agent Console](https://docs.livekit.io/testing/agent-console/) can reach it: ```console lk agent dev @@ -108,7 +109,7 @@ Pair the agent with a prebuilt frontend starter, or add telephony: For more options, see the [frontend guide](https://docs.livekit.io/frontends/). -## Tests and evals +## Testing and debugging Simulations run full multi-turn conversations between a simulated user and your agent on LiveKit Cloud, then judge each transcript. The scenarios live in [`scenarios.yaml`](scenarios.yaml). Run them locally with the CLI: @@ -116,9 +117,11 @@ Simulations run full multi-turn conversations between a simulated user and your lk agent simulate --scenarios scenarios.yaml ``` -The `Simulations` workflow in [`.github/workflows/simulations.yml`](.github/workflows/simulations.yml) runs the same file on every merge to `main`, and on demand from the Actions tab. It doesn't run on every pull request push because each run uses real inference. See the [simulations guide](https://docs.livekit.io/agents/start/testing/simulations/) for how to write scenarios and read results. +The `Simulations` workflow in [`.github/workflows/simulations.yml`](.github/workflows/simulations.yml) runs the same file on every merge to `main`, and on demand from the Actions tab. It doesn't run on every pull request push because each run uses real inference. See the [simulations guide](https://docs.livekit.io/testing/simulations/) for how to write scenarios and read results. -For turn-level checks that don't need a live session, the LiveKit Agents [testing and evaluation framework](https://docs.livekit.io/agents/start/testing/) runs your agent in-process under `pytest`. [`tests/test_agent.py`](tests/test_agent.py) has a commented-out example. +For turn-level checks that don't need a live session, the LiveKit Agents [unit testing framework](https://docs.livekit.io/testing/unit-tests/) runs your agent in-process under `pytest`. [`tests/test_agent.py`](tests/test_agent.py) has a commented-out example. + +To debug a running agent, open it in the [Agent Console](https://docs.livekit.io/testing/agent-console/). It shows events, tool calls, and model timing as you talk to the agent. To stream logs from a deployed agent, run `lk agent logs`. ## Using this template for your own project From 0edc5b84f1d77329a65ceb8f17c74105fe8db302 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 20:30:40 +0000 Subject: [PATCH 05/11] Restore the get-page example alongside search Search returns short excerpts, so reading a result means fetching the full page. Show both commands in the README, and tell coding agents in AGENTS.md to fetch the page before acting on a search result. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv --- AGENTS.md | 2 +- README.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 55fe584..bc4b132 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ Install or update the CLI: - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` - **Windows:** `winget install LiveKit.LiveKitCLI` (update: `winget upgrade LiveKit.LiveKitCLI`) -Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, and `lk docs submit-feedback`. Run `lk docs --help` before using a command for the first time, because the help text explains how to use it and how to interpret results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, because docs pages are more current and give better context than raw code. +Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, and `lk docs submit-feedback`. Run `lk docs --help` before using a command for the first time, because the help text explains how to use it and how to interpret results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, because docs pages are more current and give better context than raw code. Search results are short excerpts, so fetch the full page with `lk docs get-page` before you act on one. ### LiveKit docs MCP server diff --git a/README.md b/README.md index c0e6f3a..7b52f96 100644 --- a/README.md +++ b/README.md @@ -28,10 +28,11 @@ The starter works with any [custom web or mobile frontend](https://docs.livekit. This project works with coding agents like [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), and [Codex](https://openai.com/codex/). -LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) for browsing and searching its documentation. For example: +LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) for browsing and searching its documentation. Search returns short excerpts, so fetch the full page to read the details: ```console lk docs search "testing my agent" +lk docs get-page /testing/unit-tests ``` The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing. See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill. From d838d34daeaa7d727125879b372dca355b8388a6 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 16:51:55 +0000 Subject: [PATCH 06/11] Add the agent debugger to the README and AGENTS.md `lk agent debugger` shipped in CLI 2.18.8: it runs the agent in text mode and lets a coding agent or script drive one turn at a time, printing the tool calls and handoffs behind each reply. README lists it under "Run the agent" and raises the CLI floor to 2.18.8. AGENTS.md adapts the snippet from the coding agents guide so the agent tries every change with the debugger, and the debugging checklist now starts from reproducing the problem there. Agent Console stays the answer for speech issues the text-only debugger cannot show. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv --- AGENTS.md | 11 +++++++---- README.md | 14 +++++++++++--- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bc4b132..1c259ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,15 +48,18 @@ For turn-level checks that don't need a live session, use the in-process [unit t Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Use test-driven development (TDD) and start by writing tests for the desired behavior. For example, if you're adding a tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass. This is how you produce a working, reliable agent. +After changing the agent, try it with the [agent debugger](https://docs.livekit.io/testing/debugger/) (CLI 2.18.8 or later) before calling the change done. Start the agent with `lk agent debugger start`, send user turns with `lk agent debugger say "..."`, and read the tool calls in each turn as well as the reply. Run `lk agent debugger restart` after every code edit, since a running session keeps the old code, and `lk agent debugger stop` when you're done. + ## Debugging To investigate unexpected agent behavior: -- Reproduce it in a unit test or simulation scenario first, so you have a repeatable case to iterate against. -- Run `lk agent dev --log-level DEBUG` for verbose logs from a local agent. +- Reproduce it with `lk agent debugger`: send the turns that trigger the problem and read the tool calls and errors in each one. Add `--logs` to `say` to see log lines, including tracebacks, next to the turn that produced them. +- Add a unit test or simulation scenario once it's fixed, so a later change can't bring it back unnoticed. +- Run `lk agent dev --log-level DEBUG` for verbose logs from a local agent connected to LiveKit Cloud. - Run `lk agent logs` to stream logs from a deployed agent. -- Ask the developer to open the [Agent Console](https://docs.livekit.io/testing/agent-console/), which shows events, tool calls, and model timing for a live session. -- For sessions with real users, check [Agent Observability](https://docs.livekit.io/testing/observability/) for transcripts, traces, logs, and recordings. +- Ask the developer to open the [Agent Console](https://docs.livekit.io/testing/agent-console/) for speech problems such as turn-taking, interruptions, or transcription, which the text-only debugger can't show. It shows events, tool calls, and model timing for a live session. +- Check [Agent Observability](https://docs.livekit.io/testing/observability/) for transcripts, traces, logs, and recordings of sessions with real users. ## Other CLI commands diff --git a/README.md b/README.md index bf6e057..44a291f 100644 --- a/README.md +++ b/README.md @@ -36,11 +36,11 @@ lk docs search "testing my agent" lk docs get-page /testing/unit-tests ``` -The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing. See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill. +The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing, and tries its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill. ## Dev setup -Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.15.0 or later: +Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.18.8 or later: - **macOS:** `brew install livekit-cli` - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` @@ -77,7 +77,7 @@ lk app env --write --destination .env.local ## Run the agent -The `lk agent console` and `lk agent dev` commands run your agent on your own machine. To talk to it in your terminal: +The `lk agent console`, `lk agent dev`, and `lk agent debugger` commands run your agent on your own machine. To talk to it in your terminal: ```console lk agent console @@ -89,6 +89,14 @@ To connect it to LiveKit Cloud so a frontend, a phone call, or the [Agent Consol lk agent dev ``` +To let a coding agent or a script test it one text turn at a time, use the [agent debugger](https://docs.livekit.io/testing/debugger/). Each turn prints the agent's reply along with the tool calls and handoffs behind it: + +```console +lk agent debugger start +lk agent debugger say "Hi, what can you do?" +lk agent debugger stop +``` + In production, run the agent directly: ```console From 848a75b48ded834015d2ee4b4ec58bcdf5aa138d Mon Sep 17 00:00:00 2001 From: Ben Cherry Date: Thu, 24 Sep 2026 14:42:38 -0700 Subject: [PATCH 07/11] Update AGENTS.md Co-authored-by: u9g --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 1c259ac..3b06244 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ Be sure to maintain code formatting, using `uv run ruff format` and `uv run ruff ## LiveKit documentation -LiveKit Agents changes quickly, and its documentation is updated often. Always refer to the latest documentation when working with this project. LiveKit offers both a CLI and an MCP server for browsing and searching its documentation. If the developer hasn't installed the CLI yet, recommend that they install it. +Always refer to the latest documentation when working with this project. LiveKit offers both a CLI (`lk docs`) and an MCP server for browsing and searching its documentation. ### LiveKit CLI From ddef639444ec2feed7372760149f70c90cc6cb42 Mon Sep 17 00:00:00 2001 From: Ben Cherry Date: Thu, 24 Sep 2026 14:43:01 -0700 Subject: [PATCH 08/11] Update AGENTS.md Co-authored-by: u9g --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 3b06244..d2c9415 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ Install or update the CLI: - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` - **Windows:** `winget install LiveKit.LiveKitCLI` (update: `winget upgrade LiveKit.LiveKitCLI`) -Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, and `lk docs submit-feedback`. Run `lk docs --help` before using a command for the first time, because the help text explains how to use it and how to interpret results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, because docs pages are more current and give better context than raw code. Search results are short excerpts, so fetch the full page with `lk docs get-page` before you act on one. +Run `lk docs` for the first time, because the help text explains how to use it and how to interpret results. ### LiveKit docs MCP server From 5b5c016f5bcfe07355be8efae69affca0cfb4c0b Mon Sep 17 00:00:00 2001 From: Ben Cherry Date: Thu, 24 Sep 2026 14:43:58 -0700 Subject: [PATCH 09/11] Update AGENTS.md Co-authored-by: u9g --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d2c9415..92379db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,7 +42,7 @@ Voice AI agents are highly sensitive to latency. Design complex agents in a stru ## Testing -When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/testing/simulations/) before editing them. +To ensure agent behavior does not regress, add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. Then ensure that the scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/testing/simulations/) before editing them. For turn-level checks that don't need a live session, use the in-process [unit testing framework](https://docs.livekit.io/testing/unit-tests/). `tests/test_agent.py` has a commented-out example. Run those tests with `uv run pytest`. From 3d1935fdb3aaa1191f7d38ded3d8d1db539c6317 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 21:47:18 +0000 Subject: [PATCH 10/11] Apply Jason's AGENTS.md review round, and point testing at the debugger - Say the starter, not the SDK, is designed to run in LiveKit Cloud. - Drop the lk docs intro, the command list, and the MCP transport details; running lk docs shows the help. - Widen docs feedback to any LiveKit problem, keeping the to-do-list timing that has worked well. - Stop advertising the unit testing framework. Scenarios are the tests, and the debugger is the loop for checking each change; the README testing section points there too. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv --- AGENTS.md | 20 ++++++++------------ README.md | 2 +- 2 files changed, 9 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 92379db..0fb2ab2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This is a LiveKit Agents project. LiveKit Agents is a Python SDK for building voice AI agents, and this project is designed for LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem. +This is a LiveKit Agents project. LiveKit Agents is a Python SDK for building voice AI agents. This starter is designed to run in LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem. ## Tooling @@ -14,23 +14,21 @@ Always refer to the latest documentation when working with this project. LiveKit ### LiveKit CLI -The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) `lk docs` subcommand gives full access to LiveKit documentation from the terminal. It requires CLI version 2.15.0 or later. Check with `lk --version`. - Install or update the CLI: - **macOS:** `brew install livekit-cli` (update: `brew update && brew upgrade livekit-cli`) - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` - **Windows:** `winget install LiveKit.LiveKitCLI` (update: `winget upgrade LiveKit.LiveKitCLI`) -Run `lk docs` for the first time, because the help text explains how to use it and how to interpret results. +Run `lk docs` before your first docs lookup. Its help text explains how to use each command and how to interpret results. ### LiveKit docs MCP server -For deeper IDE integration, LiveKit also offers an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) with the same documentation access. It uses Streamable HTTP transport at `https://docs.livekit.io/mcp`. See your IDE's documentation for how to add it. +For deeper coding agent integration, LiveKit also offers an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/). -### Submit docs feedback to LiveKit +### Submit feedback to LiveKit -If you use the LiveKit CLI or MCP server to search or browse documentation, also submit constructive feedback to LiveKit with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool. Add this to your to-do list when planning work, so you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, or any other gap or issue in the docs. +When you run into any problem with LiveKit, add it to your to-do list, then submit it with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool once you finish your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, broken features or implementations, and any other gap or issue in the LiveKit ecosystem. ## LiveKit Agents skill @@ -42,11 +40,9 @@ Voice AI agents are highly sensitive to latency. Design complex agents in a stru ## Testing -To ensure agent behavior does not regress, add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. Then ensure that the scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/testing/simulations/) before editing them. - -For turn-level checks that don't need a live session, use the in-process [unit testing framework](https://docs.livekit.io/testing/unit-tests/). `tests/test_agent.py` has a commented-out example. Run those tests with `uv run pytest`. +To keep agent behavior from regressing, add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. Make sure the scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/testing/simulations/) before editing them. -Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Use test-driven development (TDD) and start by writing tests for the desired behavior. For example, if you're adding a tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass. This is how you produce a working, reliable agent. +Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Start by writing a scenario for the desired behavior. For example, if you're adding a tool, write a scenario that exercises it, then iterate on the tool until the scenario passes. This is how you produce a working, reliable agent. After changing the agent, try it with the [agent debugger](https://docs.livekit.io/testing/debugger/) (CLI 2.18.8 or later) before calling the change done. Start the agent with `lk agent debugger start`, send user turns with `lk agent debugger say "..."`, and read the tool calls in each turn as well as the reply. Run `lk agent debugger restart` after every code edit, since a running session keeps the old code, and `lk agent debugger stop` when you're done. @@ -55,7 +51,7 @@ After changing the agent, try it with the [agent debugger](https://docs.livekit. To investigate unexpected agent behavior: - Reproduce it with `lk agent debugger`: send the turns that trigger the problem and read the tool calls and errors in each one. Add `--logs` to `say` to see log lines, including tracebacks, next to the turn that produced them. -- Add a unit test or simulation scenario once it's fixed, so a later change can't bring it back unnoticed. +- Add a simulation scenario once it's fixed, so a later change can't bring it back unnoticed. - Run `lk agent dev --log-level DEBUG` for verbose logs from a local agent connected to LiveKit Cloud. - Run `lk agent logs` to stream logs from a deployed agent. - Ask the developer to open the [Agent Console](https://docs.livekit.io/testing/agent-console/) for speech problems such as turn-taking, interruptions, or transcription, which the text-only debugger can't show. It shows events, tool calls, and model timing for a live session. diff --git a/README.md b/README.md index 44a291f..89d8b7d 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ lk agent simulate --scenarios scenarios.yaml The `Simulations` workflow in [`.github/workflows/simulations.yml`](.github/workflows/simulations.yml) runs the same file on every merge to `main`, and on demand from the Actions tab. It doesn't run on every pull request push because each run uses real inference. See the [simulations guide](https://docs.livekit.io/testing/simulations/) for how to write scenarios and read results. -For turn-level checks that don't need a live session, the LiveKit Agents [unit testing framework](https://docs.livekit.io/testing/unit-tests/) runs your agent in-process under `pytest`. [`tests/test_agent.py`](tests/test_agent.py) has a commented-out example. +To check a change turn by turn without a live session, use the [agent debugger](https://docs.livekit.io/testing/debugger/) shown in [Run the agent](#run-the-agent). To debug a running agent, open it in the [Agent Console](https://docs.livekit.io/testing/agent-console/). It shows events, tool calls, and model timing as you talk to the agent. To stream logs from a deployed agent, run `lk agent logs`. From 7020b05d68dd23189357d19d6fb89c54f873bb94 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 25 Sep 2026 02:55:31 +0000 Subject: [PATCH 11/11] Describe the seven bundled agent skills, not livekit-agents The skills PR replaces the single livekit-agents skill with seven focused ones, so the fallback path to its SKILL.md would no longer exist. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv --- AGENTS.md | 4 ++-- README.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0fb2ab2..0ce1e99 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,9 +30,9 @@ For deeper coding agent integration, LiveKit also offers an [MCP server](https:/ When you run into any problem with LiveKit, add it to your to-do list, then submit it with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool once you finish your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, broken features or implementations, and any other gap or issue in the LiveKit ecosystem. -## LiveKit Agents skill +## LiveKit agent skills -This project includes the `livekit-agents` skill in `.claude/skills/` and `.agents/skills/`. It covers how to approach agent architecture, workflows, handoffs, tasks, and testing, and it defers to the live documentation for API details. If your tool doesn't load skills automatically, read `.agents/skills/livekit-agents/SKILL.md` before you design or restructure an agent. +This project includes LiveKit's agent skills in `.claude/skills/` and `.agents/skills/`, one for each stage of the work: reading the docs, building, debugging, testing, writing scenarios, running simulations, and operating in production. They defer to the live documentation for API details. If your tool doesn't load skills automatically, read the matching `.agents/skills//SKILL.md` before you start that kind of task. ## Handoffs and tasks ("workflows") diff --git a/README.md b/README.md index 89d8b7d..8de549c 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ lk docs search "testing my agent" lk docs get-page /testing/unit-tests ``` -The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing, and tries its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill. +The project also includes an [`AGENTS.md`](AGENTS.md) file and LiveKit's [agent skills](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing, and tries its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill. ## Dev setup