├── .env.example
├── .github
    └── assets
    │   ├── .DS_Store
    │   └── livekit-mark.png
├── .gitignore
├── LICENSE
├── README.md
├── agent.py
├── renovate.json
├── requirements.txt
└── taskfile.yaml


/.env.example:
--------------------------------------------------------------------------------
1 | LIVEKIT_URL=<your LiveKit server URL>
2 | LIVEKIT_API_KEY=<your API Key>
3 | LIVEKIT_API_SECRET=<your API Secret>
4 | OPENAI_API_KEY=<To use other providers, press Enter for now and edit .env.local>
5 | DEEPGRAM_API_KEY=<To use other providers, press Enter for now and edit .env.local>
6 | CARTESIA_API_KEY=<To use other providers, press Enter for now and edit .env.local>
7 | 


--------------------------------------------------------------------------------
/.github/assets/.DS_Store:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/livekit-examples/voice-pipeline-agent-python/e208872811af6028b34e340631dbeaf2531717f8/.github/assets/.DS_Store


--------------------------------------------------------------------------------
/.github/assets/livekit-mark.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/livekit-examples/voice-pipeline-agent-python/e208872811af6028b34e340631dbeaf2531717f8/.github/assets/livekit-mark.png


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .env.local
2 | .venv/
3 | venv/
4 | .DS_Store
5 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2025  LiveKit, Inc.
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | <a href="https://livekit.io/">
 2 |   <img src="./.github/assets/livekit-mark.png" alt="LiveKit logo" width="100" height="100">
 3 | </a>
 4 | 
 5 | # Python Voice Agent
 6 | 
 7 | <p>
 8 |   <a href="https://cloud.livekit.io/projects/p_/sandbox"><strong>Deploy a sandbox app</strong></a>
 9 |   •
10 |   <a href="https://docs.livekit.io/agents/overview/">LiveKit Agents Docs</a>
11 |   •
12 |   <a href="https://livekit.io/cloud">LiveKit Cloud</a>
13 |   •
14 |   <a href="https://blog.livekit.io/">Blog</a>
15 | </p>
16 | 
17 | A basic example of a voice agent using LiveKit and Python.
18 | 
19 | ## Dev Setup
20 | 
21 | Clone the repository and install dependencies to a virtual environment:
22 | 
23 | ```console
24 | # Linux/macOS
25 | cd voice-pipeline-agent-python
26 | python3 -m venv venv
27 | source venv/bin/activate
28 | pip install -r requirements.txt
29 | python3 agent.py download-files
30 | ```
31 | 
32 | <details>
33 |   <summary>Windows instructions (click to expand)</summary>
34 |   
35 | ```cmd
36 | :: Windows (CMD/PowerShell)
37 | cd voice-pipeline-agent-python
38 | python3 -m venv venv
39 | venv\Scripts\activate
40 | pip install -r requirements.txt
41 | ```
42 | 
43 | </details>
44 | 
45 | Set up the environment by copying `.env.example` to `.env.local` and filling in the required values:
46 | 
47 | - `LIVEKIT_URL`
48 | - `LIVEKIT_API_KEY`
49 | - `LIVEKIT_API_SECRET`
50 | - `OPENAI_API_KEY`
51 | - `CARTESIA_API_KEY`
52 | - `DEEPGRAM_API_KEY`
53 | 
54 | You can also do this automatically using the LiveKit CLI:
55 | 
56 | ```console
57 | lk app env
58 | ```
59 | 
60 | Run the agent:
61 | 
62 | ```console
63 | python3 agent.py console
64 | ```
65 | 
66 | This agent can use a frontend application to communicate with. You can use one of our example frontends in [livekit-examples](https://github.com/livekit-examples/), create your own following one of our [client quickstarts](https://docs.livekit.io/realtime/quickstarts/), or test instantly against one of our hosted [Sandbox](https://cloud.livekit.io/projects/p_/sandbox) frontends.
67 | 
68 | Run the agent with the following command when using a frontend application.
69 | 
70 | ```console
71 | python3 agent.py dev
72 | ```
73 | 


--------------------------------------------------------------------------------
/agent.py:
--------------------------------------------------------------------------------
  1 | import logging
  2 | 
  3 | from dotenv import load_dotenv
  4 | from livekit.agents import (
  5 |     Agent,
  6 |     AgentSession,
  7 |     AutoSubscribe,
  8 |     JobContext,
  9 |     JobProcess,
 10 |     WorkerOptions,
 11 |     cli,
 12 |     metrics,
 13 |     RoomInputOptions,
 14 | )
 15 | from livekit.plugins import (
 16 |     cartesia,
 17 |     openai,
 18 |     deepgram,
 19 |     noise_cancellation,
 20 |     silero,
 21 | )
 22 | from livekit.plugins.turn_detector.multilingual import MultilingualModel
 23 | 
 24 | 
 25 | load_dotenv(dotenv_path=".env.local")
 26 | logger = logging.getLogger("voice-agent")
 27 | 
 28 | 
 29 | class Assistant(Agent):
 30 |     def __init__(self) -> None:
 31 |         # This project is configured to use Deepgram STT, OpenAI LLM and Cartesia TTS plugins
 32 |         # Other great providers exist like Cerebras, ElevenLabs, Groq, Play.ht, Rime, and more
 33 |         # Learn more and pick the best one for your app:
 34 |         # https://docs.livekit.io/agents/plugins
 35 |         super().__init__(
 36 |             instructions="You are a voice assistant created by LiveKit. Your interface with users will be voice. "
 37 |             "You should use short and concise responses, and avoiding usage of unpronouncable punctuation. "
 38 |             "You were created as a demo to showcase the capabilities of LiveKit's agents framework.",
 39 |             stt=deepgram.STT(),
 40 |             llm=openai.LLM(model="gpt-4o-mini"),
 41 |             tts=cartesia.TTS(),
 42 |             # use LiveKit's transformer-based turn detector
 43 |             turn_detection=MultilingualModel(),
 44 |         )
 45 | 
 46 |     async def on_enter(self):
 47 |         # The agent should be polite and greet the user when it joins :)
 48 |         self.session.generate_reply(
 49 |             instructions="Hey, how can I help you today?", allow_interruptions=True
 50 |         )
 51 | 
 52 | 
 53 | def prewarm(proc: JobProcess):
 54 |     proc.userdata["vad"] = silero.VAD.load()
 55 | 
 56 | 
 57 | async def entrypoint(ctx: JobContext):
 58 |     logger.info(f"connecting to room {ctx.room.name}")
 59 |     await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)
 60 | 
 61 |     # Wait for the first participant to connect
 62 |     participant = await ctx.wait_for_participant()
 63 |     logger.info(f"starting voice assistant for participant {participant.identity}")
 64 | 
 65 |     usage_collector = metrics.UsageCollector()
 66 | 
 67 |     # Log metrics and collect usage data
 68 |     def on_metrics_collected(agent_metrics: metrics.AgentMetrics):
 69 |         metrics.log_metrics(agent_metrics)
 70 |         usage_collector.collect(agent_metrics)
 71 | 
 72 |     session = AgentSession(
 73 |         vad=ctx.proc.userdata["vad"],
 74 |         # minimum delay for endpointing, used when turn detector believes the user is done with their turn
 75 |         min_endpointing_delay=0.5,
 76 |         # maximum delay for endpointing, used when turn detector does not believe the user is done with their turn
 77 |         max_endpointing_delay=5.0,
 78 |     )
 79 | 
 80 |     # Trigger the on_metrics_collected function when metrics are collected
 81 |     session.on("metrics_collected", on_metrics_collected)
 82 | 
 83 |     await session.start(
 84 |         room=ctx.room,
 85 |         agent=Assistant(),
 86 |         room_input_options=RoomInputOptions(
 87 |             # enable background voice & noise cancellation, powered by Krisp
 88 |             # included at no additional cost with LiveKit Cloud
 89 |             noise_cancellation=noise_cancellation.BVC(),
 90 |         ),
 91 |     )
 92 | 
 93 | 
 94 | if __name__ == "__main__":
 95 |     cli.run_app(
 96 |         WorkerOptions(
 97 |             entrypoint_fnc=entrypoint,
 98 |             prewarm_fnc=prewarm,
 99 |         ),
100 |     )
101 | 


