From 2cd066bee98acaa7e1845d42e166910fda0b463d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 21:30:47 +0000 Subject: [PATCH 01/13] Recommend lk agent init and explain how to get the agent skills The skills are no longer bundled, so a project created with GitHub's "Use this template" button or git clone has none. Make lk agent init the recommended way to create a project, add lk skills install to the manual setup, lead the coding agents section with the skills, and tell coding agents to recommend lk skills install when the skills are missing. Raise the stated CLI minimum to 2.19.0, which lk skills and the debugger need. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- AGENTS.md | 6 ++++-- README.md | 34 ++++++++++++++++++++++++---------- 2 files changed, 28 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2c2e754..7189f3e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,9 @@ When you run into any problem with LiveKit, add it to your to-do list, then subm ## LiveKit agent skills -LiveKit publishes agent skills 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. The developer installs them with `lk skills install`, which also adds the LiveKit Docs MCP server to your config. If they aren't installed (there's no `.agents/skills/` or `.claude/skills/` directory), recommend that the developer install them. If your tool doesn't load skills automatically, read the matching `.agents/skills//SKILL.md` before you start that kind of task. +LiveKit publishes agent skills 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. + +The skills aren't bundled with this project. `lk agent init` installs them when it creates a project, and `lk skills install` (LiveKit CLI 2.19.0 or later) installs them into an existing one, along with the LiveKit Docs MCP server. If the LiveKit skills, such as `building-livekit-agents`, aren't available to you, recommend that the developer run `lk skills install` in the project directory. This is common when the project was created with GitHub's "Use this template" button or `git clone`. If your tool doesn't load skills automatically, read the matching `SKILL.md` in `.agents/skills//` or `.claude/skills//` before you start that kind of task. ## Handoffs and tasks ("workflows") @@ -44,7 +46,7 @@ To keep agent behavior from regressing, add a scenario to `scenarios.yaml` and r 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. +After changing the agent, try it with the [agent debugger](https://docs.livekit.io/testing/debugger/) (CLI 2.19.0 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 diff --git a/README.md b/README.md index f2bfb06..ccf3e64 100644 --- a/README.md +++ b/README.md @@ -27,28 +27,30 @@ The starter works with any [custom web or mobile frontend](https://docs.livekit. ## Using coding agents -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/). +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 gives them three things to work with. -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: +**Agent skills.** LiveKit's [agent skills](https://docs.livekit.io/reference/developer-tools/agent-skills/) guide your coding agent through each stage of the work, from building and debugging to testing and deploying. The skills aren't included in this repository. `lk agent init` installs them when it creates your project (see [Dev setup](#dev-setup)). If you created your project another way, such as with GitHub's **Use this template** button or `git clone`, install them from the project directory: ```console -lk docs search "testing my agent" -lk docs get-page /testing/unit-tests +lk skills install ``` -The project also includes an [`AGENTS.md`](AGENTS.md) file, 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/). +The CLI installs the skills for the coding agents it finds on your machine and adds the LiveKit Docs MCP server to their config. Run `lk skills update` to get the latest skills. + +**`AGENTS.md`.** The project includes an [`AGENTS.md`](AGENTS.md) file, 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/). -For more guidance at each stage of the work, from building and debugging to testing and deploying, install LiveKit's [agent skills](https://docs.livekit.io/intro/coding-agents/#agent-skills). The CLI installs them for the coding agents on your machine and adds the Docs MCP server to their config. `lk agent init` offers to do this when it creates your project, or you can run it yourself: +**Docs access.** 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 skills install +lk docs search "testing my agent" +lk docs get-page /testing/unit-tests ``` -Run `lk skills update` to get the latest skills, and commit `skills-lock.json` along with them. See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details. +See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details. ## Dev setup -Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.18.8 or later: +Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.19.0 or later: - **macOS:** `brew install livekit-cli` - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` @@ -56,13 +58,16 @@ Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2. 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). -Then create a project from this template. The CLI clones the template and configures your environment: +Then create your project with `lk agent init`. The CLI clones this template, writes your LiveKit Cloud credentials to `.env.local`, and offers to install dependencies and LiveKit's [agent skills](#using-coding-agents) for your coding agents: ```console lk cloud auth lk agent init my-agent --template agent-starter-python ``` +> [!TIP] +> Use `lk agent init` instead of GitHub's **Use this template** button. A repository created on GitHub doesn't include the agent skills or your credentials, so you'd need to set them up yourself as described in the following section. +
Set up the project manually @@ -74,6 +79,8 @@ cd agent-starter-python uv sync ``` +If you created your own repository from this template on GitHub, clone that repository instead. + 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: ```console @@ -81,6 +88,12 @@ lk cloud auth lk app env --write --destination .env.local ``` +Then install LiveKit's agent skills for your coding agents: + +```console +lk skills install +``` +
## Run the agent @@ -146,6 +159,7 @@ To debug a running agent, open it in the [Agent Console](https://docs.livekit.io After you create your own project from this template: - **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. +- **Commit the agent skills.** If you installed the [agent skills](#using-coding-agents) into the project, commit the skill directories and `skills-lock.json` so everyone working on the project gets the same skills. If they aren't installed yet, run `lk skills install`. - **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 From 3b1e0342190247535ce8bbd543f4b040c5196d53 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 21:46:19 +0000 Subject: [PATCH 02/13] Show the full lk agent init command for each starter Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- AGENTS.md | 2 +- README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7189f3e..4a8bc39 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,7 +34,7 @@ When you run into any problem with LiveKit, add it to your to-do list, then subm LiveKit publishes agent skills 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. -The skills aren't bundled with this project. `lk agent init` installs them when it creates a project, and `lk skills install` (LiveKit CLI 2.19.0 or later) installs them into an existing one, along with the LiveKit Docs MCP server. If the LiveKit skills, such as `building-livekit-agents`, aren't available to you, recommend that the developer run `lk skills install` in the project directory. This is common when the project was created with GitHub's "Use this template" button or `git clone`. If your tool doesn't load skills automatically, read the matching `SKILL.md` in `.agents/skills//` or `.claude/skills//` before you start that kind of task. +The skills aren't bundled with this project. `lk agent init my-agent --template agent-starter-python` installs them when it creates a project from this starter, and `lk skills install` (LiveKit CLI 2.19.0 or later) installs them into an existing one, along with the LiveKit Docs MCP server. If the LiveKit skills, such as `building-livekit-agents`, aren't available to you, recommend that the developer run `lk skills install` in the project directory. This is common when the project was created with GitHub's "Use this template" button or `git clone`. If your tool doesn't load skills automatically, read the matching `SKILL.md` in `.agents/skills//` or `.claude/skills//` before you start that kind of task. ## Handoffs and tasks ("workflows") diff --git a/README.md b/README.md index ccf3e64..2801a1e 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ 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 gives them three things to work with. -**Agent skills.** LiveKit's [agent skills](https://docs.livekit.io/reference/developer-tools/agent-skills/) guide your coding agent through each stage of the work, from building and debugging to testing and deploying. The skills aren't included in this repository. `lk agent init` installs them when it creates your project (see [Dev setup](#dev-setup)). If you created your project another way, such as with GitHub's **Use this template** button or `git clone`, install them from the project directory: +**Agent skills.** LiveKit's [agent skills](https://docs.livekit.io/reference/developer-tools/agent-skills/) guide your coding agent through each stage of the work, from building and debugging to testing and deploying. The skills aren't included in this repository. Create your project with `lk agent init my-agent --template agent-starter-python` and the CLI installs them for you (see [Dev setup](#dev-setup)). If you created your project another way, such as with GitHub's **Use this template** button or `git clone`, install them from the project directory: ```console lk skills install @@ -66,7 +66,7 @@ lk agent init my-agent --template agent-starter-python ``` > [!TIP] -> Use `lk agent init` instead of GitHub's **Use this template** button. A repository created on GitHub doesn't include the agent skills or your credentials, so you'd need to set them up yourself as described in the following section. +> Use `lk agent init my-agent --template agent-starter-python` instead of GitHub's **Use this template** button. A repository created on GitHub doesn't include the agent skills or your credentials, so you'd need to set them up yourself as described in the following section.
Set up the project manually From 52d25fb30052348c0996dbdef7b8dadb498a6a58 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 21:50:07 +0000 Subject: [PATCH 03/13] Tighten the skills and lk agent init wording Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- AGENTS.md | 2 +- README.md | 24 +++++++++++++----------- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4a8bc39..fe6b079 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,7 +34,7 @@ When you run into any problem with LiveKit, add it to your to-do list, then subm LiveKit publishes agent skills 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. -The skills aren't bundled with this project. `lk agent init my-agent --template agent-starter-python` installs them when it creates a project from this starter, and `lk skills install` (LiveKit CLI 2.19.0 or later) installs them into an existing one, along with the LiveKit Docs MCP server. If the LiveKit skills, such as `building-livekit-agents`, aren't available to you, recommend that the developer run `lk skills install` in the project directory. This is common when the project was created with GitHub's "Use this template" button or `git clone`. If your tool doesn't load skills automatically, read the matching `SKILL.md` in `.agents/skills//` or `.claude/skills//` before you start that kind of task. +The skills aren't bundled with this project. If they aren't available to you, ask the developer to run `lk skills install` (LiveKit CLI 2.19.0 or later), which also adds the LiveKit Docs MCP server. 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 2801a1e..7079517 100644 --- a/README.md +++ b/README.md @@ -27,26 +27,26 @@ The starter works with any [custom web or mobile frontend](https://docs.livekit. ## Using coding agents -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 gives them three things to work with. +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/). -**Agent skills.** LiveKit's [agent skills](https://docs.livekit.io/reference/developer-tools/agent-skills/) guide your coding agent through each stage of the work, from building and debugging to testing and deploying. The skills aren't included in this repository. Create your project with `lk agent init my-agent --template agent-starter-python` and the CLI installs them for you (see [Dev setup](#dev-setup)). If you created your project another way, such as with GitHub's **Use this template** button or `git clone`, install them from the project directory: +**Agent skills.** LiveKit's [agent skills](https://docs.livekit.io/reference/developer-tools/agent-skills/) guide your coding agent through building, debugging, testing, and deploying. `lk agent init` installs them (see [Dev setup](#dev-setup)). If you created the project another way, run this in the project directory: ```console lk skills install ``` -The CLI installs the skills for the coding agents it finds on your machine and adds the LiveKit Docs MCP server to their config. Run `lk skills update` to get the latest skills. +To get the latest skills, run `lk skills update`. -**`AGENTS.md`.** The project includes an [`AGENTS.md`](AGENTS.md) file, 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/). +**`AGENTS.md`.** Teaches your coding agent LiveKit's best practices for workflows, handoffs, and testing, and has it check its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). -**Docs access.** 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: +**Docs.** Search and read the LiveKit docs with the CLI or the [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/): ```console lk docs search "testing my agent" lk docs get-page /testing/unit-tests ``` -See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details. +For more, see the [coding agents guide](https://docs.livekit.io/intro/coding-agents/). ## Dev setup @@ -58,15 +58,17 @@ Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2. 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). -Then create your project with `lk agent init`. The CLI clones this template, writes your LiveKit Cloud credentials to `.env.local`, and offers to install dependencies and LiveKit's [agent skills](#using-coding-agents) for your coding agents: +Then create your project: ```console lk cloud auth lk agent init my-agent --template agent-starter-python ``` +The CLI clones this starter, writes your credentials to `.env.local`, and installs dependencies and agent skills. + > [!TIP] -> Use `lk agent init my-agent --template agent-starter-python` instead of GitHub's **Use this template** button. A repository created on GitHub doesn't include the agent skills or your credentials, so you'd need to set them up yourself as described in the following section. +> Use this command instead of GitHub's **Use this template** button, which skips the skills and credentials.
Set up the project manually @@ -79,7 +81,7 @@ cd agent-starter-python uv sync ``` -If you created your own repository from this template on GitHub, clone that repository instead. +If you used **Use this template**, clone your own repository instead. 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: @@ -88,7 +90,7 @@ lk cloud auth lk app env --write --destination .env.local ``` -Then install LiveKit's agent skills for your coding agents: +Then install the agent skills: ```console lk skills install @@ -159,7 +161,7 @@ To debug a running agent, open it in the [Agent Console](https://docs.livekit.io After you create your own project from this template: - **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. -- **Commit the agent skills.** If you installed the [agent skills](#using-coding-agents) into the project, commit the skill directories and `skills-lock.json` so everyone working on the project gets the same skills. If they aren't installed yet, run `lk skills install`. +- **Commit the agent skills** and `skills-lock.json`, if you installed them in the project. - **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 From f552bab77a3223e7f0d95e43f55c01a47f64c390 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 22:29:04 +0000 Subject: [PATCH 04/13] Make the AGENTS.md skills instructions direct Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fe6b079..4c288c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,9 +32,9 @@ When you run into any problem with LiveKit, add it to your to-do list, then subm ## LiveKit agent skills -LiveKit publishes agent skills 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. +LiveKit's agent skills cover each stage of the work: reading the docs, building, debugging, testing, writing scenarios, running simulations, and operating in production. Use them. -The skills aren't bundled with this project. If they aren't available to you, ask the developer to run `lk skills install` (LiveKit CLI 2.19.0 or later), which also adds the LiveKit Docs MCP server. If your tool doesn't load skills automatically, read the matching `.agents/skills//SKILL.md` before you start that kind of task. +If they aren't installed, install them with `lk skills install --yes` (LiveKit CLI 2.19.0 or later). This also adds the LiveKit Docs MCP server. New skills load in your next session, so until then, read the matching `.agents/skills//SKILL.md` before you start that kind of task. ## Handoffs and tasks ("workflows") From 8f34a1de03ef93c672720e04dce8a46638778f22 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 22:33:14 +0000 Subject: [PATCH 05/13] Ask before installing the agent skills Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4c288c4..920d617 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,7 +34,7 @@ When you run into any problem with LiveKit, add it to your to-do list, then subm LiveKit's agent skills cover each stage of the work: reading the docs, building, debugging, testing, writing scenarios, running simulations, and operating in production. Use them. -If they aren't installed, install them with `lk skills install --yes` (LiveKit CLI 2.19.0 or later). This also adds the LiveKit Docs MCP server. New skills load in your next session, so until then, read the matching `.agents/skills//SKILL.md` before you start that kind of task. +If they aren't installed, ask the developer for permission, then install them with `lk skills install --yes` (LiveKit CLI 2.19.0 or later). This also adds the LiveKit Docs MCP server. New skills load in your next session, so until then, read the matching `.agents/skills//SKILL.md` before you start that kind of task. ## Handoffs and tasks ("workflows") From f63afa4628d8cac96906b9e95bb20ce9241ed58d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 23:06:09 +0000 Subject: [PATCH 06/13] Lead the README with getting started, then coding agents Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- README.md | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 7079517..96a53cf 100644 --- a/README.md +++ b/README.md @@ -25,30 +25,7 @@ The starter includes: 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 works with coding agents like [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), and [Codex](https://openai.com/codex/). - -**Agent skills.** LiveKit's [agent skills](https://docs.livekit.io/reference/developer-tools/agent-skills/) guide your coding agent through building, debugging, testing, and deploying. `lk agent init` installs them (see [Dev setup](#dev-setup)). If you created the project another way, run this in the project directory: - -```console -lk skills install -``` - -To get the latest skills, run `lk skills update`. - -**`AGENTS.md`.** Teaches your coding agent LiveKit's best practices for workflows, handoffs, and testing, and has it check its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). - -**Docs.** Search and read the LiveKit docs with the CLI or the [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/): - -```console -lk docs search "testing my agent" -lk docs get-page /testing/unit-tests -``` - -For more, see the [coding agents guide](https://docs.livekit.io/intro/coding-agents/). - -## Dev setup +## Getting started Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.19.0 or later: @@ -65,7 +42,7 @@ lk cloud auth lk agent init my-agent --template agent-starter-python ``` -The CLI clones this starter, writes your credentials to `.env.local`, and installs dependencies and agent skills. +The CLI clones this starter, writes your credentials to `.env.local`, and installs dependencies and [agent skills](#using-coding-agents) for your coding agents. > [!TIP] > Use this command instead of GitHub's **Use this template** button, which skips the skills and credentials. @@ -98,6 +75,29 @@ lk skills install
+## Using coding agents + +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/). + +**Agent skills.** Install LiveKit's [agent skills](https://docs.livekit.io/reference/developer-tools/agent-skills/), which teach your coding agent to build, debug, test, and deploy LiveKit agents: + +```console +lk skills install +``` + +To get the latest skills, run `lk skills update`. + +**`AGENTS.md`.** Teaches your coding agent LiveKit's best practices for workflows, handoffs, and testing, and has it check its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). + +**Docs.** Search and read the LiveKit docs with the CLI or the [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/): + +```console +lk docs search "testing my agent" +lk docs get-page /testing/unit-tests +``` + +For more, see the [coding agents guide](https://docs.livekit.io/intro/coding-agents/). + ## Run the agent 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: From 80ad8fb5968d81b41a238ee01be1a88590b3dcdb Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 23:09:03 +0000 Subject: [PATCH 07/13] Lead the README with getting started and drop manual setup Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- README.md | 72 ++++++++++++++++++------------------------------------- 1 file changed, 23 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 96a53cf..0938092 100644 --- a/README.md +++ b/README.md @@ -6,74 +6,48 @@ 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 includes: - -- 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](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/) such as OpenAI GPT-Live. Many other models 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. -- [Keyterms](https://docs.livekit.io/agents/models/stt/keyterms/), on by default, so speech recognition gets your names, brands, and jargon right, including names it picks up during the conversation, like a caller's. -- [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 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/). - ## Getting started -Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.19.0 or later: +Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/): - **macOS:** `brew install livekit-cli` - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` - **Windows:** `winget install LiveKit.LiveKitCLI` -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). - -Then create your project: +Create your project and talk to your agent: ```console lk cloud auth lk agent init my-agent --template agent-starter-python +cd my-agent +lk agent console ``` -The CLI clones this starter, writes your credentials to `.env.local`, and installs dependencies and [agent skills](#using-coding-agents) for your coding agents. +`lk agent init` creates your project from this starter, writes your LiveKit Cloud credentials to `.env.local`, and installs dependencies and [agent skills](#using-coding-agents) for your coding agents. > [!TIP] -> Use this command instead of GitHub's **Use this template** button, which skips the skills and credentials. - -
-Set up the project manually - -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 -``` - -If you used **Use this template**, clone your own repository instead. +> Use `lk agent init` instead of GitHub's **Use this template** button, which skips the skills and credentials. -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: +## What's included -```console -lk cloud auth -lk app env --write --destination .env.local -``` - -Then install the agent skills: +The starter includes: -```console -lk skills install -``` +- 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](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/) such as OpenAI GPT-Live. Many other models 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. +- [Keyterms](https://docs.livekit.io/agents/models/stt/keyterms/), on by default, so speech recognition gets your names, brands, and jargon right, including names it picks up during the conversation, like a caller's. +- [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 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/). ## Using coding agents From 70a1f4670fdd365d35b596ff9460c0a4444d6e6b Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 23:22:01 +0000 Subject: [PATCH 08/13] Drop the Use this template tip Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 0938092..a486df4 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,6 @@ lk agent console `lk agent init` creates your project from this starter, writes your LiveKit Cloud credentials to `.env.local`, and installs dependencies and [agent skills](#using-coding-agents) for your coding agents. -> [!TIP] -> Use `lk agent init` instead of GitHub's **Use this template** button, which skips the skills and credentials. - ## What's included The starter includes: From df4cb0980fdfe01f8c6abadf8b48c53a3c0c37d8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 23:22:31 +0000 Subject: [PATCH 09/13] Drop docs search from the README Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- README.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/README.md b/README.md index a486df4..1e29ae1 100644 --- a/README.md +++ b/README.md @@ -60,13 +60,6 @@ To get the latest skills, run `lk skills update`. **`AGENTS.md`.** Teaches your coding agent LiveKit's best practices for workflows, handoffs, and testing, and has it check its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). -**Docs.** Search and read the LiveKit docs with the CLI or the [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/): - -```console -lk docs search "testing my agent" -lk docs get-page /testing/unit-tests -``` - For more, see the [coding agents guide](https://docs.livekit.io/intro/coding-agents/). ## Run the agent From 65bbababe681d43a59b9661905171e817330974d Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 23:24:01 +0000 Subject: [PATCH 10/13] Number the getting started steps and move coding agents down Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- README.md | 59 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 1e29ae1..4097e08 100644 --- a/README.md +++ b/README.md @@ -8,22 +8,25 @@ A starter project for building voice AI apps with [LiveKit Agents for Python](ht ## Getting started -Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/): +1. Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/): -- **macOS:** `brew install livekit-cli` -- **Linux:** `curl -sSL https://get.livekit.io/cli | bash` -- **Windows:** `winget install LiveKit.LiveKitCLI` + - **macOS:** `brew install livekit-cli` + - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` + - **Windows:** `winget install LiveKit.LiveKitCLI` -Create your project and talk to your agent: +1. Create your project from this starter. The CLI writes your LiveKit Cloud credentials to `.env.local` and installs dependencies and [agent skills](#using-coding-agents) for your coding agents: -```console -lk cloud auth -lk agent init my-agent --template agent-starter-python -cd my-agent -lk agent console -``` + ```console + lk cloud auth + lk agent init my-agent --template agent-starter-python + ``` -`lk agent init` creates your project from this starter, writes your LiveKit Cloud credentials to `.env.local`, and installs dependencies and [agent skills](#using-coding-agents) for your coding agents. +1. Talk to your agent. Run it in your terminal and speak into your microphone: + + ```console + cd my-agent + lk agent console + ``` ## What's included @@ -46,22 +49,6 @@ The starter includes: 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 works with coding agents like [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), and [Codex](https://openai.com/codex/). - -**Agent skills.** Install LiveKit's [agent skills](https://docs.livekit.io/reference/developer-tools/agent-skills/), which teach your coding agent to build, debug, test, and deploy LiveKit agents: - -```console -lk skills install -``` - -To get the latest skills, run `lk skills update`. - -**`AGENTS.md`.** Teaches your coding agent LiveKit's best practices for workflows, handoffs, and testing, and has it check its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). - -For more, see the [coding agents guide](https://docs.livekit.io/intro/coding-agents/). - ## Run the agent 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: @@ -120,6 +107,22 @@ To check a change turn by turn without a live session, use the [agent debugger]( 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 coding agents + +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/). + +**Agent skills.** Install LiveKit's [agent skills](https://docs.livekit.io/reference/developer-tools/agent-skills/), which teach your coding agent to build, debug, test, and deploy LiveKit agents: + +```console +lk skills install +``` + +To get the latest skills, run `lk skills update`. + +**`AGENTS.md`.** Teaches your coding agent LiveKit's best practices for workflows, handoffs, and testing, and has it check its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). + +For more, see the [coding agents guide](https://docs.livekit.io/intro/coding-agents/). + ## Using this template for your own project After you create your own project from this template: From 281506f7420b8cfa1e705aea37aa6a9fc424e276 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 23:26:58 +0000 Subject: [PATCH 11/13] Fold LiveKit Cloud sign-up and lk cloud auth into the CLI step Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4097e08..4ce015f 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,21 @@ A starter project for building voice AI apps with [LiveKit Agents for Python](ht ## Getting started -1. Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/): +1. Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) and sign in to LiveKit Cloud: - **macOS:** `brew install livekit-cli` - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` - **Windows:** `winget install LiveKit.LiveKitCLI` -1. Create your project from this starter. The CLI writes your LiveKit Cloud credentials to `.env.local` and installs dependencies and [agent skills](#using-coding-agents) for your coding agents: + Sign up for a free [LiveKit Cloud](https://cloud.livekit.io/) account if you don't have one, then link it to the CLI: ```console lk cloud auth + ``` + +1. Create your project from this starter. The CLI writes your LiveKit Cloud credentials to `.env.local` and installs dependencies and [agent skills](#using-coding-agents) for your coding agents: + + ```console lk agent init my-agent --template agent-starter-python ``` From f8e5c3c222b8c345eba3764000fb7ffb9cae38aa Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 23:27:10 +0000 Subject: [PATCH 12/13] Trim the project creation step Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4ce015f..86e9580 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ A starter project for building voice AI apps with [LiveKit Agents for Python](ht lk cloud auth ``` -1. Create your project from this starter. The CLI writes your LiveKit Cloud credentials to `.env.local` and installs dependencies and [agent skills](#using-coding-agents) for your coding agents: +1. Create your project from this starter: ```console lk agent init my-agent --template agent-starter-python From 06c5eb0860cf748388f68eecd8c4c8ac01249eef Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 23:46:58 +0000 Subject: [PATCH 13/13] Add the package manager and dependency install to getting started Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Rquu1YZenr2ZXTsyVptCYu --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 86e9580..e3bdd5d 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ A starter project for building voice AI apps with [LiveKit Agents for Python](ht ## Getting started +1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), which manages Python and the project's dependencies. + 1. Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) and sign in to LiveKit Cloud: - **macOS:** `brew install livekit-cli` @@ -30,6 +32,7 @@ A starter project for building voice AI apps with [LiveKit Agents for Python](ht ```console cd my-agent + uv sync lk agent console ```