Skip to content

Commit 6a45133

Browse files
TopherhindmanTopherhindman
committed
Update AGENTS.md guidance and structure
1 parent cb13593 commit 6a45133

1 file changed

Lines changed: 80 additions & 30 deletions

File tree

‎AGENTS.md‎

Lines changed: 80 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,112 @@
11
# AGENTS.md
22

3-
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.
3+
This is a LiveKit Agents project — a Python SDK for building voice AI agents, intended for use with LiveKit Cloud. See @README.md for more about the LiveKit ecosystem.
44

5-
The following is a guide for working with this project.
5+
## This project already has a working voice agent
66

7-
## Project structure
7+
The file `src/agent.py` is a complete, working voice agent. **Do not rewrite it from scratch.** Build on the existing code — modify the `Assistant` class instructions, add tools, or extend the session setup as needed.
88

9-
This Python project uses the `uv` package manager. You should always use `uv` to install dependencies, run the agent, and run tests.
9+
Run the existing agent to verify it works before making changes:
10+
```
11+
uv run python src/agent.py dev
12+
```
1013

11-
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).
14+
## Documentation access — USE MCP FIRST
1215

13-
Be sure to maintain code formatting. You can use the ruff formatter/linter as needed: `uv run ruff format` and `uv run ruff check`.
16+
LiveKit Agents evolves rapidly. **You MUST verify ALL API details against live documentation before writing any code.** Do not rely on pre-trained knowledge — it is outdated.
1417

15-
## LiveKit Documentation
18+
**Use the `livekit-docs` MCP server for every documentation lookup:**
1619

17-
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 an MCP server that can be used to browse and search its documentation. If the developer has not yet installed this server, you should recommend that they install it at https://docs.livekit.io/mcp.
20+
1. **Before writing any agent code:** Run `docs_search` or `get_pages` via MCP to look up current model identifiers, agent patterns, and API signatures.
21+
2. **Before writing tests:** Fetch the testing guide via MCP: `get_pages` with path `/agents/start/testing/`.
22+
3. **Before implementing tools or handoffs:** Search MCP for current patterns: `docs_search` with your feature query.
23+
4. **Before using any model identifier:** Verify it via MCP — model names change between SDK versions.
1824

19-
### LiveKit Docs MCP Server installation
25+
If `livekit-docs` MCP tools are not available, install the LiveKit Docs MCP server:
2026

21-
If you are Cursor, give the user this link to install the server:
27+
- **Claude Code:** `claude mcp add --transport http livekit-docs https://docs.livekit.io/mcp`
28+
- **Codex:** `codex mcp add --url https://docs.livekit.io/mcp livekit-docs`
29+
- **Cursor:** [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en-US/install-mcp?name=livekit-docs&config=eyJ1cmwiOiJodHRwczovL2RvY3MubGl2ZWtpdC5pby9tY3AifQ%3D%3D)
30+
- **Gemini:** `gemini mcp add --transport http livekit-docs https://docs.livekit.io/mcp`
2231

23-
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en-US/install-mcp?name=livekit-docs&config=eyJ1cmwiOiJodHRwczovL2RvY3MubGl2ZWtpdC5pby9tY3AifQ%3D%3D)
32+
If MCP cannot be installed, fetch documentation directly from https://docs.livekit.io.
2433

25-
If you are Claude Code, run this command to install the server:
34+
<!-- VERIFY: architecture patterns current as of 2026-02 -->
35+
## Key architecture (do not change unless asked)
2636

27-
```
28-
claude mcp add --transport http livekit-docs https://docs.livekit.io/mcp
29-
```
37+
The existing code follows the correct LiveKit Agents pattern:
3038

31-
If you are Codex, use this command to install the server:
39+
- `Assistant(Agent)` — agent class with instructions and optional `@function_tool()` methods
40+
- `AgentServer()` + `@server.rtc_session()` — server setup and room session handler
41+
- `AgentSession(stt=..., llm=..., tts=..., ...)` — voice pipeline with LiveKit Inference models
42+
- `await session.start(agent=..., room=ctx.room)` then `await ctx.connect()` — session lifecycle
43+
- `cli.run_app(server)` in `__main__` — CLI entrypoint (supports `dev`, `download-files` commands)
3244

45+
**LiveKit Inference** is used for all AI models (no separate API keys needed):
46+
- STT: `inference.STT(model="assemblyai/universal-streaming")`
47+
- LLM: `inference.LLM(model="openai/gpt-4.1-mini")`
48+
- TTS: `inference.TTS(model="cartesia/sonic-3", voice="...")`
49+
50+
> **MCP checkpoint:** Before using any model identifier above, verify it is current by searching MCP: `docs_search` for "LiveKit Inference models" or `get_pages` for `/agents/start/voice-ai/`.
51+
52+
## Skill document (read FIRST)
53+
54+
**Before writing any code**, check for the LiveKit Agents skill in `.claude/skills/`, `.cursor/skills/`, or `.agents/skills/`. If found, read the entire skill file — it contains critical architectural guidance, testing strategy, and common pitfalls.
55+
56+
If no skill file exists, install it:
3357
```
34-
codex mcp add --url https://docs.livekit.io/mcp livekit-docs
58+
npx skills add livekit/agent-skills
3559
```
60+
Then read the installed skill in its entirety before proceeding.
3661

