Workflow

lk-mav init
lk-mav setup    # answer prompts; credentials stored in .env
lk-mav validate
lk-mav run      # or lk-mav run --dev
lk-mav doctor   # optional: check integration health

All customization happens through the CLI, lk-mav.config.yaml, and .env. Secrets stay in .env only.

Configuration

You can customize agents without changing code by using a config file. Secrets stay in .env; the config file holds only non-secret options (prompts, voices, which agents are enabled, and toggles for memory and MCP).

1. Copy the example config: cp config/agents.example.yaml config/agents.yaml (or set AGENTS_CONFIG_PATH in .env to your file path).
2. Edit config/agents.yaml:
   • session: LLM model, STT model, default TTS, default_timezone, and flags mcp_enabled and memory_enabled. When mcp_enabled is false, MCP is not attached even if MCP_SERVER_URL is set in .env. When memory_enabled is false, Mem0 is not used even if MEM0_API_KEY is set.
   • agents: List of agents. One must have role: starter and list specialist ids in handoff_to (e.g. [booking, consultant]). Each agent has id, name, role, instructions, tts (model + voice), and optionally memory_enabled / mcp_enabled. Specialists can use agent_type: booking (adds time tools and MCP-focused behavior) or generic. For booking instructions you can use placeholders {appointment_topic}, {now_utc}, {default_timezone}; for consultant use {topic}.
3. Run the agent as usual. If no config file is found, built-in defaults are used (current hardcoded prompts and agents).

CLI Reference

Agent — uv run python src/agents.py [command]

Dispatch — uv run python scripts/dispatch_agent.py

Dispatches lk-mav to a room via the Agent Dispatch API. Requires LIVEKIT_* in .env.

Examples

uv run python scripts/dispatch_agent.py -r my-room
uv run python scripts/dispatch_agent.py -r my-room -m '{"user_name":"Alice"}' -l
uv run python scripts/dispatch_agent.py -r my-room --no-create

LiveKit CLI — lk

Cloud & auth

Agent (LiveKit Cloud)

Dispatch

Dispatch and testing

Because dispatch is explicit, connect only after dispatching:

1. Dispatch: lk dispatch create --agent-name lk-mav --room my-room or uv run python scripts/dispatch_agent.py -r my-room
2. Connect: Agents Playground or your frontend — join the same room.

For token-based dispatch, use RoomAgentDispatch with agent_name="lk-mav" in RoomConfiguration. For SIP, use SIP dispatch rules.

Deploy

lk agent deploy

Uses the project Dockerfile; download-files runs at build time, and the container runs uv run src/agents.py start.

License

MIT — see LICENSE.