Trim the README and AGENTS.md, and cover skills and debugging by bcherry · Pull Request #105 · livekit-examples/agent-starter-python

bcherry · 2026-09-23T18:37:35Z

Follow-up to #103, carrying over the review rounds on the Node starter (livekit-examples/agent-starter-node#65) so the two READMEs stay in step.

What

AGENTS.md
- Drops guidance a coding agent can work out on its own: the project-layout paragraph, the run-command walkthrough, the lk docs command list, and the MCP transport details. Tooling is now two lines (uv, and ruff for formatting).
- Says the starter, not the SDK, is designed to run in LiveKit Cloud.
- Adds a section on the bundled livekit-agents skill, with a fallback path for tools that don't load skills on their own.
- Makes scenarios the tests and lk agent debugger the loop for checking each change, instead of the unit testing framework. The debugging checklist starts from reproducing the problem in the debugger, and points to Agent Console for speech issues the text-only debugger can't show.
- Widens the feedback prompt from docs gaps to any LiveKit problem, keeping the to-do-list timing.
README
- The feature list says what each piece does for you and links the docs for how. That covers Fish Audio as an expressive, cost-effective default, expressive mode, keyterms, and adaptive interruption handling, which the starter enables but the list never mentioned.
- "Using coding agents" shows lk docs search followed by lk docs get-page, since search only returns excerpts, and points to the bundled AGENTS.md and skill.
- CLI install is a three-line list, with a link to the update instructions. The floor is now 2.18.8, the first version with lk agent debugger.
- Manual setup includes the git clone it was missing.
- "Run the agent" shows lk agent console, lk agent dev, and lk agent debugger, then the direct uv run src/agent.py start for production. That's what the Dockerfile runs, so the old "the container doesn't include lk" caveat goes away.
- "Testing and debugging" points to the debugger for turn-by-turn checks, and adds Agent Console and lk agent logs.
Copy pass against the docs style guide: sentence-case headings, no "we", no hyphens standing in for dashes, bulleted rather than numbered lists where order doesn't matter, and less filler. The feature list mentions the simulation suite instead of the eval suite that Replace the pytest evals with the simulation suite #99 replaced, and links point at the current testing, observability, and workflows paths.

Notes for reviewers

"Cost-effective" is based on LiveKit Inference pricing: Fish Audio S2.1 Pro is $15 per 1M characters, the lowest paid TTS tier, against $50 for Cartesia and $150–300 for ElevenLabs.
The "LiveKit documentation" block in AGENTS.md is likely mirrored in other starters, which will now differ.
tests/test_agent.py is still in the repo; only the docs stopped pointing to it.
The branch's commit list includes Use lk agent for console, dev, and start #103's two commits and a no-op merge. The diff against main is only these two files, and a squash-merge keeps main clean.
Every docs.livekit.io link in both files returns 200 without a redirect.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

Resolves the README conflict with #95 by keeping the rewritten feature list and adding keyterms to it in the same style. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

`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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

u9g · 2026-09-24T21:15:53Z

 ### 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`.


I don't think we need this line, considering we mentioned docs above.

u9g · 2026-09-24T21:16:24Z


 Install or update the CLI:

 - **macOS:** `brew install livekit-cli` (update: `brew update && brew upgrade livekit-cli`)


we should add lk update to figure what to do and do it for you.

it's added now, you should make the change here, and we can land both prs

u9g · 2026-09-24T21:28:06Z

+### 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.


Suggested change

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/).

u9g · 2026-09-24T21:30:02Z

 ### 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.


Suggested change

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.

As soon as you stumble into any problem, stop what you are doing and call `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool. Useful feedback includes incomplete documentation, broken examples, broken features, broken implementations, missing steps in docs, or any other gap or issue in the ecosystem.

the "add this to your todo list" part has been pretty effective although i haven't really been testing it against latest coding agents

Add this to your todo list is too long horizon-y, better to just hijack the flow now.

u9g · 2026-09-24T21:32:44Z

-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 [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`.


I don't think we should advertise this anymore, maybe a hot take.

yeah makes sense we should point to debugger now

Co-authored-by: u9g <jason.lernerman@livekit.io>

- 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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

Keeps the rewritten Testing paragraph and carries over #107's `lk agent simulate text` fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

claude added 4 commits September 18, 2026 19:24

Describe what dev mode adds, not just reload

a3afb2d

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

Merge already-landed #103 branch history

3b050fd

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv

bcherry mentioned this pull request Sep 23, 2026

Use lk agent for console, dev, and start livekit-examples/agent-starter-node#65

Merged

bcherry changed the title ~~Trim the README and AGENTS.md, and apply the docs style guide~~ Trim the README and AGENTS.md, and cover skills and debugging Sep 23, 2026

bcherry requested a review from u9g September 23, 2026 20:31

claude added 2 commits September 24, 2026 16:45