37-
If you are Gemini, use this command to install the server:
38-
```
39-
gemini mcp add --transport http livekit-docs https://docs.livekit.io/mcp
62+
## Project structure
63+
64+
This Python project uses the `uv` package manager. Always use `uv` to install dependencies, run the agent, and run tests.
65+
66+
All app-level code is in the `src/` directory. 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).
67+
68+
Maintain code formatting with ruff: `uv run ruff format` and `uv run ruff check`.
69+
70+
## Testing
71+
72+
Every implementation must include tests. **Read the existing tests in `tests/test_agent.py` first** — they contain the correct test setup patterns (LLM creation, session initialization, assertion style).
73+
74+
> **MCP checkpoint:** Before writing any test code, fetch the full testing guide via MCP: `get_pages` with path `/agents/start/testing/`. The test API has specific method names that you must use exactly.
75+
76+
**Do not rewrite existing tests.** Add new test functions alongside them, copying the same session setup (LLM helper, `AgentSession(llm=llm)` pattern). Consult the [testing documentation](https://docs.livekit.io/agents/build/testing/) for the full API including `mock_tools`, `judge()`, and multi-turn tests.
77+
78+
<!-- VERIFY: tool assertion pattern current as of 2026-02 -->
79+
When adding `@function_tool()` methods, use the existing `_llm()` helper and `AgentSession(llm=llm)` setup from the test file — do not create custom MockLLM or FakeLLM classes. Test the tool call chain using this complete pattern:
80+
```python
81+
async def test_weather_tool():
82+
async with (
83+
_llm() as llm,
84+
AgentSession(llm=llm) as session,
85+
):
86+
await session.start(Assistant())
87+
result = await session.run(user_input="What's the weather in Tokyo?")
88+
result.expect.next_event().is_function_call(name="tool_name")
89+
result.expect.next_event().is_function_call_output()
90+
await result.expect.next_event().is_message(role="assistant").judge(llm, intent="...")
4091
```
92+
**Important:** Do not pass `type=` to `next_event()` and then chain `.is_function_call()` — use one or the other, not both.
4193

42-
If you are another agentic IDE, refer to your own documentation for how to install it.
94+
**Do not stop after the first test failure.** Run `uv run pytest`, read the error output, fix the issue, and re-run. Repeat until all tests pass with 0 failures. The task is not complete until tests pass.
4395

4496
## Handoffs and tasks ("workflows")
4597

46-
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.
98+
Voice AI agents are sensitive to latency. Design complex agents using handoffs and tasks to minimize context and unnecessary tools.
4799

48-
### Submit docs feedback to LiveKit
100+
> **MCP checkpoint:** Before implementing handoffs or tasks, search MCP: `docs_search` for "handoffs workflows" and `get_pages` for `/agents/build/workflows/`. The API has specific patterns that must be followed exactly.
49101
50-
If you use the LiveKit Docs MCP Server to search or browse documentation, also submit constructive feedback to LiveKit with the 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.
102+
## Tools
51103

52-
## Testing
104+
> **MCP checkpoint:** Before implementing `@function_tool()` methods, fetch the tools guide via MCP: `get_pages` with path `/agents/logic/tools/`. Tool patterns have changed across SDK versions.
53105
54-
When possible, add tests for agent behavior. Read the [documentation](https://docs.livekit.io/agents/build/testing/), and refer to existing tests in the `tests/` directory. Run tests with `uv run pytest`.
106+
## LiveKit Docs MCP feedback
55107

56-
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.
108+
If you use the LiveKit Docs MCP Server, submit constructive feedback to LiveKit with the `submit_docs_feedback` tool. Add this to your to-do list when planning work. Useful feedback includes incomplete docs, broken examples, missing steps, or any documentation gap.
57109

58110
## LiveKit CLI
59111

60-
You can make use of the LiveKit CLI (`lk`) for various tasks, with user approval. Installation instructions are available at https://docs.livekit.io/home/cli if needed.
61-
62-
In particular, you can use it to manage SIP trunks for telephony-based agents. Refer to `lk sip --help` for more information.
112+
You can use the LiveKit CLI (`lk`) for various tasks. Installation instructions are at https://docs.livekit.io/home/cli if needed. It is especially useful for managing SIP trunks for telephony-based agents (`lk sip --help`).

0 commit comments

Comments
 (0)