Skip to content

AGENTS.md

Latest commit

 

History

History
133 lines (110 loc) · 6.01 KB

AGENTS.md

File metadata and controls

133 lines (110 loc) · 6.01 KB
Raw

AGENTS.md

Build and Development Commands

This project uses uv as the package manager. All commands run from the repository root.

Installation

make install          # Install all dependencies with dev extras (uv sync --all-extras --dev)

Versioning

  • Use a patch version bump by default.
  • Do not use a minor or major version bump unless a human explicitly confirms the bump level.

Code Quality

make format           # Format code with ruff
make lint             # Run ruff linter
make lint-fix         # Run ruff linter and auto-fix issues
make type-check       # Run mypy type checker (strict mode)
make check            # Run all checks (format-check, lint, type-check)

Testing

uv run pytest --unit                    # Run all unit tests
uv run pytest tests/test_tools.py       # Run a single test file
make unit-tests                         # Run unit tests that don't require cloud accounts

Test categories

Every test module declares exactly one category via a module-level marker, and each category has a matching --<category> selection flag. Selection happens before import, so a category run never imports (or fails on) modules outside it.

Marker Flag Meaning
pytest.mark.unit --unit fast, hermetic, no external providers/credentials/network
pytest.mark.audio_eot --audio_eot hermetic audio end-of-turn / turn-detection suite
pytest.mark.plugin("name") --plugin [name] provider integration test (needs that provider's deps/keys)
pytest.mark.stt --stt cross-provider speech-to-text suite (tests/test_stt.py)
pytest.mark.tts --tts cross-provider text-to-speech suite (tests/test_tts.py)
pytest.mark.realtime("name") --realtime [name] realtime-model test
pytest.mark.evals --evals behavioral evals against the LiveKit inference gateway
pytest.mark.docs --docs tests for the docs-build tooling under .github/ 
uv run pytest --unit                    # the CI unit gate (no cloud accounts)
uv run pytest --plugin openai           # only the openai provider tests
uv run pytest --list-categories         # list every module grouped by category, then exit

Adding a test: give the new module a category marker (pytestmark = pytest.mark.unit, etc.) — collection fails with a hint if it lacks one. Run pytest with the --allow-uncategorized option to temporarily disable this rule (CI keeps it on by default).

Running Agents

python myagent.py console   # Terminal mode with local audio I/O (no server needed)
python myagent.py dev       # Development mode with hot reload (connects to LiveKit)
python myagent.py start     # Production mode
python myagent.py connect --room <room> --identity <id>  # Connect to existing room

Linking Local python-rtc (for SDK development)

make link-rtc         # Link to local python-rtc with downloaded FFI artifacts
make link-rtc-local   # Build and link local rust SDK from source (requires cargo)
make unlink-rtc       # Restore PyPI version
make status           # Show current linking status
make doctor           # Check development environment health

Architecture Overview

Core Concepts

  • AgentServer (formerly known as Worker) (worker.py): Main process coordinating job scheduling, launches agents for user sessions
  • JobContext (job.py): Context provided to entrypoint functions for connecting to LiveKit rooms
  • Agent (voice/agent.py): LLM-based application with instructions, tools, and model integrations
  • AgentSession (voice/agent_session.py): Container managing interactions between agents and end users

Key Directories

livekit-agents/livekit/agents/
├── voice/              # Core voice agent: AgentSession, Agent, room I/O, transcription
├── llm/                # LLM integration: chat context, tool definitions, MCP support
├── stt/                # Speech-to-text with fallback and stream adapters
├── tts/                # Text-to-speech with fallback and stream pacing
├── ipc/                # Inter-process communication for distributed job execution
├── cli/                # CLI commands (console, dev, start, connect)
├── inference/          # Remote model inference (LLM, STT, TTS)
├── telemetry/          # OpenTelemetry traces and Prometheus metrics
└── utils/              # Audio processing, codecs, HTTP, async utilities

livekit-plugins/        # 50+ provider plugins (openai, anthropic, google, deepgram, etc.)
tests/                  # Test suite with mock implementations (fake_stt.py, fake_vad.py)
examples/               # Example agents and use cases

Plugin System

Plugins in livekit-plugins/ provide STT, TTS, LLM, and specialized services. Each plugin is a separate package following the pattern livekit-plugins-<provider>. Plugins register via the Plugin base class in plugin.py.

Model Interface Pattern

STT, TTS, LLM, Realtime models have provider-agnostic interfaces with:

  • Base classes defining the interface (stt/stt.py, tts/tts.py, llm/llm.py, llm/realtime.py)
  • Fallback adapters for resilience
  • Stream adapters for different streaming patterns

Job Execution Flow

  1. Worker receives job request from LiveKit server
  2. Job is dispatched to process/thread pool (ipc/proc_pool.py)
  3. Entrypoint function receives JobContext
  4. Agent connects to room via ctx.connect()
  5. AgentSession manages the conversation lifecycle

Environment Variables

  • LIVEKIT_URL: WebSocket URL of LiveKit server
  • LIVEKIT_API_KEY: API key for authentication
  • LIVEKIT_API_SECRET: API secret for authentication
  • LIVEKIT_AGENT_NAME: Agent name for explicit dispatch (optional)
  • Provider-specific keys: OPENAI_API_KEY, DEEPGRAM_API_KEY, ANTHROPIC_API_KEY, etc.

Code Style

  • Line length: 100 characters
  • Python 3.10+ compatibility required
  • Google-style docstrings
  • Strict mypy type checking enabled
  • Use make check and make fix before committing