Voice agent workers (livekit-agents)
LiveKit Agents workers that answer the calls routed to a Navin voice agent: registered under the agent name of the SIP dispatch rules, they fetch the configuration of the agent from Navin Enterprise, talk through OpenAI compatible speech to text, LLM (LiteLLM) and text to speech endpoints, transfer to a human and report the call events.
Generated from catalog/services/livekit-agents.yaml: do not edit by hand.
Summary
| Version | 1.0.0 |
| Use | install and configure |
| Layer | functional (AI catalog) |
| Category | AI serving |
| Installation methods | python |
| External connection | no |
| Sandbox only | no |
Licence
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Licence exceptions of its dependencies | LEX-029 (pending, awaiting the client), LEX-030 (pending, awaiting the client), LEX-031 (pending, awaiting the client) |
| Licence note | The LiveKit Agents SDK and its OpenAI and Silero plugins are Apache-2.0 (https://github.com/livekit/agents); the navin-voice-agent package is the code of Navin. |
| Platform component | livekit-agents |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| Python package | navin-voice-agent | 1.0.0 | LicenseRef-Navin-Enterprise | interpreters, in order of preference python3.12, python3.11, python3.10 |
| Python package | livekit-agents | 1.8.10 | Apache-2.0 | interpreters, in order of preference python3.12, python3.11, python3.10 |
| Python package | livekit-plugins-openai | 1.8.10 | Apache-2.0 | interpreters, in order of preference python3.12, python3.11, python3.10 |
| Python package | livekit-plugins-silero | 1.8.10 | Apache-2.0 | interpreters, in order of preference python3.12, python3.11, python3.10 |
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
python | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- at least 2048 MB of memory (warning,
memory). - at least 2 CPU (warning,
cpu).
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
worker | health | 8581/tcp | no |
worker | metrics | 6793/tcp | yes |
Services and connections needed
livekit:livekit.navin_enterprise:navin-enterprise.litellm:litellm.
Details and resolution: see Dependencies.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
python | yes | a Python virtual environment holding the Python packages of the descriptor |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
Voice agent worker (worker) | worker | python | 8581/tcp, 6793/tcp |
Single worker (single) (default)
One worker host.
What the mode deploys:
| Component | Placement |
|---|---|
worker | min 1, max 1 |
Worker pool (pool)
Several workers registered under the same agent name; LiveKit gives each new call to a worker below its load threshold.
What the mode deploys:
| Component | Placement |
|---|---|
worker | min 2, recommended 2 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select Voice agent workers. The card shows the licence
Apache-2.0and the dependencies the installation needs. -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
single(default),pool. Each mode deploys the components listed in Installation methods and modes. -
Bind the dependencies. On the Bindings step, choose for each dependency (
livekit,navin_enterprise,litellm) Install with the platform or Use an existing connection; an optional dependency can stay on No binding. -
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
High availability
| Cluster | native (native) |
| High availability | redundancy (redundancy) |
| Failover | native (native) |
| Replication | none (none) |
| Quorum | none (none) |
| Discovery | registry (registry) |
| Entry point | none (none) |
| Official documentation | https://docs.livekit.io/agents/server/ |
| References | https://github.com/livekit/agents |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
single | standalone (standalone) | single (single) | - | 1 | One worker, no fault tolerance. |
pool | ha (ha) | parallel jobs (parallel-jobs) | - | 2 | Several workers; LiveKit dispatches each new call to an available worker. |
Notes
- The loss of a worker ends the voice sessions it runs; the fallback rule of Navin Enterprise routes those calls to a human queue.
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Health port (health_port) | port | 8581 | - | no | no | no | HTTP health of the worker: 200 once registered with LiveKit, 503 otherwise; /worker gives its agent name and load. |
Metrics port (metrics_port) | port | 6793 | - | no | no | no | Prometheus port of the worker. |
LiveKit URL (livekit_url) | string | (empty) | - | no | no | no | ws:// or wss:// URL of LiveKit Server (its load balancer in the distributed mode); empty: the first server of the livekit binding. |
Models
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Agent name (agent_name) | string | navin-voice | ^[a-z][a-z0-9-]{1,62}$ | no | no | yes | Name the dispatch rules of Navin Enterprise give in room_config.agents (explicit dispatch). |
LLM key (llm_api_key) | password | (empty) | - | no | yes | no | LiteLLM virtual key of the workers (sk-...); empty: the master key of the litellm binding. |
Speech key (speech_api_key) | password | (empty) | - | no | yes | no | Key of the speech to text and text to speech endpoints; empty: the LLM key. |
Capacity
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Load threshold (load_threshold) | float | 0.7 | min 0.1, max 1.0 | no | no | no | CPU load above which a worker takes no new call. |
Warm processes (idle_processes) | int | 2 | min 0, max 64 | no | no | no | Job processes kept warm (VAD loaded) to answer without delay. |
Dependencies
For each active dependency the Manager takes the first of: the binding chosen in the wizard; a service of the same installation that provides it; a service already installed in the cluster; the only connection of the expected type. Otherwise an optional dependency stays unbound, and a required one is added to the installation in its default mode (the column below names the catalog service added).
| Binding | Provided by | Connection type | Endpoint | Optional | When nothing is bound | Description |
|---|---|---|---|---|---|---|
livekit | livekit | - | signal | no | livekit is added to the installation | LiveKit Server the workers register with (API key pair). |
navin_enterprise | navin-enterprise | - | api | no | navin-enterprise is added to the installation | Telephony API of Navin Enterprise: runtime of the voice agents, call events, transfers and lookups (worker token of the binding). |
litellm | litellm | - | api | no | litellm is added to the installation | OpenAI compatible gateway of the LLM and, when Navin Enterprise routes them there, of the speech models. |
Commands
| Command | Component | Target | Description |
|---|---|---|---|
Worker state (worker_info) | worker | every host | Agent name, active calls and load of every worker. |
Recent logs (logs) | worker | chosen host | Last lines of the worker journal. |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
worker | HTTP http://{{ host.ip or '127.0.0.1' }}:{{ config.health_port }}/ | Expected 200; 60 retries; interval 2 s; timeout 3 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|---|---|---|---|
memory | memory_mb {"min": 2048} | at least 2048 MB of memory | warning | every component |
cpu | cpu_count {"min": 2} | at least 2 CPU | warning | every component |
Uninstall
Paths removed when the data is purged: {{ paths.log }}.
Quick links
- Metrics:
http://{{ host.fqdn }}:{{ config.metrics_port }}/metrics
Upstream documentation
- Homepage: https://docs.livekit.io/agents/
- Source: https://github.com/livekit/agents
- High availability: https://docs.livekit.io/agents/server/
- High availability: https://github.com/livekit/agents