LiveKit Agent Example

Agentes de voz construidos sobre LiveKit Agents SDK + Gemini Realtime. Cada agente es una variante independiente que combina audio, texto, herramientas y skills según necesidad.

Stack

• Python 3.10+
• LiveKit Agents SDK
• Gemini Realtime (gemini-2.5-flash-native-audio-preview-12-2025)

gemini-3.1-flash-live-preview es solo audio y no soporta generate_reply() (saludo inicial). Usa el modelo anterior si necesitas saludo automático.

Quickstart

Setup

python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows
pip install -r requirements.txt
cp .env.example .env        # editar credenciales (ver .env.example para todas las variables)
pytest                      # verificar instalación (opcional)

Arrancar un agente

python agent_live_basic.py console              # solo voz
python agent_live_tools.py console              # + tools genéricas
python agent_live_tools_multimodal.py console   # + texto + video
python agent_live_multimodal_skills.py console  # + skills
python agent_live_skills_mcp.py console         # + MCP
python agent_live_full.py console               # full stack (recomendado)

Modos de arranque

Modo	Descripción
console	Consola integrada para testing directo del agente.
dev	Agente como servicio independiente. Permite conectar una interfaz web u otro cliente externo.

Gemini: API KEY y modelo Gemini Live

1. Crea cuenta en Google AI Studio: https://aistudio.google.com/
2. Crea un proyecto en el portal.
3. Crea una API KEY para el proyecto.
4. Añade la API key y el modelo en .env.

LiveKit: Cloud + Self-hosted

Cloud (recomendado)

1. Crea cuenta en LiveKit Cloud: https://livekit.com/
2. Crea un proyecto en el portal.
3. Copia LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET.
4. Pega esas variables en .env.
5. Adapta el prompt del agente según necesidades.
6. Arranca con python agent_live_full.py console u otro agente según necesites.

Referencias oficiales:

• LiveKit
• Docs
• Agents
• Playground

Self-hosted (alternativa)

1. Despliega un servidor LiveKit propio.
2. Arranca el servidor local siguiendo la guía oficial.
3. Usa la URL y credenciales del servidor en .env.
4. Arranca el agente con python agent_live_full.py console u otro agente según necesites.

Referencias:

• GitHub
• Self-hosting

El código del agente no cambia entre Cloud y self-hosted; cambia la infraestructura (operación, TLS, red y mantenimiento).

Skills

Las skills son documentos Markdown en .agents/skills/<nombre>/SKILL.md que el agente carga bajo demanda con get_skill(name).

Convención

---
name: <nombre del directorio>
description: <texto que ve el LLM>
---

El cuerpo del Markdown es el contenido completo que recibe el agente: ROLE, instrucciones, tablas, ejemplos, etc.

Carga bajo demanda

El prompt del agente incluye un bloque ## SKILLS DISPONIBLES generado automáticamente que lista todas las skills en disco. Cuando la consulta encaja con una skill, el LLM usa get_skill(name) para cargar su contenido y responder basándose en él.

Skills actuales

Skill	Descripción
taskhome-app	Guía para operar la app taskhome
api-template	Plantilla para crear skills de APIs
skill-creator	Guía para crear skills siguiendo convenciones
manual-markdown	Referencia rápida de sintaxis Markdown
test-skill	Skill de prueba

Añadir una skill

1. Crear .agents/skills/<nombre>/SKILL.md
2. Escribir front matter + contenido
3. Sin tocar código — el discovery es automático

Para patrones de skills de API, ver spec/skills.md.

Tools

Tool	Módulo	Descripción
get_time	tools/tools.py	Hora y fecha actual
get_weather	tools/tools.py	Clima de una ciudad
search_web	tools/tools.py	Búsqueda en DuckDuckGo
send_email	tools/tools.py	Envío de email vía Gmail
get_skill	tools/skills.py	Carga una skill por nombre
list_skills	tools/skills.py	Lista skills disponibles
api_request	tools/http.py	HTTP genérica con auth automática
run_curl	tools/taskhome.py	Curl contra taskhome (legacy)
read_file	tools/filesystem.py	Lee un archivo
list_files	tools/filesystem.py	Lista archivos en un directorio
write_file	tools/filesystem.py	Crea/sobrescribe archivo
edit_file	tools/filesystem.py	Reemplaza texto en archivo
delete_file	tools/filesystem.py	Elimina archivo/directorio
create_skill	tools/skill_manager.py	Crea una skill en custom-skills/

Registry

tools/registry.py centraliza todas las tools:

from tools.registry import get_all_tools  # core + custom
from tools.registry import CORE_TOOLS     # solo core
from tools.registry import ALL_TOOLS      # core + fs (sin custom)

Para detalles de api_request, run_curl, filesystem tools y skill manager, ver spec/tools.md.

Agente MCP

Los agentes con MCP tienen acceso a fuentes de datos externas vía Model Context Protocol. Actualmente: agent_live_skills_mcp.py y agent_live_full.py.

• Auto-discovery de tools desde mcp_servers.json
• Sin mcp instalado o JSON no existe → el agente arranca igual
• Para añadir una fuente nueva, solo añade una entry al JSON

Configuración MCP

Archivo mcp_servers.json en la raíz. Plantillas: mcp_servers.json.example (stdio) y mcp_servers.http.json.example (streamable-http).

Transportes:

• stdio (recomendado): el agente lanza el server como subproceso
• streamable-http: server ya levantado como proceso independiente

Uso:

cp mcp_servers.json.example mcp_servers.json
# Editar mcp_servers.json con las credenciales del servidor
python agent_live_full.py console

Para configuración completa (JSON, env vars, expansion), ver spec/mcp.md.