programa
Liderazgo en Inteligencia Artificial (IA)
6 h
Los agentes de IA de voz están viviendo un gran momento. Los usuarios quieren hablar con sus aplicaciones en lugar de escribirles, y la tecnología por fin es lo suficientemente buena como para que esas conversaciones resulten naturales.
Si deseas crear uno, la API Grok Voice Agent de xAI es un buen punto de partida. Ofrece tiempos de respuesta inferiores a un segundo y costes más bajos que la mayoría de las alternativas, además de compatibilidad inmediata con el código OpenAI existente.
Este tutorial te muestra cómo crear un agente de voz funcional desde cero. Conectarás la autenticación, configurarás las opciones de personalidad y voz, añadirás llamadas con herramientas e implementarás en producción con LiveKit en la nube. La API se ejecuta en Grok 3, que xAI adaptó para conversaciones de voz en tiempo real en lugar del flujo de trabajo habitual de entrada y salida de texto.
¿Qué es la API del agente de voz Grok?
La API Grok Voice Agent es la plataforma de conversación de voz en tiempo real de xAI, lanzada en diciembre de 2025. Procesa el audio directamente sin la conversión habitual de voz a texto y viceversa, lo que reduce el tiempo de respuesta y mantiene la naturalidad de las conversaciones.
Los sistemas tradicionales de IA de voz encadenan tres pasos distintos: transcribir el habla a texto, procesar ese texto mediante un modelo lingüístico y, a continuación, sintetizar la respuesta de nuevo en audio. Este enfoque funciona, pero cada transferencia entre componentes añade retraso. Si se tiene en cuenta la transcripción, el procesamiento y la síntesis, el usuario tardará entre 500 y 1000 ms en obtener una respuesta. Esas pausas se acumulan y hacen que las conversaciones parezcan mecánicas.
Grok Voice Agent omite por completo las conversiones. El sistema capta el audio, razona en el ámbito auditivo y emite audio utilizando un único modelo entrenado en el habla conversacional. Esta arquitectura ofrece un tiempo de respuesta de audio inicial de 0,78 segundos de media, al tiempo que admite la comunicación full-duplex (audio bidireccional simultáneo en el que el agente puede escuchar y hablar al mismo tiempo), por lo que el agente puede responder sin tener que esperar a que se respete estrictamente el turno de palabra.
Configuración del entorno del agente de voz Grok
Para crear un agente de voz con Grok, es necesario combinarlo con LiveKit, una plataforma WebRTC de código abierto. Grok proporciona el modelo de IA conversacional, mientras que LiveKit gestiona la infraestructura de audio en tiempo real que conecta a los usuarios con tu agente. Esta sección trata sobre la configuración de ambos servicios.
Configuración de Grok
Visita console.x.ai y crea una cuenta utilizando la autenticación X, correo electrónico, Google o Apple. La consola xAI requiere créditos prepagados antes de que puedas realizar llamadas a la API. Compra créditos a través de la sección Facturación.
Con créditos en tu cuenta, ve a Claves API y genera una nueva clave. La consola muestra la clave una sola vez, así que cópiala inmediatamente y guárdala en un lugar seguro. Si lo pierdes, tendrás que generar un duplicado y actualizar tus aplicaciones. Para obtener una descripción más detallada del ecosistema API de xAI, consulta el tutorial de la API Grok 3.
Configuración de LiveKit
LiveKit es una infraestructura WebRTC para audio y vídeo en tiempo real. Gestiona la capa de transporte de audio que Grok necesita para conectarse con los usuarios. Al crear un agente de voz, LiveKit gestiona las salas donde tienen lugar las conversaciones, dirige los flujos de audio entre los participantes y proporciona la infraestructura de implementación. El marco LiveKit Agents envuelve esta complejidad, permitiéndote centrarte en el comportamiento del agente mientras se encarga de la gestión de la conexión, la codificación de audio y la detección de turnos.
El marco es compatible con múltiples proveedores de IA, incluido xAI. Incluye un entorno de pruebas accesible a través de una interfaz web, que podrás utilizar para validar tu agente antes de implementarlo.
Regístrate en nube.livekit.io. El nivel gratuito proporciona recursos suficientes para el desarrollo y las pruebas. Crea un proyecto a través del panel de control. Ve a Configuración y, a continuación, a Claves API. Copia tres credenciales: LIVEKIT_URL (el punto final WebSocket de tu proyecto), LIVEKIT_API_KEY (el identificador público) y LIVEKIT_API_SECRET (la clave de autenticación privada). Estas credenciales autentican tu código de agente con tu proyecto de LiveKit en la nube.
Instalación de dependencias y configuración
Instala los paquetes necesarios:
uv add "livekit-agents[xai,openai]>=1.3.10" python-dotenvEsto instala el marco de agentes LiveKit con el complemento xAI y las dependencias de OpenAI (el complemento xAI se basa en la compatibilidad con la API en tiempo real de OpenAI), además de python-dotenv para la gestión de variables de entorno.
Crea un archivo .env en la raíz de tu proyecto:
XAI_API_KEY=xai-YourActualKeyHere
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIYourKeyHere
LIVEKIT_API_SECRET=YourSecretHereReemplaza los valores de marcador de posición con tus credenciales reales. Carga estas credenciales en tu código Python:
from dotenv import load_dotenv
load_dotenv()Esto hace que las credenciales estén disponibles tanto para las bibliotecas xAI como LiveKit. Añade .env a tu .gitignore para evitar fugas de credenciales en el control de versiones.
Creación de tu primer agente de voz Grok
Una vez configurado tu entorno, puedes crear un agente de voz operativo. Comienza con las importaciones y la clase de agente en un nuevo archivo llamado agent.py:
from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from dotenv import load_dotenv
load_dotenv()
class ResearchAssistant(Agent):
def __init__(self):
super().__init__(
instructions="You are a research assistant who helps users find information.",
)Tu subclase Agent solo contiene las instrucciones que determinan cómo responde el agente. Funcionan como un aviso del sistema, indicando al agente qué papel debe desempeñar. La configuración real del modelo va en otro lugar.
A continuación, configura el servidor y el controlador de conexión:
server = AgentServer()
@server.rtc_session()
async def entrypoint(ctx: JobContext):
await ctx.connect()
session = AgentSession(
llm=realtime.RealtimeModel(voice="ara"),
)
await session.start(
room=ctx.room,
agent=ResearchAssistant(),
)El decorador ` @server.rtc_session() ` le indica a LiveKit que ejecute tu función de punto de entrada cada vez que alguien se conecte. En el interior, AgentSession toma la configuración del modelo, incluyendo cuál de las siete voces de Grok utilizar (Ara, Eve, Leo, Sal, Rex, Mika o Valentin). Cuando se ejecuta session.start(), conecta tu agente a la sala LiveKit donde tiene lugar la conversación.
Las conversaciones de voz implican esperar la entrada y salida de audio sin congelar el programa, por lo que la función utiliza async def y await para gestionar estas operaciones de forma simultánea.
Por último, añade el punto de entrada:
if __name__ == "__main__":
cli.run_app(server)Ejecuta tu agente en modo de desarrollo:
uv run agent.py devLa terminal muestra la secuencia de inicio: inicialización del trabajador, servidor HTTP a la escucha en un puerto local y registro en tu proyecto LiveKit de la nube.
Para probar el agente, accede a tu panel de control de LiveKit Cloud en cloud.livekit.io. Selecciona tu proyecto y haz clic en la pestaña Sandbox en la barra lateral. Selecciona Web Voice Agent en las plantillas.
La página de la plantilla muestra una vista previa de la interfaz de voz junto con detalles sobre lo que incluye. Haz clic en el botón Crear entorno de pruebas.
En la ventana modal que aparece, puedes configurar una URL personalizada, habilitar funciones como la cámara y el uso compartido de pantalla, y ajustar la configuración de apariencia. Los valores predeterminados funcionan bien para las pruebas, así que haz clic en Crear y, a continuación, en Hecho.
De vuelta en la página Sandbox, tu nuevo entorno de pruebas aparecerá en Aplicaciones de Sandbox. Haz clic en Iniciar para abrirlo.
Haz clic en Iniciar llamada y concede los permisos de micrófono cuando se te soliciten. Observa el terminal para ver este mensaje de registro, que indica que el agente está listo para recibir audio:
DEBUG livekit.agents start reading stream {"participant": "...", "source": "SOURCE_MICROPHONE", ...}Después de que aparece este mensaje, las respuestas llegan rápidamente.
Cuando preguntas algo a lo que el agente no puede acceder (como el tiempo actual en una ciudad concreta), te explica sus limitaciones en lugar de inventarse cosas.
Cómo añadir herramientas a tus agentes de voz Grok
El agente básico puede mantener una conversación, pero no tiene forma de buscar información. La llamada a herramientas permite a Grok ejecutar funciones durante la conversación y hablar sobre los resultados. Puedes utilizar las herramientas integradas de xAI o definir las tuyas propias.
Uso de herramientas integradas
El complemento xAI incluye WebSearch para consultas web generales y XSearch para buscar publicaciones en X. Importadlos y pasadlos a AgentSession:
from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import WebSearch, XSearch
from dotenv import load_dotenv
load_dotenv()
class ResearchAssistant(Agent):
def __init__(self):
super().__init__(
instructions="""You are a research assistant with access to web search and X search.
- Use web search for general queries and current information
- Use X search when users ask about posts or what people are saying on X/Twitter
Always mention your sources when providing information.""",
)
server = AgentServer()
@server.rtc_session()
async def entrypoint(ctx: JobContext):
await ctx.connect()
session = AgentSession(
llm=realtime.RealtimeModel(voice="ara"),
tools=[
WebSearch(),
XSearch(),
],
)
await session.start(
room=ctx.room,
agent=ResearchAssistant(),
)
if __name__ == "__main__":
cli.run_app(server)El parámetro tools acepta una lista de objetos de herramienta. Ejecuta el agente y pruébalo con preguntas como «¿Cuáles son las últimas noticias sobre la IA?» o «¿Qué opinan los usuarios sobre Grok en X?». Los registros del terminal pueden mostrar advertencias sobre funciones desconocidas de AI, como web_search_with_snippets o x_semantic_search, pero las herramientas devuelven la información actual independientemente de ello.
El audio full-duplex de Grok también se hace evidente cuando usas herramientas. Puedes interrumpir al agente mientras habla, y este se detendrá, escuchará y ajustará su respuesta. Esto hace que las conversaciones parezcan menos robóticas que los sistemas que requieren esperar a que el agente termine antes de hablar.
Añadir herramientas personalizadas
Las herramientas integradas cubren los casos de uso más comunes, pero definir tus propias herramientas te permite controlar los parámetros, la gestión de errores y las API que se deben invocar. En esta sección se muestra cómo crear herramientas personalizadas utilizando el punto final de búsqueda de Firecrawl, que ofrece opciones de filtrado como limit, lang y country que la búsqueda web integrada no muestra.
Regístrate en firecrawl.dev. El nivel gratuito incluye 500 créditos y no requiere tarjeta de crédito. Instala el SDK y añade tu clave a .env:
uv add firecrawl-pyFIRECRAWL_API_KEY=fc-your-key-hereLas herramientas personalizadas son métodos decorados con @function_tool(). Actualiza las importaciones en search_agent.py:
from livekit.agents import (
Agent,
AgentSession,
AgentServer,
JobContext,
cli,
function_tool,
RunContext,
)
from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import XSearch
from firecrawl import FirecrawlApp
from dotenv import load_dotenv
import os
load_dotenv()Las adiciones son function_tool para el decorador, RunContext, que se pasa a las funciones de la herramienta, y FirecrawlApp para el cliente Firecrawl. Se ha eliminadoWebSearch, ya que la herramienta personalizada lo sustituye.
Define la herramienta como un método en tu clase de agente:
class ResearchAssistant(Agent):
def __init__(self):
super().__init__(
instructions="""You are a research assistant with access to web search and X search.
- Use Firecrawl search for general queries and current information
- Use X search when users ask about posts or what people are saying on X/Twitter
Always mention your sources when providing information.""",
)
self.firecrawl = FirecrawlApp(api_key=os.getenv("FIRECRAWL_API_KEY"))
@function_tool()
async def search_web(
self,
context: RunContext,
query: str,
) -> dict:
"""Search the web for current information using Firecrawl.
Args:
query: The search query
"""
result = self.firecrawl.search(query, limit=3)
return {
"results": [
{
"title": item.title,
"url": item.url,
"description": item.description,
}
for item in result.web
]
}Grok lee la cadena de documentación para comprender qué hace la herramienta. Cuando preguntas «¿Cuál es el tipo de cambio actual entre el dólar estadounidense y el euro?», Grok extrae la consulta, llama a tu función e incorpora los resultados en su respuesta.
Los métodos decorados con @function_tool() se registran automáticamente, por lo que debes eliminar WebSearch() de la lista de herramientas:
session = AgentSession(
llm=realtime.RealtimeModel(voice="ara"),
tools=[
XSearch(),
],
)Ejecuta el agente actualizado:
uv run search_agent.py devEl terminal muestra la ejecución de la herramienta:
DEBUG livekit.agents executing tool {
"function": "search_web",
"arguments": "{\"query\":\"current USD to EURO exchange rate\"}",
...
}
DEBUG livekit.agents tools execution completed {...}En mis pruebas, Firecrawl arrojó resultados en unos dos segundos. Puedes combinar varias herramientas personalizadas con herramientas integradas en el mismo agente. Un agente de atención al cliente, por ejemplo, podría utilizar XSearch junto con herramientas personalizadas como lookup_order() y check_inventory(), que se conectan a bases de datos internas.
Personalización de la detección de giros
La configuración predeterminada de detección de turnos funciona bien en conversaciones típicas. Los ajustes son necesarios cuando el entorno o el comportamiento de los usuarios difieren de lo habitual. Una sala ruidosa puede hacer que el agente responda a los sonidos de fondo, mientras que un usuario que hace una pausa para ordenar sus ideas puede verse interrumpido antes de terminar.
from livekit.plugins.xai import realtime
from openai.types.beta.realtime.session import TurnDetection
session = AgentSession(
llm=realtime.RealtimeModel(
voice="ara",
turn_detection=TurnDetection(
type="server_vad",
threshold=0.5,
prefix_padding_ms=300,
silence_duration_ms=200,
),
),
)El parámetro « threshold » establece el volumen que debe tener el audio para que se considere voz, en un rango de 0,0 a 1,0. Aumentar este valor a 0,7 o más ayuda en entornos ruidosos donde, de otro modo, los sonidos de fondo podrían desencadenar respuestas.
El parámetroprefix_padding_ms determina la cantidad de audio que se capturará antes del inicio detectado del habla. El valor predeterminado de 300 ms evita que se corte la primera sílaba. Aumenta este valor si los usuarios informan de que se cortan sus primeras palabras.
El parámetro « silence_duration_ms » controla cuánto tiempo espera el agente después de que dejes de hablar antes de responder. A 200 ms, las conversaciones se perciben como receptivas. Aumentar este valor a 400 o 500 ms permite adaptarse a los usuarios que hacen pausas en mitad de las frases o hablan a un ritmo más lento.
Para interfaces push-to-talk o sistemas de telefonía en los que necesitas un control explícito sobre el flujo de la conversación, desactiva la detección automática de giros:
session = AgentSession(
llm=realtime.RealtimeModel(
voice="ara",
turn_detection=None,
),
)A continuación, el agente espera una señal programática antes de responder, en lugar de escuchar el silencio.
Implementación de Grok Voice Agent en producción
El modo de desarrollo vincula el agente a tu máquina local. Para una implementación de producción que funciona las 24 horas del día, los 7 días de la semana, y se adapta a la demanda, LiveKit en la nube aloja tu agente en su infraestructura.
Configuración para la implementación
La CLI de LiveKit detecta el tipo de proyecto a través de los archivos de dependencia. Crea un archivo requirements.txt en tu directorio de agente:
livekit-agents[xai,openai]>=1.3.10
python-dotenv>=1.2.1
firecrawl-py>=4.12.0Crea un archivo aparte para los secretos de producción. LiveKit en la nube proporciona automáticamente LIVEKIT_URL, LIVEKIT_API_KEY y LIVEKIT_API_SECRET, por lo que solo necesitas incluir tus otras claves API:
XAI_API_KEY=xai-your-key-here
FIRECRAWL_API_KEY=fc-your-key-hereGuarda esto como « .env.production » y añádelo a «.gitignore ».
Implementación del agente
Autentifica la CLI con tu cuenta de LiveKit de la nube:
lk cloud authEsto abre un navegador para vincular tu CLI a tu proyecto. Una vez autenticado, implementa el agente:
lk agent create --secrets-file .env.productionLa CLI registra tu agente, genera un archivo Dockerfile, crea la imagen del contenedor y la implementa en la nube de LiveKit. Los registros se transmiten a tu terminal cuando se inicia el agente:
{"message": "registered worker", "level": "INFO", "name": "livekit.agents", "url": "https://your-project.livekit.cloud", "region": "Germany 2", ...}Comprueba el estado de la implementación:
lk agent status┌─────────────────┬─────────────────┬────────────┬─────────┬────────┬─────────┬───────────┐
│ ID │ Version │ Region │ Status │ CPU │ Mem │ Replicas │
├─────────────────┼─────────────────┼────────────┼─────────┼────────┼─────────┼───────────┤
│ CA_AAVy5WbUYpmA │ v20260109102531 │ eu-central │ Running │ 0m / 2 │ 0 / 4GB │ 0 / 1 / 1 │
└─────────────────┴─────────────────┴────────────┴─────────┴────────┴─────────┴───────────┘Cómo acceden los usuarios a tu agente
La URL que aparece en los registros de implementación (https://your-project.livekit.cloud) es el backend de WebSocket, no una interfaz de usuario. Los usuarios interactúan con tu agente a través de una interfaz que se conecta a este backend.
El entorno de pruebas que creaste anteriormente sirve para este propósito. Ve al panel de control de LiveKit, abre la sección Sandbox y copia la URL de tu sandbox. Esta URL es de acceso público y funciona sin necesidad de autenticación. Compártelo con los usuarios y podrán empezar a hablar con tu agente inmediatamente.
Para disfrutar de una experiencia personalizada, personaliza la apariencia del entorno de pruebas en el panel de control (logotipo, colores, texto de los botones) o crea tu propia interfaz utilizando el SDK de JavaScript de LiveKit.
Gestión de implementaciones
Ve los registros en tiempo real desde tu agente implementado:
lk agent logsImplementa las actualizaciones después de modificar tu código:
lk agent deploy --secrets-file .env.productionLiveKit utiliza implementaciones continuas. Las nuevas instancias gestionan las sesiones recientes, mientras que las instancias existentes completan sus conversaciones activas, por lo que las actualizaciones no provocan tiempo de inactividad.
Vuelve a una versión anterior si algo falla:
lk agent rollbackEl agente implementado se ejecuta independientemente de tu máquina local. Cierra tu terminal, apaga tu ordenador y el agente seguirá respondiendo a los usuarios. LiveKit en la nube se encarga del escalado, por lo que los picos de tráfico activan automáticamente instancias adicionales.
Costes de implementación
El funcionamiento de un agente de voz Grok en producción implica dos costes: la API de xAI y el alojamiento de LiveKit.
xAI cobra 0,05 dólares por minuto de conversación de voz. LiveKit en la nube cobra 0,01 $ por minuto de tiempo de sesión del agente. En conjunto, se espera aproximadamente 0,06 dólares por minuto cuando tu agente esté atendiendo activamente a los usuarios.
El nivel gratuito de LiveKit (plan Build) incluye 1000 minutos de sesión de agente al mes sin necesidad de tarjeta de crédito. Esto cubre unas 16 horas de conversación, suficientes para pruebas y aplicaciones con poco tráfico. Los planes de pago comienzan en 50 $ al mes, con 5000 minutos incluidos y límites de concurrencia más altos.
El agente no cuesta nada cuando está inactivo. Los cargos solo se aplican durante las conversaciones activas, por lo que una implementación que permanece inactiva durante la noche no incurre en gastos de LiveKit. La facturación de xAI sigue el mismo patrón, midiendo solo el uso real de la API. A lo largo de mis experimentos mientras escribía este artículo, gasté un total de 78 centavos en xAI, con LiveKit cubierto por su nivel gratuito.
Conclusión
Ahora tienes un agente de voz que escucha, piensa y responde. El agente se conecta a datos en tiempo real a través de herramientas, ajusta su comportamiento de escucha a diferentes entornos y se ejecuta en una infraestructura que se adapta sin intervención manual.
Los patrones de código que se tratan aquí se extienden a otros casos de uso. Cambia las instrucciones para los asistentes de investigación por las directrices de atención al cliente y añade herramientas que consulten tu base de datos de pedidos. Crea un tutor de idiomas que busque frases de ejemplo. Crea una interfaz de voz para tu API existente.
xAI tiene previsto lanzar terminales independientes de conversión de texto a voz y de voz a texto, lo que abrirá las puertas a arquitecturas híbridas en las que se podrán combinar las capacidades de voz de Grok con otros modelos lingüísticos. Por ahora, la API del agente de voz gestiona todo el proceso.
La documentación de LiveKit Agents cubre características adicionales como traspasos entre múltiples agentes y persistencia de sesiones. La documentación de xAI profundiza en los formatos de audio y las funciones empresariales.