--------------------------------------------------------------------------------
/renovate.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
 3 |   "extends": [
 4 |     "config:recommended"
 5 |   ],
 6 |   "packageRules": [
 7 |     {
 8 |       "matchUpdateTypes": ["minor", "patch", "pin", "digest"],
 9 |       "automerge": true
10 |     }
11 |   ]
12 | }
13 | 


--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
 1 | livekit-agents~=1.0
 2 | livekit-plugins-openai~=1.0
 3 | livekit-plugins-cartesia~=1.0
 4 | livekit-plugins-deepgram~=1.0
 5 | livekit-plugins-silero~=1.0
 6 | # optional, only when using LiveKit's turn detection model
 7 | livekit-plugins-turn-detector~=1.0
 8 | # optional, only if background voice & noise cancellation is needed
 9 | livekit-plugins-noise-cancellation>=0.2.0,<1.0.0
10 | python-dotenv~=1.0
11 | 


--------------------------------------------------------------------------------
/taskfile.yaml:
--------------------------------------------------------------------------------
 1 | version: "3"
 2 | output: interleaved
 3 | dotenv: [".env.local"]
 4 | 
 5 | tasks:
 6 |   post_create:
 7 |     desc: "Runs after this template is instantiated as a Sandbox or Bootstrap"
 8 |     cmds:
 9 |       - echo -e "To setup and run the agent:\r\n"
10 |       - echo -e "\tcd {{.ROOT_DIR}}\r"
11 |       - echo -e "\tpython3 -m venv venv\r"
12 |       - platforms: [darwin, linux]
13 |         cmd: echo -e "\tsource venv/bin/activate\r"
14 |       - platforms: [windows]
15 |         cmd: echo -e "\tpowershell venv/Scripts/Activate.ps1\r"
16 |       - echo -e "\tpip install -r requirements.txt\r"
17 |       - echo -e "\tpython3 agent.py download-files\r"
18 |       - echo -e "\tpython3 agent.py dev\r\n"
19 | 
20 |   install:
21 |     desc: "Bootstrap application for local development"
22 |     cmds:
23 |       - "python3 -m venv venv"
24 |       - platforms: [darwin, linux]
25 |         cmd: "source venv/bin/activate"
26 |       - platforms: [windows]
27 |         cmd: "powershell venv/Scripts/Activate.ps1"
28 |       - "pip install -r requirements.txt"
29 | 
30 |   dev:
31 |     interactive: true
32 |     cmds:
33 |       - platforms: [darwin, linux]
34 |         cmd: "source venv/bin/activate"
35 |       - platforms: [windows]
36 |         cmd: "powershell venv/Scripts/Activate.ps1"
37 |       - "python3 agent.py dev"
38 | 


--------------------------------------------------------------------------------