diff --git a/AGENTS.md b/AGENTS.md index 2c2e754..920d617 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'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, 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") @@ -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..e3bdd5d 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,38 @@ 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/). +## 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` + - **Linux:** `curl -sSL https://get.livekit.io/cli | bash` + - **Windows:** `winget install LiveKit.LiveKitCLI` + + 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: + + ```console + lk agent init my-agent --template agent-starter-python + ``` + +1. Talk to your agent. Run it in your terminal and speak into your microphone: + + ```console + cd my-agent + uv sync + lk agent console + ``` + +## What's included + The starter includes: - A simple [voice AI assistant](https://docs.livekit.io/agents/start/voice-ai/) to extend and customize. @@ -25,64 +57,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/). - -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, 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: - -```console -lk skills install -``` - -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. - -## Dev setup - -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` -- **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 a project from this template. The CLI clones the template and configures your environment: - -```console -lk cloud auth -lk agent init my-agent --template agent-starter-python -``` - -
-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 -``` - -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 -lk cloud auth -lk app env --write --destination .env.local -``` - -
- ## 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: @@ -141,11 +115,28 @@ 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: - **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** 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